Guides
Start typing to search…
  1. Payments
  2. ISO 20022 message-based integration
  3. ISO 20022 message-based integration flows

Credit transfer / RTGS payments

Learn how to integrate credit transfer / RTGS payments using Mambu Payments (formerly Numeral)

1. Incoming credit transfer / RTGS payment

1.1. Receive an incoming credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house


PBCH ->> C2: Credit transfer/RTGS payment
C2 ->> C2: Format ISO 20022 pacs.008 FI to FI credit transfer 
C2 ->> M: Send pacs.008 to SFTP / API
M ->> M: Validate pacs.008 FI to FI credit transfer against XSD schema
M ->> M: Parse pacs.008 FI to FI credit transfer
M ->> M: Create incoming payment<br/>with direction = credit
M ->> C1: Send webhook event<br/>incoming_payment:received

1.2. Return an incoming credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An incoming credit transfer/RTGS payment has been received

C1 ->> M: POST /returns
M ->> M: Create return
M ->> C2: Send ISO 20022 pacs.004 Payment return
M ->> C1: Send webhook events<br/>return:sent<br/>incoming_payment:pending_return
C2 ->> C2: Validate pacs.004 against XSD schema
C2 ->> PBCH: Send return

PBCH ->> C2: Return payment status report
C2 ->> C2: Format ISO 20022 pacs.002 Payment status report
C2 ->> M: Send pacs.002 to SFTP / API
M ->> M: Validate pacs.002 Payment status report against XSD schema
M ->> M: Parse pacs.002 Payment status report
M ->> M: Update return status
M ->> C1: Send webhook events<br/>return:executed<br/>incoming_payment:returned

1.3. Receive and respond to a recall of an incoming credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An incoming credit transfer/RTGS payment has been received

PBCH ->> C2: Recall payment
C2 ->> C2: Format ISO 20022 pacs.056 FI to FI payment cancellation request 
C2 ->> M: Send pacs.056 to SFTP / API
M ->> M: Validate  pacs.056 FI to FI payment<br/>cancellation request against XSD schema
M ->> M: Parse pacs.056 FI to FI payment<br/>cancellation request
M ->> M: Create return request
M ->> C1: Send webhook events<br/>return_request:received<br/>incoming_payment:pending_return

Note left of C1: Later

alt Recall denied
  C1 ->> M: POST /return_requests/{id}/deny
  M ->> C2: Send ISO 20022 camt.029 negative response to recall
  M ->> C2:Send webhook events<br/>return_request:denied<br/>incoming_payment:return_denied
  C2 ->> C2: Validate camt.029 against XSD schema
  C2 ->> PBCH: Send recall response
else Recall accepted
  C1 ->> M: POST /return_requests/{id}/accept
  M ->> M: Create return
  M ->> C2: Send ISO 20022 pacs.004 positive response to recall
  M ->> C1:Send webhook event<br/>return:sent
  C2 ->> C2: Validate camt.004 against XSD schema
  C2 ->> PBCH: Send recall response
  
  PBCH ->> C2: Return payment status report
  C2 ->> C2: Format ISO 20022 pacs.002 Payment status report
  C2 ->> M: Send pacs.002 to SFTP / API
  M ->> M: Validate pacs.002 Payment status report against XSD schema
  M ->> M: Parse pacs.002 Payment status report
  M ->> M: Update status
  M ->> C1: Send webhook events<br/>return:executed<br/>return_request:accepted<br/>incoming_payment:returned
end

1.4. Receive a payment modification request of an incoming credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An incoming credit transfer/RTGS payment has been received

PBCH ->> C2: Payment modification request
C2 ->> C2: Format ISO 20022 pacs.087 FI to FI payment modification request 
C2 ->> M: Send pacs.087 to SFTP / API
M ->>M: Validate  pacs.087 FI to FI payment<br/>modification request against XSD schema
M ->>M: Parse pacs.087 FI to FI payment<br/>modification request
M ->>M: Create claim
M ->>M: Send webhook event<br/>claim:received

Note left of C1: Later

C1 ->> M: POST /claims/{id}/(accept|reject)
M ->> C2: Send ISO 20022 camt.029 Resolution of investigation
M ->> C2:Send webhook event<br/>claim:accepted | claim:rejected
C2 ->> C2: Validate camt.029 against XSD schema
C2 ->> PBCH: Send investigation response

1.5. Receive an investigation request on an incoming credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

PBCH ->> C2: Payment investigation request
C2 ->> C2: Format ISO 20022 pacs.028 FI to FI payment investigation request 
C2 ->> M: Send pacs.028 to SFTP / API
M ->> M: Validate  pacs.028 FI to FI payment<br/>investigation request against XSD schema
M ->> M: Parse pacs.028 FI to FI payment<br/>investigation request
M ->> M: Create inquiry
M ->> C1: Send webhook event<br/>inquiry:received

alt Inquiry on a recall
  Note over M, PBCH: Same flow as the incoming recall response
else Inquiry on a payment modification request
  Note over M, PBCH: Same flow as the incoming payment modification request
end

2. Outgoing credit transfer / RTGS payment

2.1. Send an outgoing credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

