Acme logoAcme docs
GuidesAPI referenceChangelog
CollectionsDirect DebitAuthorizations

Create a Direct Debit Authorization

Acme will fail the Direct Debit Authorization if we do not receive an authorization response within 20 minutes after creation for RETAIL payer segment, and 48 hours for CORPORATE payer segment. The status field will be set to FAILED, with failureReason set to PAYER_AUTHORIZATION_TIMEOUT. This can happen if the payer did not complete the authorization flow on their bank's website.

POST
/v1/direct-debit-authorizations

Authorization

authorization
AuthorizationBearer <token>

Set Your Secret API Key

In: header

Header Parameters

Idempotency-Key?string

A unique value, eg. a UUID.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

billReferenceNumber*string

Bill reference number for your payer. Must be at most 35 characters. Only alphanumeric characters and dashes are accepted. This must be unique for each new Direct Debit Authorization that you create.

Match^[a-zA-Z0-9\-]+$
Length1 <= length <= 35
businessUnitId?string

Business unit identifier, where your organization uses one.

Length1 <= length <= 5
country?string

Value in

  • "SG"
  • "MY"
  • "HK"
  • "KR"
  • "AU"
  • "US"
  • "ID"
  • "TW"
  • "BR"
  • "DK"
  • "PH"
  • "VN"
  • "AE"
  • "GB"
  • "IN"
  • "MX"
  • "CN"
endDate*string

If the payer sets an expiry date earlier than this end date with their bank during authorization, Acme will fail this authorization.

Formatdate
maxAmount?numberDeprecated

A positive integer value in the specified currency's smallest unit. E.g. SGD $10 will be represented as 1000 (in cents). Some banks allow payers to set deduction limits when they are approving the Direct Debit Authorizations. If the payer sets a deduction limit that is lower than maxAmount, Acme will fail the Direct Debit Authorization. Deprecated: use precheckMinAmount and precheckMaxAmount instead.

Range1 <= value <= 20000000
maxAmountCurrency?stringDeprecated

Three-letter ISO 4217 currency code in full uppercase. Currently supports SGD. Deprecated: use precheckCurrency instead.

payerName*string

Payer's name.

Length1 <= length <= 140
payerSegment*string

Your payer's segment: RETAIL or CORPORATE.

Value in

  • "CORPORATE"
  • "RETAIL"
payerSwiftBic*string

Your payer's bank SWIFT/BIC code. Use List Direct Debit Banks for the banks that support eGIRO and their current status.

Match^[A-Z0-9]{4}SG[A-Z0-9]{5}$
Length1 <= length
precheckCurrency?string

Three-letter ISO 4217 currency code in full uppercase. Currently supports SGD. This is required if either precheckMinAmount or precheckMaxAmount is set.

precheckMaxAmount?number

A positive integer value in the specified currency's smallest unit. E.g. SGD $10 will be represented as 1000 (in cents).

If you attempt to create a Direct Debit Payment (for this Direct Debit Authorization) with an amount greater than precheckMaxAmount, Acme will reject the Direct Debit Payment request. Use this as a guardrail to prevent yourself from overcharging your payers.

If the payer sets a deduction limit that is lower than precheckMaxAmount, precheckMaxAmount will be updated to the lower deduction limit.

If precheckMaxAmount is not set, it will be updated to the deduction limit set by the payer. If the payer does not set a deduction limit, and the payer's bank does not set a default deduction limit, Acme will set precheckMaxAmount to SGD $200,000.00.

Range1 <= value <= 20000000
precheckMinAmount?number

A positive integer value in the specified currency's smallest unit. E.g. SGD $10 will be represented as 1000 (in cents). Some banks allow payers to set deduction limits when they are approving Direct Debit Authorizations. If the payer sets a deduction limit that is lower than precheckMinAmount, Acme will fail the Direct Debit Authorization. If you attempt to create a Direct Debit Payment with an amount lower than precheckMinAmount, Acme will reject the Direct Debit Payment request.

Range1 <= value <= 20000000
returnUrl*string

Payer will be redirected to this URL after they have authorized the Direct Debit Authorisation at their bank's website.

Match^[A-Za-z][A-Za-z0-9+\-\.]+:\/\/[^:\?\/]+(:[0-9]+)?((\/[^\/\?]*)*\/?(\?[^\?\/]*)?)?$
Length0 <= length <= 2048
billReferenceNumber*string

Bill reference number for your payer. Numeric, up to 10 digits, unique for each new Direct Debit Authorization that you create.

Match^[0-9]+$
Length1 <= length <= 10
country?string

Value in

  • "SG"
  • "MY"
  • "HK"
  • "KR"
  • "AU"
  • "US"
  • "ID"
  • "TW"
  • "BR"
  • "DK"
  • "PH"
  • "VN"
  • "AE"
  • "GB"
  • "IN"
  • "MX"
  • "CN"
payerIdNumber*string

Your payer's identity number, based on the identity type.

Length1 <= length <= 35
payerIdType*string

Your payer's identity type.

Value in

  • "NEW_IC"
  • "OLD_IC"
  • "PASSPORT"
  • "BUSINESS_REGISTRATION"
  • "OTHERS"
payerName*string

Payer's name.

