Create a Batch Payment

POST 
/payment-batches

Create a batch payment.

This is an asynchronous operation. Listen to the payments.succeeded or payments.failed webhook to be notified of the final outcome of each payment.

Please refer to the payment rules for each bank for details on per-bank limitations.

Request

Header Parameters

Idempotency-Key string

A unique value, eg. a UUID.

application/json

Body

type stringrequired

Possible values: [ACT, FAST, PAYNOW, TT, MEPS, GIRO, MY_DUITNOW]

Type of payment

paymentDate stringrequired

The date payment should be sent.

senderAccountId stringrequired

The Acme-specific internal id of the source bank account.

senderAccountCurrency string

Currency to use in the sender account, if it has multiple currencies. Optional if sender account only has one currency configured.

currency stringrequired

Three-letter ISO 4217 currency code in full uppercase. Must be a currency supported by the payment type.

For example, FAST only supports SGD.

payments

object[]

required

Payments to create in this batch. Maximum 1000 items.

Array [

amount integerrequired

A positive integer value in specified currency's smallest unit. e.g. for SGD, $10 would be represented as 1000 (cents).

customerReference string

A meaningful description of the payment. This will show up in the receiver's bank statement. Characters used should be restricted to the SWIFT Character Set: uppercase and lowercase letters A-Z, 0-9 numerals, space, and these symbols: /-?:().,'+.

paymentDetails string

Extended description of the payment.

instructionForSenderBank string

Usually for TT only - special instructions for sender bank

bankChargeBearer string

Possible values: [SENDER, RECEIVER, SHARED]

For TT/MEPS - who pays for bank charges

receiver

object

required

oneOf

FAST Receiver

name stringrequired

Receiver's name

bank stringrequired

Receiver's bank 11-character SWIFT/BIC code

bankAccountNumber stringrequired

Receiver's bank account number

address

object

Receiver's address

line1 string

line2 string

city string

state string

postalCode string

country string

GIRO Receiver

name stringrequired

Receiver's name

bank stringrequired

Receiver's bank 11-character SWIFT/BIC code

bankAccountNumber stringrequired

Receiver's bank account number

address

object

Receiver's address

line1 string

line2 string

city string

state string

postalCode string

country string

PayNow Receiver

name stringrequired

Receiver's name

proxyType stringrequired

Possible values: [MOBILE, UEN, VPA]

The proxy type if type is PAYNOW

proxyValue stringrequired

The proxy value if type is PAYNOW

ACT receiver

name stringrequired

Receiver's name

bankAccountNumber stringrequired

Receiver's bank account number

TT Receiver

name stringrequired

Receiver's name

bank stringrequired

Receiver's bank 11-character SWIFT/BIC code

bankAccountNumber stringrequired

Receiver's bank account number

localRoutingIdentifier string

Local routing identifier, if required e.g. AU BSB

intermediaryBank string

Intermediary bank's BIC, if required

address

object

required

Receiver's address

line1 stringrequired

line2 string

city string

state string

postalCode string

country string

MEPS Receiver

name stringrequired

Receiver's name

bank stringrequired

Receiver's bank 11-character SWIFT/BIC code

bankAccountNumber stringrequired

Receiver's bank account number

address

object

required

Receiver's address

line1 stringrequired

line2 string

city string

state string

postalCode string

country string

DuitNow Receiver

name stringrequired

Receiver's name

proxyType stringrequired

Possible values: [MOBILE, BUSINESS_REG, NRIC, PASSPORT]

The proxy type

proxyValue stringrequired

Follow these formats:

• MOBILE proxy type: A mobile number including the country code (+60 for Malaysia). E.g: +601255214553.
• BUSINESS_REG proxy type: A valid Business Registration Number (BRN) issued by the Companies Commission of Malaysia, a.k.a. Suruhanjaya Syarikat Malaysia (SSM). E.g: 201903123456.
• NRIC proxy type: Only alphanumeric with no hyphens (-) and no spaces allowed. Both New and Old IC numbers are supported. E.g: 610204135758.
• PASSPORT proxy type: Passport Number + Alpha-3 country code of the country of issuance. E.g: given a passport number E394029340V and country code of Singapore (SGP), the value will be E394029340VSGP.

]

