Single payments: integrate and test

A single payment goes to the bank over its API, one payment per request. To send many payments in one file instead, see Batch payments: integrate and test. For the statuses and webhooks, see Single payment flow.

Create a paymentCopy Anchor Link

Send Create a Payment (POST /v1/payments). Add an Idempotency-Key header, so you can retry it safely (see Idempotency).

This example is a DBS Singapore FAST payment. The fields a payment needs depend on the bank and the payment type: look them up in your bank's guide under Bank payment rules.

{
  "type": "FAST",
  "amount": 150000,
  "currency": "SGD",
  "senderAccountId": "intacc_0H3BQY9BK1FCG",
  "senderAccountCurrency": "SGD",
  "customerReference": "INV-20260901-001",
  "paymentDetails": "Payment for invoice INV-20260901-001",
  "receiver": {
    "name": "Chan Tai Man",
    "bank": "OCBCSGSGXXX",
    "bankAccountNumber": "7654321098"
  }
}

• amount is in minor units: 150000 is 1,500.00 SGD. See Minor units format.
• senderAccountCurrency is required when the sender account holds more than one currency in Acme. Test accounts usually hold two, so send it in test mode.
• customerReference is optional. Acme generates one when you leave it out.
• For a PAYNOW or other proxy payment, send receiver.proxyType and receiver.proxyValue instead of a bank account. Your bank's guide lists which fields each type takes.

ResponseCopy Anchor Link

{
  "id": "pymt_0J7Q2D4K9RXM3",
  "type": "FAST",
  "amount": 150000,
  "currency": "SGD",
  "customerReference": "INV-20260901-001",
  "senderAccountId": "intacc_0H3BQY9BK1FCG",
  "receiver": {
    "name": "Chan Tai Man",
    "bank": "OCBCSGSGXXX",
    "bankAccountNumber": "7654321098"
  },
  "paymentDetails": "Payment for invoice INV-20260901-001",
  "currencyExchange": { "fxContractId": null },
  "senderAccountCurrency": "SGD",
  "status": "COMPLETED",
  "resultCode": null,
  "bankReference": null,
  "bankReferences": {},
  "createdAt": "2026-09-01T02:15:32.418Z",
  "updatedAt": "2026-09-01T02:15:33.102Z"
}

• status is what the bank has said by the time Acme answers: PROCESSING, SUBMITTED, COMPLETED or FAILED. Some banks answer at once, others later. Follow the payment with webhooks or Get a Payment until it is COMPLETED or FAILED.
• A 200 with FAILED usually means the bank rejected the payment during the request. resultCode says why, and underlyingErrorMessage holds the bank's reason when it gives one.
• With Acme maker-checker, the payment is PENDING_APPROVAL and is not sent to the bank yet. The create response has no review; Get a Payment returns it.

ValidationCopy Anchor Link

Acme checks the payment before it sends it to the bank. Every payment must:

• Have an amount and a senderAccountId.
• Use a sender account of your organization, in the mode of your API key, that your API key may pay from.
• Give senderAccountCurrency, one of the account's currencies, when the account holds more than one.

Always send type, currency and receiver too. DBS answers 400 when one is missing, but some banks answer 500.

Each bank adds its own rules: which types it supports, which receiver fields are required or not allowed, and field lengths and characters. Your bank's guide lists them under Bank payment rules.

Possible errorsCopy Anchor Link

For the 4xx, 501 and 503 answers below, the payment was not sent to the bank. After a 500, check before you retry.

Example 400 responseCopy Anchor Link

{
  "errorCode": "INVALID_REQUEST_PARAMETER",
  "errorMessage": "receiver.bankAccountNumber: must be provided"
}

• A single payment reports one failing field at a time. Fix it and send again to see the next one.
• A 400 for the sender account's currency has a fixed message, for example Sender account has multiple currencies. Please specify one to use in senderAccountCurrency.

If you get no response at all (a timeout), send the same request again (the same body, byte for byte) with the same Idempotency-Key within an hour. You get the original answer, and no second payment is made. Acme saves every answer except 401, 403, 429 and a maintenance 503, so a retry with the same key returns the saved answer, and its status is the one at that time: call Get a Payment for the latest one.

Test modeCopy Anchor Link

Use your test API key to try your integration before going live. In test mode, Acme checks the payment with the same rules as in live mode, then simulates the bank instead of sending it. The exception is the banks that cannot be tested yet, listed below. Test mode has no maintenance windows, so it never answers 503.

StepsCopy Anchor Link

Test account numbersCopy Anchor Link

The values are matched on receiver.bankAccountNumber only, not on receiver.iban or receiver.proxyValue. Any receiver bank works.

By bankCopy Anchor Link

• A proxy payment fails only if it also carries a test bankAccountNumber, which some banks' rules do not allow.
• For other test values, such as for direct debit and hosted payments, see Test mode values.