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.

Payment status flowYou create a payment with POST /v1/payments. It starts as PROCESSING while Acme sends it to the bank. When the bank accepts it, it is SUBMITTED while the bank processes it straight through or holds it for your approvers in the bank's portal. It ends as COMPLETED or FAILED. Some banks never report that they accepted the payment, or give their final answer straight away, so the payment goes from PROCESSING to COMPLETED or FAILED without SUBMITTED.AT ACMEAT THE BANKFINALPayment createdPOST /v1/paymentsPROCESSINGSent, or with the bankBank acceptsSUBMITTEDBank is processing itWhile SUBMITTED, the bank:• processes it straight through(pre-authorised), or• holds it for your approvers inits portal (re-authorisation).COMPLETEDFAILEDBank confirmsBank rejectsFinal answer, no SUBMITTED stepFinal answer, no SUBMITTED stepFinal statusOnly some banks
Payment statuses. A thick border marks a final status. A dashed arrow is a step only some banks take.

The usual path:

PROCESSING → SUBMITTED → COMPLETED

Other paths:

  • The bank rejects the payment: PROCESSING or SUBMITTED → FAILED.
  • Some banks give their final answer straight away, so the payment goes from PROCESSING to COMPLETED or FAILED without SUBMITTED.
  • Some banks do not report that they accepted the payment, so it stays PROCESSING until their final answer.

Payment statuses

StatusWhere the payment isWhat it meansFinal?Webhook
PROCESSINGAcme or the bankAcme is sending it to the bank, or the bank has it but has not yet reported a result.NoNone
SUBMITTEDThe bankThe bank accepted it and is processing it. Acme is waiting for the final answer.NoNone
COMPLETEDThe bankThe bank confirmed the payment.Yespayments.succeeded
FAILEDThe bankThe bank rejected or returned the payment. resultCode says why.Yespayments.failed

If your organization uses Acme maker-checker, a payment can also be PENDING_APPROVAL, APPROVAL_REJECTED or APPROVAL_EXPIRED before it reaches PROCESSING.

  • COMPLETED and FAILED never 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 stays COMPLETED.
  • If the bank does not answer, the payment stays PROCESSING or SUBMITTED until Acme confirms the result.
  • If Acme marks a payment FAILED without 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 SUBMITTED with resultCode REQUEST_TIMEOUT while Acme confirms the result. This resultCode does 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.succeeded or payments.failed as the bank reports on the payments. One webhook can carry up to 100 payments under objects, as described in Payments in a batch. Each payment includes its id and the batchId of 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 payment id.

Record each payment id from the create response: no other response lists the payments in a batch. See Store each payment id.

Batch payment status flowA batch is created with POST /v1/payment-batches. It is PROCESSING while Acme prepares the file or waits to send it. When the file is sent, the batch is SUBMITTED. It is COMPLETED when every payment in it is completed or failed. It is FAILED when the bank rejects the whole file.AT ACMEAT THE BANKFINALBatch createdPOST /v1/payment-batchesPROCESSINGPreparing or waiting to sendFile sentSUBMITTEDBank is processing the fileCOMPLETEDFAILEDEvery payment resolvedWhole file rejected
Batch statuses. A thick border marks a final status. Each payment in the batch also has its own status.
Batch statusWhat it meansFinal?Webhook
PROCESSINGAcme is preparing the file, or waiting to send it.NoNone
SUBMITTEDAcme sent the file to the bank.Nopayment-batches.submitted
COMPLETEDEvery payment in the batch is COMPLETED or FAILED.YesNone
FAILEDThe bank rejected the whole file. Every payment in it is FAILED.Yespayment-batches.rejected

Payments in a batch:

  • PROCESSING: each payment starts here while Acme prepares the file. A 200 answer to the create request means Acme created the batch, not that the bank has made the payments. If a batch stays PROCESSING for 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 a SUBMITTED payment 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 stays SUBMITTED in Acme, and you can confirm it in the bank's portal or on your bank statement.
  • COMPLETED or FAILED: each payment moves here as the bank reports on it, and is included in a payments.succeeded or payments.failed webhook. For a failed payment, underlyingErrorMessage holds the bank's reason when the bank provides one. If the bank rejects the whole file, the batch carries the reason.
  • A COMPLETED batch can contain FAILED payments. 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.

  1. You send 10 payments, 2 of them with an invalid bank code. Acme answers 400 and creates nothing.
  2. You correct the 2 payments and send the batch again. Acme answers 200. The batch and its 10 payments are PROCESSING, and the response lists each payment id.
  3. Acme sends the file to the bank. The batch and its payments move to SUBMITTED, and Acme sends payment-batches.submitted.
  4. 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 sends payment-batches.rejected.
  5. The bank checks each payment at level 2 and rejects 2 other payments. Those payments move to FAILED and are reported in payments.failed.
  6. The bank accepts the remaining 8 payments at level 3, its final result. Those payments move to COMPLETED and are reported in payments.succeeded.
  7. 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.

Acme maker-checker flowA maker API key creates a payment with POST /v1/payments. The payment is PENDING_APPROVAL at Acme. A checker API key approves it with POST /v1/payments/id/approve, and it moves to PROCESSING and continues in the standard flow. A checker API key rejects it with POST /v1/payments/id/reject, and it is APPROVAL_REJECTED. If nobody acts before review.expiresAt, it is APPROVAL_EXPIRED. Rejected and expired payments are never sent to the bank.AT ACME, BEFORE THE BANKFINALMaker API keyPOST /v1/paymentsPENDING_APPROVALWaiting for a checkerChecker API key approvesPOST /v1/payments/{id}/approvePROCESSINGContinues the standard flowChecker API key rejectsPOST /v1/payments/{id}/rejectNobody acts before review.expiresAtAPPROVAL_REJECTEDAPPROVAL_EXPIRED
Acme maker-checker. A thick border marks a final status. An approved payment continues in the single payment flow.

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 PROCESSING and follows the single payment flow.
  • review.expiresAt on 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.
StatusWhat it meansFinal?Webhook
PENDING_APPROVALWaiting for a checker key to approve or reject it.Nopayments.pending-approval
APPROVAL_REJECTEDA checker key rejected it. It was never sent to the bank.Yespayments.approval-rejected
APPROVAL_EXPIREDNobody approved it before review.expiresAt. It was never sent to the bank.Yespayments.approval-expired
PROCESSINGA checker key approved it, and Acme is sending it to the bank.NoNone (see payments.approved below)
  • payments.approved is sent once the checker approves. It carries the payment's status at that moment, which can already be past PROCESSING.
  • 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_APPROVAL until 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_EXPIRED if nobody at Acme decides within 24 hours.
  • Names Acme in its review object (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

LevelWhat the bank doesPossible Acme statusWebhook
Level 1: acceptanceReceives 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 statusReports 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

LevelWhat the bank doesPossible Acme statusWebhook
Level 1: file checksChecks 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 checksChecks 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 statusReports 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 FAILED and reported in payments.failed, but the batch is not FAILED and Acme sends no payment-batches.rejected.
  • A payment can be rejected at any level. A payment is completed only when the bank reports its final status.

On this page