C1 ->> M: POST /payment_orders
M ->> M: Create payment order<br/>with direction = credit
M ->> M: Validate payment
M ->> C1: Send webhook event<br/>payment_order:approved
Note over M: On predefined time and period
M ->> M: Batch payment
M ->> C2: Send ISO 20022 pacs.008 FI to FI credit transfer
M ->> C1: Send webhook event<br/>payment_order:sent
C2 ->> C2: Validate pacs.008 against XSD schema
C2 ->> PBCH: Send Credit Transfer / RTGS

loop 
  PBCH ->> C2: Payment status report
  C2 ->> C2: Format ISO 20022 pacs.002 Payment status report
  C2 ->> M: Send pacs.002 to SFTP / API
  M ->> M: Validate pacs.002 Payment status report against XSD schema
  M ->> M: Parse pacs.002 Payment status report
  M ->> M: Update payment status
  M ->> C1: Send webhook event<br/>payment_order:executed|rejected|pending
end

2.2. Receive an incoming credit transfer / RTGS payment return

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An outgoing credit transfer/RTGS payment has been executed

PBCH ->> C2: Send payment return
C2 ->> C2: Format ISO 20022 pacs.004 Payment return
C2 ->> M: Send pacs.004 to SFTP / API
M ->> M: Create return
M ->> C1: Send webhook events<br/>return:received<br/>payment_order:returned

2.3. Send a recall on an outgoing credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An outgoing credit transfer/RTGS payment has been executed

C1 ->> M: POST /return_requests
M ->> M: Create return request
M ->> C1: Send webhook events<br/>return_request:pending<br/>payment_order:pending_return
Note over M: On predefined time and period
M ->> M: Batch return requests
M ->> C2: Send ISO 20022 camt.056 FI to FI payment cancellation request
M ->> C1: Send webhook event<br/>return_request:sent
C2 ->> C2: Validate camt.056 against XSD schema
C2 ->> PBCH: Send recall

Note over PBCH: Later

alt Recall denied
  PBCH ->> C2: Send recall denied
  C2 ->> C2: Format ISO 20022 camt.029 Negative response to recall
  C2 ->> M: Send camt.029 to SFTP / API
  M ->> M: Update status
  M ->> C1: Send webhook events<br/>return_request:denied<br/>payment_order:return_denied
else Recall accepted
  PBCH ->> C2: Send recall accepted
  C2 ->> C2: Format ISO 20022 pacs.004 Positive response to recall
  C2 ->> M: Send pacs.004 to SFTP / API
  M ->> M: Create return
  M ->> C1: Send webhook event<br/>return:received  
  M ->> M: Update return request status
  M ->> C1: Send webhook event<br/>return_request:accepted
  M ->> M: Update payment order status
  M ->> C1: Send webhook event<br/>payment_order:returned
end

2.4. Send a payment modification request of an outgoing credit transfer / RTGS payment

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An outgoing credit transfer/RTGS payment has been executed

C1 ->> M: POST /claims
M ->> M: Create claim
M ->> C1: Send webhook event<br/>claim:created
Note over M: On predefined time and period
M ->> M: Batch claims
M ->> C2: Send ISO 20022 pacs.087 FI to FI payment<br/>modification request
M ->> C2: Send webhook event<br/>claim:sent
C2 ->> C2: Validate pacs.087 FI to FI payment<br/>modification request against XSD schema
C2 ->> PBCH: Send payment modification request

Note over PBCH: Later
PBCH ->> C2: Send investigation response
C2 ->> C2: Format ISO 200022 camt.029 Resolution of investigation
C2 ->> M: Send camt.029 to SFTP / API
M ->> M: Validate camt.029 against XSD schema
M ->> M: Parse camt.029
M ->> M: Update claim status
M ->> C1: Send webhook event<br/>claim:accepted|denied

2.5. Send an investigation request on an outgoing recall

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An outgoing credit transfer/RTGS payment recall was sent but no response has been received

C1 ->> M: POST /inquiries
M ->> M: Create inquiry
M ->> C1: Send webhook event<br/>inquiry:created
Note over M: On predefined time and period
M ->> M: Batch inquiries
M ->> C2: Send ISO 20022 pacs.028 FI to FI payment<br/>status request
M ->> C1: Send webhook event<br/>inquiry:sent
C2 ->> C2: Validate pacs.028 FI to FI payment<br/>status request against XSD schema
C2 ->> PBCH: Send payment status request

Note over C1, PBCH: Same flow as the outgoing recall response

2.6. Send an investigation request on a payment modification request

sequenceDiagram
autonumber
participant C1 as Customer<br/>API
box
  participant M as Mambu Payments
  participant C2 as Customer<br/>ISO
end
participant PBCH as Partner bank / clearing house

Note over C1, PBCH: An outgoing credit transfer/RTGS payment claim was sent but no response has been received

C1 ->> M: POST /inquiries
M ->> M: Create inquiry
M ->> C1: Send webhook event<br/>inquiry:created
Note over M: On predefined time and period
M ->> M: Batch inquiries
M ->> C2: Send ISO 20022 pacs.028 FI to FI payment<br/>status request
M ->> C1: Send webhook event<br/>inquiry:sent
C2 ->> C2: Validate pacs.028 FI to FI payment<br/>status request against XSD schema
C2 ->> PBCH: Send payment status request

Note over C1, PBCH: Same flow as the outgoing payment modification request response

Updated about 10 hours ago

What's next