Incoming direct debit payment lifecycle

Incoming direct debit rejections now pass through a pending_rejection status before reaching rejected. This resolves an ambiguity where a rejection denied by a sponsor bank triggered an incoming_payment.received event indistinguishable from a new incoming payment.

What's new

pending_rejection status. Incoming direct debit payments enter this status when you call POST /incoming_payments/{id}/reject. From pending_rejection, the payment transitions to one of two outcomes:

Two new events. incoming_payment.pending_rejection is created when the rejection is submitted. incoming_payment.rejection_denied is created when the sponsor bank denies the rejection and replaces the previous incoming_payment.received event in this scenario.

What changed

Previously, rejecting an incoming direct debit transitioned the payment directly from received to rejected. If the sponsor bank denied the rejection (for example, due to a missed cutoff or incorrect message format), the payment reverted to received and created incoming_payment.received – identical to a new incoming payment event.

The new flow inserts pending_rejection as an intermediary status and uses incoming_payment.rejection_denied to distinguish a denied rejection from a new payment.

Migration

This change takes effect on 19 January 2026.

If your webhook handlers uses incoming_payment.received, check whether you need to handle incoming_payment.rejection_denied separately. Any payment that transitions from pending_rejection back to received will fire incoming_payment.rejection_denied instead of incoming_payment.received.

No changes are required if you do not reject incoming direct debit payments.

sequenceDiagram
autonumber
participant Customer
participant Mambu Payments
participant Bank as Partner bank / CSM

note over Customer, Bank: Prerequisite: incoming direct debit payment in received status
Customer ->> Mambu Payments: POST /incoming_payments/{id}/reject
Mambu Payments ->> Mambu Payments: Switch payment status to <br/>pending_rejection
Mambu Payments -->> Customer: incoming_payment.pending_rejection event
Mambu Payments ->> Bank: Send payment rejection<br/>e.g. pacs.002 RJCT
alt Partner bank / CSM accepts
  Bank ->> Mambu Payments: Payment rejection accepted<br/>e.g. pacs.002 ACCP
  Mambu Payments ->> Mambu Payments: Switch payment status to <br/>rejected
  Mambu Payments -->> Customer: incoming_payment.rejected
else Partner bank / CSM denies
  Bank ->> Mambu Payments: Payment rejection denied<br/>e.g. pacs.002 RJCT
  Mambu Payments ->> Mambu Payments: Switch payment status to <br/>received
  Mambu Payments -->> Customer: incoming_payment.rejection_denied
end