1. Incoming real-time payment

1.1. Receive an incoming real-time 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: Real-time 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:pending_confirmation

alt Customer system confirms or reject the payment
  C1 ->> M: POST /incoming_payments/{id}/(accept|reject)
else Mambu payments confirms or reject the payment based on payment validations
  M --> M: Payment validations
end
M ->> C2: Send ISO 20022 pacs.002 Payment status report
M ->> C1: Send webhook event<br/>incoming_payment:confirmed|rejected
C2 ->> C2: Validate pacs.002 against XSD schema
C2 ->> PBCH: Send Payment status report

opt Only if payment is accepted
  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 status
  M ->> C1: Send webhook incoming_payment:received
end
 

1.2. Receive and respond to a recall of an incoming real-time 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 real-time 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

2. Outgoing real-time payment

2.1. Send an outgoing real-time 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 real-time payment

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
end

2.2. Send a recall of an outgoing real-time 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 real-time 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