Acme logoAcme docs
GuidesAPI referenceChangelog

October 2026

Oct 23, 2026

API Reference: 400 Lists Only the Codes Each Endpoint Returns

  • Each endpoint's 400 now lists only the error codes that endpoint returns. Before, most listed the same 24 codes, including sign-in and OTP codes that the API never returns with a 400.
  • Most endpoints return INVALID_REQUEST_PARAMETER. List endpoints can also return INVALID_PAGINATION_LIMIT. Some endpoints can also return INVALID_OPERATION, when the request is valid but the action is not allowed (for example Create a Refund).
  • Create a Bank Payment File now shows paymentErrors on its 400, as Create a Batch Payment does.
  • Newly documented: the 400 of Close a Batch Payment (empty body), Approve a Payment and Delete a Virtual Account; and the cases that return a 400 with an empty body. The response bodies are unchanged.

Batch Payments: Error Responses Documented

  • Create a Batch Payment now lists the errors it returns, with what each means: 400 (with paymentErrors), 401, 403, 409, 429 and 503. The response bodies are unchanged.
  • On every endpoint, a 429 now lists only RATE_LIMIT_EXCEEDED. Before, it listed every error code of the API.
  • A badly formatted value, such as a date, now returns <field>: not a valid value instead of a general message. The general message, still used when Acme cannot read a request body for another reason, now reads "An unexpected error has occurred".
  • A saved batch is answered 200. Before, a rare failure after the batch was saved returned a 500, and a retry could create a second batch.
  • The Batch Payments guide explains each status after Acme accepts a batch. A COMPLETED batch can still contain FAILED payments.
  • The Idempotency guide says when to use a new key: after a 400, a fixed request needs one.

Affected pages:

Citibank: Structured Receiver Addresses (ISO 20022)

To meet Citibank's ISO 20022 address rules, each part of receiver.address now goes to the bank in its own field, with at most 2 address lines (line1, line2). Addresses that already fit the limits below need no change.

  • postalCode is now at most 16 characters (was 35). In Citibank Brazil, line1, line2, city and state are at most 35 each.
  • The check that the whole address fits in 3 lines of 35 characters is removed; each field is checked on its own.
  • country, when sent, must be a 2-letter ISO 3166-1 alpha-2 code (GB, not UK).
  • The guides now list each address field on its own row. Citibank Indonesia TT and ID_RTGS show city and country as mandatory, as validation already required, and Citibank Malaysia no longer lists line3, which the API does not have.

Affected pages:

Oct 21, 2026

Citibank: City and Country Required When an Address Is Sent

Citibank's ISO 20022 rules require the town and country whenever a payment carries an address. For cross-border and urgent payment types, receiver.address.city and receiver.address.country will be required when any part of receiver.address is sent. A payment with no address is unchanged.

  • Citibank Singapore MEPS and TT, Citibank Korea TT, Citibank Australia AU_HVCS and TT, and Citibank US US_WIRE_DOM and US_WIRE_INTL.
  • Citibank China CN_TT_DOM will always require receiver.address.city and receiver.address.country.

We are turning this on organization by organization and will contact you before it applies to your payments.

Affected pages:

Oct 15, 2026

Bank References for More Banks

Payments now return the bank's references for most banks and payment types. For most banks, references sent before the payment completes show on the payment while it is in progress; each bank's guide says when its references appear. The response schema has not changed.

  • bankReference is the bank's main reference for the payment. It can be null even when the bank sends other references, if none of them is the bank's main reference. An id a bank only echoes back from the payment request, such as UOB's transactionReference, is kept in bankReferences by name.
  • bankReferences has every reference the bank sent, keyed by the bank's own field names. Where a bank has a guide, its "Bank references" section lists the keys; the others are listed below.
  • A failed payment keeps the references it already showed.
  • References that arrive after a payment completed or failed are added, but never replace ones you already have. No webhook is sent, so fetch the payment to see them.
  • Banks that now return references:
    • DBS Singapore: every API payment type, and H2H.
    • Standard Chartered: every API payment type in every country, and H2H in Singapore, Great Britain and India (the same keys as Singapore H2H).
    • UOB Singapore and Malaysia: API, and the Malaysia DuitNow result file.
    • OCBC: Singapore and Malaysia API (BankReferenceNo is the main reference; Malaysia also keeps BizMsgID), and Singapore H2H.
    • CIMB Singapore: FAST and TT (API), CIMB's JournalId for BKTR, and H2H.
    • Citi: H2H in every country, and the API.
    • HSBC H2H (Singapore, Malaysia, Hong Kong, Vietnam; the same keys as the Singapore guide) and HSBC Malaysia API, ANZ Australia, and Deutsche Bank Singapore when its status files carry them.
    • Banco Azteca Mexico.
    • Airwallex: id is the main reference, with short_reference_id, request_id and external_reference (from dispatch_info).
    • Banking Circle: paymentId is the main reference, with transactionReference.
  • RHB Malaysia already returned bankReference. Its guide now names the keys.
  • Payments completed before this change are not updated.

Affected pages:

Oct 15, 2026

Lower POST Burst Limit

