Direct debit payments
Learn how to integrate direct debit payments using Mambu Payments (formerly Numeral)
1. Incoming direct debit payment
1.1. Receive an incoming direct debit 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: Incoming direct debit payment C2 ->> C2: Format ISO 20022 pacs.003 FI to FI customer direct debit C2 ->> M: Send pacs.003 to SFTP / API M ->> M: Validate pacs.003 FI to FI customer direct debit against XSD schema M ->> M: Parse pacs.003 M ->> M: Validate payments M ->> M: Create incoming_payment<br/>with direction = debit M ->> C1: Send webhook event<br/>incoming_payment:received
1.2. Receive an incoming direct debit payment cancellation
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 direct debit payment has been received and is still in pre-settlement period PBCH ->> C2: Incoming direct debit payment cancellation C2 ->> C2: Format ISO 20022 camt.056 FI to FI cancellation request C2 ->> M: Send camt.056 to SFTP / API M ->> M: Validate camt.056 FI to FI customer direct debit against XSD schema M ->> M: Parse camt.056 M ->> M: Cancel direct debit payment M ->> C1: Send webhook event<br/>incoming_payment:canceled M ->> M: Format ISO 20022 pacs.002 Payment status report M ->> C2: Send pacs.002 Payment status report
1.3. Receive an incoming direct debit payment reversal
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 direct debit payment has been settled PBCH ->> C2: Incoming direct debit payment reversal C2 ->> C2: Format ISO 20022 pacs.007 FI to FI payment reversal C2 ->> M: Send pacs.007 to SFTP / API M ->> M: Validate pacs.007 FI to FI payment reversal against XSD schema M ->> M: Parse pacs.007 M ->> M: Create return M ->> C1: Send webhook events<br/>return:received<br/>incoming_payment:returned
1.4. Reject an incoming direct debit 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 direct debit payment has been received and is still in pre-settlement period
C1 ->> M: POST /incoming_payments/{id}/reject
M ->> C2: Send ISO 20022 pacs.002 payment status report
M ->> C1: Send webhook event<br/>incoming_payment:pending_rejection
C2 ->> PBCH: Reject direct debit payment request
PBCH ->> C2: Reject direct debit payment response
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
M ->> C1: Send webhook event<br/>incoming_payment:rejected|rejection_denied
1.5. Return an incoming direct debit 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 direct debit payment has been settled
C1 ->> M: POST /incoming_payments/{id}/return
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 ->> PBCH: Direct debit payment return request
PBCH ->> C2: Direct debit payment return response
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
M ->> C1: Send webhook events<br/>return:executed|rejected<br/>incoming_payment:returned|return_denied
2. Outgoing direct debit payment
2.1. Send an outgoing direct debit 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 = debit 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.003 FI to FI customer direct debit M ->> C1: Send webhook event<br/>payment_order:sent C2 ->> C2: Validate pacs.003 against XSD schema C2 ->> PBCH: Send direct debit 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. Cancel an outgoing direct debit 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 direct debit payment has been accepted in pre-settlement period
C1 ->> M: POST /payment_orders/{id}/cancel
M ->> M: Cancel return request
M ->> C1: Send webhook event<br/>payment_order:canceled
Note over M: On predefined time and period
M ->> M: Batch cancellation request
M ->> C2: Send ISO 20022 camt.056 FI to FI payment cancellation request
C2 ->> C2: Validate camt.056 against XSD schema
C2 ->> PBCH: Send cancellation
2.3. Reverse an outgoing direct debit 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 direct debit payment has been settled C1 ->> M: POST /returns M ->> M: Create return M ->> C1: Send webhook event<br/>payment_order:pending_return Note over M: On predefined time and period M ->> M: Batch returns M ->> C2: Send ISO 20022 pacs.007 FI to FI payment reversal M ->> C1: Send webhook event<br/>return:sent C2 ->> C2: Validate pacs.007 against XSD schema C2 ->> PBCH: Send reversal 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:returned
2.4. Receive an outgoing direct debit payment rejection
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 direct debit payment has been accepted in pre-settlement period PBCH ->> C2: Reject direct debit payment 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 M ->> C1: Send webhook event<br/>payment_order:rejected
2.5. Receive a return of an outgoing direct debit 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 direct debit payment has been settled PBCH ->> C2: Return direct debit payment C2 ->> C2: Format ISO 20022 pacs.004 payment reversal C2 ->> M: Send pacs.004 to SFTP / API M ->> M: Validate pacs.004 payment reversal against XSD schema M ->> M: Parse pacs.004 M ->> C1: Send webhook event<br/>payment_order:returned
Updated about 10 hours ago
What's next