Match^[A-Za-z0-9 '\-/.]+$
Length1 <= length <= 140
payerSegment*string

Your payer's segment: RETAIL or CORPORATE.

Value in

  • "CORPORATE"
  • "RETAIL"
payerSwiftBic*string

Your payer's bank SWIFT/BIC code. Use List Direct Debit Banks for the banks that support direct debit for each payer segment and their current status.

Match^[A-Z0-9]{4}MY[A-Z0-9]{5}$
Length1 <= length
precheckCurrency?string

Currency of the precheck maximum amount. Must be MYR. This field is required when precheckMaxAmount is provided.

precheckMaxAmount?number

A positive integer value in the specified currency's smallest unit. E.g. RM10 will be represented as 1000 (in cents). If you attempt to create a Direct Debit Payment (for this Direct Debit Authorization) with an amount greater than precheckMaxAmount, Acme will reject the Direct Debit Payment request.

Range1 <= value <= 100000000
returnUrl*string

Payer will be redirected to this URL after they have authorized the Direct Debit Authorisation at their bank's website.

Match^[A-Za-z][A-Za-z0-9+\-\.]+:\/\/[^:\?\/]+(:[0-9]+)?((\/[^\/\?]*)*\/?(\?[^\?\/]*)?)?$
Length0 <= length <= 2048
billReferenceNumber*string

Bill reference number for your payer's reference.

Match^[a-zA-Z0-9&()/\-@,.'*" ]+$
Length1 <= length <= 35
country?string

Value in

  • "SG"
  • "MY"
  • "HK"
  • "KR"
  • "AU"
  • "US"
  • "ID"
  • "TW"
  • "BR"
  • "DK"
  • "PH"
  • "VN"
  • "AE"
  • "GB"
  • "IN"
  • "MX"
  • "CN"
endDate?string

The DDA expiry date. If not specified, the value will be defaulted as "2099-12-31".

Formatdate
payerAccountNumber*string

Your payer's unique account number without bank and branch code. Value must be in numeric.

Match^[0-9]+$
Length1 <= length <= 50
payerBankCode*string

3 digits local clearing code. Please refer to the Clearing Code and Branch Code List published by Hong Kong Interbank Clearing Limited (HKICL) for the most updated codes.

Match^[0-9]{3}$
Length3 <= length <= 3
payerEmailAddress?string

Your payer's email address provided as the contact details (Optional).

Match^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\.[a-zA-Z0-9.-]+$
Length0 <= length <= 150
payerIdNumber*string

Your payer's identity number, based on the identity type.

Match^[A-Z0-9]+$
Length0 <= length <= 35
payerIdType*string

Your payer's identity type.

Value in

  • "HKID"
  • "PASSPORT"
  • "BUSINESS_REGISTRATION_NUMBER"
  • "CERTIFICATE_OF_INCORPORATION_NUMBER"
  • "OTHER"
payerMobileNumber?string

Your payer's mobile number provided as the contact details (Optional). Must follow the format +852XXXXXXXX, where X is a digit and the number must be 8 digits long (excluding country code). E.g: +85212345678

Match^\+[1-9]\d+$
Length0 <= length <= 35
payerName*string

Payer's name.

Match^[a-zA-Z0-9.@()/\-& ]+
Length1 <= length <= 140
precheckCurrency*string

Currency of the precheck maximum amount. Must be HKD. This field is required when precheckMaxAmount is provided.

precheckMaxAmount*number

A positive integer value in the specified currency's smallest unit. This can be used to set a maximum transaction amount for this DDA. If you attempt to create a Direct Debit Payment (for this Direct Debit Authorization) with an amount greater than this value, Acme will reject the Direct Debit Payment request.

Range1 <= value <= 9999999999900

Response Body

*/*

application/json

application/json

curl -X POST "https://example.com/v1/direct-debit-authorizations" \
  -H "Content-Type: application/json" \
  -d '{
    "billReferenceNumber": "A0012334455",
    "payerSwiftBic": "DBSSSGSGXXX",
    "payerSegment": "RETAIL",
    "payerName": "Richard Hendricks",
    "precheckMaxAmount": 100000,
    "precheckCurrency": "SGD",
    "endDate": "2042-04-24",
    "returnUrl": "https://example.com/return"
  }'

Redirect the payer to authorizeUrl to approve the authorization at their bank. payerBankAccountNumber is filled in once they approve.

{
  "id": "dda_0J7Q6A3M8V5X1",
  "billReferenceNumber": "A0012334455",
  "payerSwiftBic": "DBSSSGSGXXX",
  "payerBankCode": null,
  "payerSegment": "RETAIL",
  "payerName": "Richard Hendricks",
  "payerBankAccountNumber": null,
  "payerIdHash": null,
  "payerIdType": null,
  "status": "REQUIRES_AUTHORIZATION",
  "failureReason": null,
  "underlyingErrorMessage": null,
  "startDate": "2026-09-09",
  "precheckMinAmount": null,
  "precheckMaxAmount": 100000,
  "precheckCurrency": "SGD",
  "maxAmount": 100000,
  "maxAmountCurrency": "SGD",
  "payerAuthorizedMaxAmount": 0,
  "endDate": "2042-04-24",
  "authorizeUrl": "https://api.tryacme.com/redirection/direct-debit-authorizations/dda_0J7Q6A3M8V5X1/authorize?key=0J7Q6A4NRX2W8K",
  "cancelUrl": null,
  "returnUrl": "https://example.com/return",
  "cancelReturnUrl": null,
  "transactionReference": null,
  "createdAt": "2026-09-09T02:10:11.204118Z",
  "updatedAt": "2026-09-09T02:10:11.204118Z"
}

List Direct Debit Authorizations

Previous Page

Get a Direct Debit Authorization

Next Page