Payment Statuses

Payment Statuses

When an outbound payment is made, it may transition through a variety of the statuses whilst it is being processed.

📘

Final State

You should only rely upon payments that are in a Final state.

If a payment is in a status marked as "Transient" then generally it is still processing. You should not act upon any payments where the state is still "Transient" as we are still processing the payment and the status will change.

In the live environment, if the payment is in a "Transient" state for a long period of time, the please contact our support team.

Success & Pending Statuses

Payment Status	Description	State
SUBMITTED	Request has been accepted - will go to internal validation.	Transient
VALIDATED	Request internally validated - request has been validated and now is queued to be sent to external payment systems.	Transient
PENDING_FOR_DATE	Request awaiting processing date.	Transient
PENDING_FOR_FUNDS	Request awaiting funds.	Transient
PROCESSED	Request processed and successfully sent to destination payment system.	Final
CANCELLED	Payment request has been cancelled.	Final

Error Statuses

📘

Error Information

Within the errors you get back on a payment status there can be more detail within each status which allow you to know more about why there was an error and, importantly, what you need to do to resolve and then retry the request.

For a list of statuses when payments fail or are returned see: here

Payment Status	Description	State
ER_INVALID	Failed internal validations - incorrect statuses/data like no funds, account inactive, no valid destination beneficiary etc. - Does not send a webhook when rejecting the approval of a payment.	Final
ER_EXTCONN	Issues with external system connectivity - will be retried by Modulr.	Transient
ER_EXTSYS	Rejected by external system	Final
ER_EXPIRED	Request has expired - Does not send a Webhook	Final
ER_GENERAL	General error, covering any other errors	Final
ER_BATCH	Rejected due to strict processing of BatchRequest - Not relevant to single payments	Final

Approval Statuses

If a payment needs approval, in addition to the statuses specified above, the following approval statuses will be used:

Approval Status	Description
NOTNEEDED	Approval is not enabled or the payment does not need it.
PENDING	Approval needed.
APPROVED	Payment has been approved.
REJECTED	The payment was not approved.
DELETED	The payment was cancelled so approval deleted.

For a general overview on how you should handle Modulr api errors, including connectivity and REST http level errors, please read Error handling.

Approval & Payment Status Combinations

The below table outlines each approval status and respective possible payment statuses.

Approval Status	Description
NOTNEEDED	ER_INVALID, VALIDATED, PROCESSED, SUBMITTED, PENDING_FOR_DATE, PENDING_FOR_FUNDS
APPROVED	ER_INVALID, VALIDATED, PENDING_FOR_DATE, PENDING_FOR_FUNDS, PROCESSED, SUBMITTED
PENDING	PENDING_FOR_DATE, VALIDATED, SUBMITTED
REJECTED	ER_INVALID, SUBMITTED
DELETED	CANCELLED, SUBMITTED