Batch Payments

This describes Acme's Batch Payments API. This API can be used to send multiple payments in a single batch to the bank using file transfer.

Which API should I use?

Payments created outside of a Batch (using the Payments API) are sent to the bank over API transport. Payments created within a batch using the Batch Payments API described here are sent to the bank over files (host-to-host integration).

The API you should use to create the payment depends on the integration you have with your bank.

Both kinds of payments are visible in the List Payments API.

Payment Batch API

The Payment Batch API creates a batch of payments all at once. The payments in a batch share a common payment type, payment date, currency, and source account. The payments in a batch will be submitted together in a single file to the bank. Each payment in the batch has its own individual ID that can be used to track its success / failure. The batch itself also has an ID.

Upon receiving the batch, Acme will process and send it to the bank. Any progress reports will be sent via webhook. The changes will also be visible when calling the list or get APIs. A sample timeline of events and webhooks / status changes is provided below.

Create a Batch Payment

POST /v1/payment-batches

{
  "type": "MEPS",

  // actual payment date may change due to auto value date rollover from bank
  // e.g. due to submitting batch after cutoff, or approval taking too long
  "paymentDate": "2024-05-10",

  "senderAccountId": "intacct_XYZ",

  // optional - must be provided if account has multiple currencies configured in Acme
  "senderAccountCurrency": "SGD", 

  "currency": "SGD",
  "payments": [
    {
      "amount": 20000,

      // optional - a random string will be generated if not provided
      // cannot reuse previous customer references (checked by bank)
      "customerReference": "DONUTS",

      // optional
      "paymentDetails": "10 boxes of 12 each",

      // optional - for TT / MEPS: SENDER/RECEIVER/SHARED
      "bankChargeBearer": "SENDER",

      "receiver": {
        "name": "Donut Shop",
        "bank": "OCBCSGSGXXX",
        "bankAccountNumber": "123456789",

        // address must be provided for TT/MEPS
        "address": {
          "line1": "20 Side Street",
          "line2": "Unit 02-3A"
        }
      }
    },
    {
      "amount": 3000
      "customerReference": "COFFEE",
      "receiver": {
        "name": "Coffee Shop",
        "bank": "UOVBSGSGXXX",
        "bankAccountNumber": "345678901",
        "address": {
          "line1": "127 Jln Merdeka"
        }
      }
    }, 
    [...]
  ]
}

More details on the receiver fields may be found in our Payment documentation.

Response

200 OK

{
  "id": "pymtb_XYZ",
  "type": "MEPS",
  "paymentDate": "2024-05-10",
  "senderAccountId": "intacct_XYZ",
  "currency": "SGD"
  "senderAccountCurrency": "SGD",
  "status": "PROCESSING", // PROCESSING (still at Acme) -> SUBMITTED (at the bank) -> FAILED / COMPLETED
  "payments": [
    {
      "id": "pymt_XYZ",
      "amount": 20000,
      "receiver": { ... },
      "status": "PROCESSING" // individual payment status
    },
    {
      "id": "pymt_XYZ", 
      "amount": 3000,
      "receiver": { ... },
      "status": "PROCESSING"
    },
    [...]
  ]
}

The individual payment objects (pymt_XXX) returned as part of the response are also visible in our Payments API endpoints.

Validation

• Sender account currency: must be specified if account is configured in Acme as multi-currency
• Currency
  • MEPS/FAST/PAYNOW: must be SGD
• Number of payments in one batch: maximum of 1000
• Receiver name: must be present
• Receiver address
  • TT/MEPS: must be present
  • ACT: must not be present
  • all except ACT: if present, should fit within 3x35 character lines
• Receiver bank (for bank account payments - ACT/TT/MEPS/PAYNOW):
  • ACT: must not be present
  • others: must be present

Possible Errors

• Invalid type for batch
• Invalid payment date for batch
• Invalid currency for batch
• Invalid source account for batch
• any payment level error e.g. bank account number, bank, account holder name
  • If any payment fails validation by Acme, Acme will currently reject the entire submission. Please resubmit the entire request with the errors corrected.

List Batch Payments

GET /v1/payment-batches

Get a Batch Payment

GET /v1/payment-batches/{id}

Additions to the Payment API

In addition to the existing Payment fields documented on the Payment API documentation, the following fields will be added for Payments which are part of a Payment Batch.

{
  "id": "pymt_XYZ",
  // ... existing fields ...
  "batchId": "pymtb_XYZ",
  "paymentDate": "2024-05-10", // as instructed by customer
  "actualPaymentDate": "2024-05-12", // if changed by bank
  "bankChargeAmount": 100, // if bank charges present (e.g. for TT / MEPS)
  "bankChargeCurrency": "SGD"
}

Webhooks

As file-based integration is an inherently asynchronous process, Acme will emit webhooks to inform you of the status of the payments.

• Payment Batch Submitted (sample) - sent after the file is submitted to the bank
• Payment Batch Rejected (sample) - sent if the entire batch is rejected
• Payment Succeeded (sample) - sent for the payments after positive ACK3 (result from clearing system) is received from the bank
• Payment Failed (sample) - sent for the payments after a rejection at the ACK1 (entire batch), ACK2 (bank validation), or ACK3 (clearing system result) level.

Test mode

You can use your test API key to test your integration before going live. Test mode validates the input parameters and always assumes success, unless one of the special account numbers below are used.

To test failure cases please use the following account numbers (any bank is fine):

• 000000000 fail this individual payment
• 000000001 fail this individual payment
• 000000002 fail the entire batch containing this payment

Test mode will emit the following webhooks for a batch that does not fail entirely:

• payment-batches.submitted (sample)
• payments.succeeded and/or payments.failed (sample) for the payments in the batch

If the 000000002 account number is used in a batch, test mode will simulate a failure for the entire batch:

• payment-batches.submitted (sample)
• payment-batches.rejected (sample)
• payments.failed (sample) for all payments in the batch

Sample Timeline

As the payment is processed, it goes through several stages of validation by Acme and the bank. A payment may be rejected by any of these stages. A payment is considered completed only when the final stage succeeds.

1. Client submits 10 payments in the batch, 2 of them are obviously invalid e.g. bank code has wrong format (caught by Acme)
2. Acme returns 400 bad request, no batch object is created.
3. Client submits 10 payments, fixing the invalid ones.
4. Acme returns 200 OK, batch object is created (status PROCESSING), payments are created with status PROCESSING.
5. Acme processes the batch and sends a batch of 10 payments to the bank.
   1. Batch status change to SUBMITTED, 10 payments status change to SUBMITTED.
   2. Acme sends payment batch submitted webhook for the batch.
6. Bank reads the file, validates batch parameters, and delivers ACK1 accepting the batch.
   1. In case of a rejection in ACK1 (batch rejection), Acme will send a payment batch rejected webhook for the batch, and payment rejected webhook for the payments inside of it.
7. Bank processes the file and validates each payment inside. It delivers ACK2 where 2 of the 10 payments are further rejected, while the remaining 8 payments move on to the next stage.
   1. If any of the payments have ACWC (Accepted With Changes) status, Acme will set actualPaymentDate to the changed value.
   2. Acme sends payment failed webhook for the 2 payments (payment status change to FAILED).
8. Bank submits the payment to the clearing system and delivers their response in ACK3, 8 remaining payments are successful.
   1. If any of the payments have ACWC (Accepted With Changes) status, Acme will set actualPaymentDate / bankChargeAmount / bankChargeCurrency to the values provided by the bank.
   2. Acme sends payment succeeded webhook for the 8 payments (payment status change to COMPLETED).