The burst allowance for POST requests is now 30 requests per API key, down from 100, in both LIVE and TEST modes. The sustained rate is unchanged at 25 requests per second, and GET limits are unchanged.

  • Once a key's burst is used up, POST requests sent faster than 25 per second get HTTP 429 RATE_LIMIT_EXCEEDED with a Retry-After header. Wait for the time it gives before retrying.
  • To send a large batch, spread the requests at or below the sustained rate instead of sending them all at once.

Affected pages:

Oct 14, 2026

UAE Cut-offs, Limits, POP Codes and Bank Codes

The Standard Chartered UAE payment rules now cover cut-off times, processing times, amount guidance and the Purpose of Payment codes. A new page lists the UAE bank codes Acme uses to find a bank's BIC from a UAE IBAN. No API behavior changes.

  • A new summary table lists the SCB rail, currency, cut-off, processing time and amount guidance for UAE_IBFT, UAE_FTS, TT and BKTR.
  • UAE_IBFT is available 24/7. SCB recommends it for amounts below AED 50,000.
  • UAE_FTS has an 18:30 UAE time cut-off, Monday to Friday. A payment after the cut-off is processed the next working day.
  • TT has a 20:30 UAE time cut-off every day.
  • BKTR in the same currency is available 24/7. A transfer between currencies has an 18:00 UAE time cut-off.
  • The full list of Purpose of Payment (POP) codes, also called FTS codes, is published. It marks which codes UAE_IBFT accepts.
  • Each payment type now has an example payload.
  • A new UAE Bank Codes page lists the bank code in each UAE IBAN with its BIC. It also says when you need to send receiver.bank.

Affected pages:

Oct 10, 2026

Webhook Examples Updated

The webhook examples now match what Acme sends, and each set sits in the API reference next to the endpoints it relates to. No webhook behavior changes.

  • The examples are split into five pages, one per API reference group. Acme webhook examples links to each one.
  • Each example shows the fields Acme sends for that case, in the order it sends them. The notes under an example list the fields that are sent only in some cases.
  • Fields that are left out when they have no value are no longer shown as null.
  • Timestamps have the number of decimal places Acme sends. Most object timestamps have 3, and a few have up to 9.
  • Transactions, payments, hosted payments, direct debits and virtual accounts have a tab for each country, bank or payment method where the body differs.
  • Most events now have a failed example, with the result codes Acme sends.
  • The payments.approved example now shows the payment after Acme submitted it to the bank. Its status is usually PROCESSING.
  • The direct debit payment batch examples now show type GIRO or FAST, and no metadata.

Affected pages:

Oct 9, 2026

Batch Direct Debit customerReference Per Bank

The reference for creating a batch direct debit collection now says how each bank uses customerReference. No API behavior changes.

  • Use a different customerReference for each payment in the batch.
  • UOB prints customerReference on your payer's bank statement.
  • DBS rejects a payment whose reference is not unique, if you subscribe to DBS's customer reference uniqueness check.
  • DBS does not publish how far back it checks.

Affected pages:

Oct 8, 2026

Batch Direct Debit Field Rules Documented

The reference for creating a batch direct debit collection now lists the length and allowed characters of each field. No API behavior changes.

  • customerReference is required. It allows up to 20 characters from the SWIFT character set.
  • Every field in directDebitAuthorizationInformation is required.
  • billReferenceNumber allows 1 to 35 characters from the SWIFT character set.
  • payerName allows up to 35 characters.
  • payerBankAccountNumber allows up to 34 letters and digits, with no dashes or spaces.
  • payerSwiftBic allows up to 11 characters.

Affected pages:

Where CIMB Singapore Shows Payment References

The CIMB Singapore (API) guide now says where each reference goes. Payment behavior has not changed.

  • FAST: CIMB returns customerReference as the end-to-end reference on the account statement and in account notifications. paymentDetails is sent as the payment reference. If it is not provided, Acme sends customerReference instead.
  • BKTR: CIMB shows customerReference as the Remarks on the account statement. paymentDetails is kept with the payment, and CIMB does not receive it. The example payload no longer includes it.
  • TT: paymentDetails is sent as up to 4 lines of 35 characters.

Affected pages:

Oct 6, 2026

RHB Malaysia paymentDetails Limited to 20 Characters

MY_IBG and MY_IBFT payments from an RHB account are now rejected on create when paymentDetails is longer than 20 characters. The limit was 140, and RHB rejected MY_IBG payments with longer details after they were sent.

Affected pages:

September 2026

Next Page

On this page

Oct 23, 2026API Reference: 400 Lists Only the Codes Each Endpoint ReturnsBatch Payments: Error Responses DocumentedAffected pages:Citibank: Structured Receiver Addresses (ISO 20022)Affected pages:Oct 21, 2026Citibank: City and Country Required When an Address Is SentAffected pages:Oct 15, 2026Bank References for More BanksAffected pages:Oct 15, 2026Lower POST Burst LimitAffected pages:Oct 14, 2026UAE Cut-offs, Limits, POP Codes and Bank CodesAffected pages:Oct 10, 2026Webhook Examples UpdatedAffected pages:Oct 9, 2026Batch Direct Debit customerReference Per BankAffected pages:Oct 8, 2026Batch Direct Debit Field Rules DocumentedAffected pages:Where CIMB Singapore Shows Payment ReferencesAffected pages:Oct 6, 2026RHB Malaysia paymentDetails Limited to 20 CharactersAffected pages: