Update to incoming direct debit payment lifecycle

Starting from December 8, 2025, a new status and related transitions will be added to the lifecycle of incoming direct debit payments.

Until now, an incoming direct debit payment is transitioned from received to rejected when rejected before settlement. In some rare instances, it can happen that a rejection is itself rejected by the sponsor bank (e.g. due to missed cut-off or incorrect message format). When that happens, the payment is transitioned from rejected back to received. The related incoming_payment.received event could be misinterpreted as a new incoming payment.

To better manage this flow, we are introducing:

A new pending_rejection intermediary status
Two new incoming_payment.pending_rejection and incoming_payment.rejection_denied events

The pending_rejection status indicates that the rejection process has started. From pending_rejection, the payment can:

Transition to rejected and trigger an incoming_payment.rejection_denied event
Transition to received and trigger an incoming_payment.received event

From December 8, 2025, the lifecycle of incoming direct debit payments will be as follows:

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}/rejection
Mambu Payments ->> Mambu Payments: Switch payment status to <br/>pending_rejection
Mambu Payments -->> Customer: incoming_payments: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_payments:rejected
else Partner bank / CSM rejects
  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_payments:rejection_denied
end