Payment lifecycle and statuses
Every status a payment or batch can have, where approval happens, and how banks report on a payment.
Every payment moves through a set of statuses, from the moment you create it to the bank's final answer. This page explains:
- The single payment flow and its statuses.
- The batch payment flow and its statuses.
- Approval in your bank's portal.
- Acme maker-checker, an optional approval step at Acme.
- How banks report on a payment, level by level.
To build and test an integration, with example requests, responses and errors, see Single payments: integrate and test and Batch payments: integrate and test.
Single payment flow
You create a single payment with Create a Payment (POST /v1/payments). There are two ways to follow its status:
- Webhooks. Acme sends an event to your endpoint when the payment completes or fails, and at each maker-checker step. See Webhooks and the payment events.
- Get a Payment. Fetch the payment with Get a Payment (
GET /v1/payments/{id}) at any time.
Not every status sends a webhook. For example, PROCESSING and SUBMITTED send none. The Webhook column in each status table shows which do.
The usual path:
PROCESSING → SUBMITTED → COMPLETED
Other paths:
- The bank rejects the payment:
PROCESSINGorSUBMITTED→FAILED. - Some banks give their final answer straight away, so the payment goes from
PROCESSINGtoCOMPLETEDorFAILEDwithoutSUBMITTED. - Some banks do not report that they accepted the payment, so it stays
PROCESSINGuntil their final answer.
Payment statuses
| Status | Where the payment is | What it means | Final? | Webhook |
|---|---|---|---|---|
PROCESSING | Acme or the bank | Acme is sending it to the bank, or the bank has it but has not yet reported a result. | No | None |
SUBMITTED | The bank | The bank accepted it and is processing it. Acme is waiting for the final answer. | No | None |
COMPLETED | The bank | The bank confirmed the payment. | Yes | payments.succeeded |
FAILED | The bank | The bank rejected or returned the payment. resultCode says why. | Yes | payments.failed |
If your organization uses Acme maker-checker, a payment can also be PENDING_APPROVAL, APPROVAL_REJECTED or APPROVAL_EXPIRED before it reaches PROCESSING.
COMPLETEDandFAILEDnever change. A payment that completed is never marked failed later, and the reverse.- With some banks, a payment can still come back after it is
COMPLETED, for example when the beneficiary's bank rejects it. The money returns as a separate credit on your bank statement, and the payment staysCOMPLETED. - If the bank does not answer, the payment stays
PROCESSINGorSUBMITTEDuntil Acme confirms the result. - If Acme marks a payment
FAILEDwithout a rejection from the bank, for example after an error or an answer Acme cannot read, the bank may still have made it. Contact Acme before you retry the payment. - A payment can stay
SUBMITTEDwithresultCodeREQUEST_TIMEOUTwhile Acme confirms the result. ThisresultCodedoes not mean the payment failed.
Batch payment flow
You create a batch payment with Create a Batch Payment (POST /v1/payment-batches). Acme sends the batch to the bank as one file. The batch and each payment in it have separate statuses.
You can follow these statuses in two ways:
- Webhooks. Acme sends a batch event when the file is sent or rejected. It also sends
payments.succeededorpayments.failedas the bank reports on the payments. One webhook can carry up to 100 payments underobjects, as described in Payments in a batch. Each payment includes itsidand thebatchIdof its batch. - Polling. Get a Batch Payment (
GET /v1/payment-batches/{id}) returns the batch status only. To poll a payment, call Get a Payment with the paymentid.
Record each payment id from the create response: no other response lists the payments in a batch.
See Store each payment id.
| Batch status | What it means | Final? | Webhook |
|---|---|---|---|
PROCESSING | Acme is preparing the file, or waiting to send it. | No | None |
SUBMITTED | Acme sent the file to the bank. | No | payment-batches.submitted |
COMPLETED | Every payment in the batch is COMPLETED or FAILED. | Yes | None |
FAILED | The bank rejected the whole file. Every payment in it is FAILED. | Yes | payment-batches.rejected |
Payments in a batch:
PROCESSING: each payment starts here while Acme prepares the file. A200answer to the create request means Acme created the batch, not that the bank has made the payments. If a batch staysPROCESSINGfor more than an hour, contact Acme. Do not send the batch again, as the payments may be made twice.SUBMITTED: each payment moves here when Acme sends the file. Do not send aSUBMITTEDpayment again. Some banks hold the file for approval in their portal, and some send no further status after approval or after payment. The payment then staysSUBMITTEDin Acme, and you can confirm it in the bank's portal or on your bank statement.COMPLETEDorFAILED: each payment moves here as the bank reports on it, and is included in apayments.succeededorpayments.failedwebhook. For a failed payment,underlyingErrorMessageholds the bank's reason when the bank provides one. If the bank rejects the whole file, the batch carries the reason.- A
COMPLETEDbatch can containFAILEDpayments. Check each payment's status, not only the batch status. - Batch payments do not go through Acme maker-checker.
Example: a batch of 10 payments
This example uses the three levels described in How banks report on a payment. The number of levels differs by bank.
- You send 10 payments, 2 of them with an invalid bank code. Acme answers
400and creates nothing. - You correct the 2 payments and send the batch again. Acme answers
200. The batch and its 10 payments arePROCESSING, and the response lists each paymentid. - Acme sends the file to the bank. The batch and its payments move to
SUBMITTED, and Acme sendspayment-batches.submitted. - The bank accepts the file at level 1. If the bank rejects the whole file instead, every payment moves to
FAILED, and Acme usually also sendspayment-batches.rejected. - The bank checks each payment at level 2 and rejects 2 other payments. Those payments move to
FAILEDand are reported inpayments.failed. - The bank accepts the remaining 8 payments at level 3, its final result. Those payments move to
COMPLETEDand are reported inpayments.succeeded. - No payment is waiting for the bank, so the batch moves to
COMPLETED. Acme sends no webhook for this.
When the bank changes a payment's date, Acme updates actualPaymentDate. When the bank reports a charge, Acme sets bankChargeAmount and bankChargeCurrency. Not every bank reports these.
Approval at the bank
Your bank can ask for approval in its own portal. This is agreed between you and your bank. There are two set-ups:
- Straight-through (pre-authorised). The bank processes the payment as soon as it receives it. Nobody approves it in the bank's portal.
- Re-authorisation. The bank holds the payment until your approvers approve it in the bank's portal.
While the bank holds the payment, Acme shows SUBMITTED, or PROCESSING for banks that do not report acceptance. When your approver rejects it in the portal, the payment moves to FAILED if the bank reports the rejection to Acme.
Some banks report on a payment only once, before your approvers act in their portal, and send no later status. Acme then shows COMPLETED once the bank accepts the payment, even if your approvers have not approved it yet. Confirm those payments in the bank's portal or on your bank statement.
Acme maker-checker
Most organizations do not use Acme maker-checker. If Acme has not set it up for you, your payments follow the single payment flow and you can skip this section.
Acme maker-checker is an optional approval step at Acme, before the payment goes to the bank. A payment made by a maker API key waits at Acme until a checker API key approves it. It is separate from approval at the bank, and you can use both.
How it works:
- Acme turns it on for your organization. The set-up names the maker API keys, the checker API keys, and the accounts it covers.
- If the set-up names no maker keys, every API key is a maker on the covered accounts.
- A payment created by a maker key on a covered account starts as
PENDING_APPROVAL. It is not sent to the bank. - A checker key approves it with Approve a Payment or rejects it with Reject a Payment.
- When the set-up names checker keys, only those keys can approve or reject.
- The checker key cannot be the key that made the payment.
- A payment prepared in the dashboard is approved in the dashboard, not with an API key.
- Approval sends the payment to the bank in the same call. The payment moves to
PROCESSINGand follows the single payment flow. review.expiresAton the payment is the approval deadline. The default is 7 days after the payment is created. A payment prepared in the dashboard has 24 hours.- Batch payments do not go through Acme maker-checker.
| Status | What it means | Final? | Webhook |
|---|---|---|---|
PENDING_APPROVAL | Waiting for a checker key to approve or reject it. | No | payments.pending-approval |
APPROVAL_REJECTED | A checker key rejected it. It was never sent to the bank. | Yes | payments.approval-rejected |
APPROVAL_EXPIRED | Nobody approved it before review.expiresAt. It was never sent to the bank. | Yes | payments.approval-expired |
PROCESSING | A checker key approved it, and Acme is sending it to the bank. | No | None (see payments.approved below) |
payments.approvedis sent once the checker approves. It carries the payment's status at that moment, which can already be pastPROCESSING.- A rejected or expired payment has no
resultCode. - See Maker-checker flow for the webhook payloads.
Payments Acme prepares for you
Acme sometimes makes a payment from one of your accounts itself, for example a small one to verify a bank connection when it goes live. Such a payment appears in the dashboard, in the API and in your webhooks like any other payment.
A LIVE payment Acme prepares:
- Waits in
PENDING_APPROVALuntil a second person at Acme approves or rejects it, never your checkers. Approving or rejecting it with your API key, or in the dashboard, is refused. - Moves to
APPROVAL_EXPIREDif nobody at Acme decides within 24 hours. - Names
Acmein itsreviewobject (requestedBy,approvedBy,rejectedBy), where your own payments name an API key or a person.
A TEST payment Acme prepares goes straight through, with no approval and no review.
How banks report on a payment
Acme maps every status a bank reports to an Acme status. Your integration only needs the Acme statuses and webhooks. A bank reports on a payment in levels: the early levels keep the payment in progress, and the bank's final status moves it to COMPLETED or FAILED.
Single payments
| Level | What the bank does | Possible Acme status | Webhook |
|---|---|---|---|
| Level 1: acceptance | Receives the payment, and accepts or rejects it. | PROCESSING until the bank answers. SUBMITTED when it accepts the payment. FAILED when it rejects the payment. | payments.failed for a rejected payment |
| Level 2: final status | Reports the final status of the payment. | COMPLETED or FAILED. | payments.succeeded or payments.failed |
Some banks give the final status in their first answer, so the payment goes straight to COMPLETED or FAILED. Some banks do not report acceptance, so the payment stays PROCESSING until the final status.
Batch payments
| Level | What the bank does | Possible Acme status | Webhook |
|---|---|---|---|
| Level 1: file checks | Checks the file as a whole. | SUBMITTED when the bank accepts the file. FAILED for every payment when the bank rejects the whole file. | payment-batches.rejected, and payments.failed for each payment, when the file is rejected |
| Level 2: payment checks | Checks each payment. Where the bank requires it, waits for your approvers in its portal. | SUBMITTED while each payment is accepted. FAILED for a payment the bank rejects. | payments.failed for a rejected payment |
| Level 3: final status | Reports the final status of each payment. | COMPLETED or FAILED. | payments.succeeded or payments.failed |
- Some banks combine these levels, and some report in more steps.
- Some banks report a rejection for each payment in a rejected file. Each payment is then
FAILEDand reported inpayments.failed, but the batch is notFAILEDand Acme sends nopayment-batches.rejected. - A payment can be rejected at any level. A payment is completed only when the bank reports its final status.