Responses

200

OK

Response Headers

• Acme-Mode

  string

  Has the value LIVE if the data exists in live production mode or the value TEST if the data exists in test sandbox mode.

application/json

Schema

Schema

id string

Unique identifier for the object.

type string

Possible values: [ACT, FAST, PAYNOW, TT, MEPS, GIRO, MY_DUITNOW]

Type of payment

paymentDate string

The date payment should be sent.

senderAccountId string

The Acme-specific internal id of the source bank account.

currency string

Three-letter ISO 4217 currency code in full uppercase. Must be a currency supported by the payment type.

For example, FAST only supports SGD.

payments

object[]

Array [

id string

Unique identifier for the object.

amount integer

A positive integer value in specified currency's smallest unit. e.g. for SGD, $10 would be represented as 1000 (cents).

customerReference string

A meaningful description of the payment. This will show up in the receiver's bank statement. Characters used should be restricted to the SWIFT Character Set: uppercase and lowercase letters A-Z, 0-9 numerals, space, and these symbols: /-?:().,'+.

paymentDetails string

Extended description of the payment.

instructionForSenderBank string

Usually for TT only - special instructions for sender bank

bankChargeBearer string

Possible values: [SENDER, RECEIVER, SHARED]

For TT/MEPS - who pays for bank charges

status string

Possible values: [PROCESSING, FAILED, SUBMITTED, COMPLETED]

Status of the payment

receiver

object

name string

Receiver's name

bank string

Receiver's bank SWIFT/BIC code

bankAccountNumber string

Receiver's bank account number

proxyType string

Possible values: [MOBILE, UEN, VPA]

The proxy type if type is PAYNOW

proxyValue string

The proxy value if type is PAYNOW

address

object

Receiver's address

line1 string

line2 string

city string

state string

postalCode string

country string

createdAt string

Time at which the object was created. In ISO 8601 format.

updatedAt string

Time at which the object was last updated. In ISO 8601 format.

]

status string

Possible values: [OPEN, PROCESSING, SUBMITTED, FAILED, COMPLETED]

Status of the batch

createdAt string

Time at which the object was created. In ISO 8601 format.

updatedAt string

Time at which the object was last updated. In ISO 8601 format.

Example (from schema)

{
  "id": "bpmt_0FGDYHZMRZF49",
  "type": "TT",
  "paymentDate": "2024-12-31",
  "senderAccountId": "intacc_0FGDYHZMRZF49",
  "currency": "SGD",
  "payments": [
    {
      "id": "pymt_0H3BQXP3VF2HZ",
      "amount": 4200,
      "customerReference": "BONUS-2024-01",
      "paymentDetails": "20 boxes of donuts",
      "instructionForSenderBank": "string",
      "bankChargeBearer": "SENDER",
      "status": "PROCESSING",
      "receiver": {
        "name": "Harry Potter",
        "bank": "DBSSSGSGXXX",
        "bankAccountNumber": "0052312891",
        "proxyType": "MOBILE",
        "proxyValue": "+6592345678",
        "address": {
          "line1": "20 Main Street",
          "line2": "Unit #03-45",
          "city": "Singapore",
          "state": "",
          "postalCode": "11111",
          "country": "Singapore"
        }
      },
      "createdAt": "2023-04-24T00:00:00.000000Z",
      "updatedAt": "2023-04-24T00:00:00.000000Z"
    }
  ],
  "status": "SUBMITTED",
  "createdAt": "2023-04-24T00:00:00.000000Z",
  "updatedAt": "2023-04-24T00:00:00.000000Z"
}

Loading...