Skip to main content

Create a Direct Debit Authorization

POST 
/direct-debit-authorizations

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.

Request​

Header Parameters

    Idempotency-Key string

    A unique value, eg. a UUID.

Body

    billReferenceNumber stringrequired

    Possible values: Value must match regular expression ^[a-zA-Z0-9\-]{1,35}$

    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.

    payerSwiftBic stringrequired

    Your payer's bank SWIFT/BIC code.

    The banks that support eGIRO for RETAIL payer segment are:

    • Bank of China: BKCHSGSGXXX
    • DBS Bank: DBSSSGSGXXX
    • HSBC Bank: HSBCSGS2XXX
    • Industrial & Commercial Bank of China: ICBKSGSGXXX
    • Maybank: MBBESGS2XXX
    • Oversea-Chinese Banking Corporation: OCBCSGSGXXX
    • Standard Chartered Bank: SCBLSG22XXX
    • United Overseas Bank: UOVBSGSGXXX

    The banks that support eGIRO for CORPORATE payer segment are:

    • Bank of China: BKCHSGSGXXX
    • DBS Bank: DBSSSGSGXXX
    • Maybank: MBBESGS2XXX
    • Oversea-Chinese Banking Corporation: OCBCSGSGXXX
    • United Overseas Bank: UOVBSGSGXXX
    payerSegment stringrequired

    Possible values: [RETAIL, CORPORATE]

    Your payer's segment: RETAIL or CORPORATE.

    payerName stringrequired
    maxAmount integerdeprecated

    A positive integer value in 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 this Direct Debit Authorization. Otherwise maxAmount will be updated with the deduction limit set by the payer.

    Deprecated: use precheckMinAmount instead.

    maxAmountCurrency stringdeprecated

    Possible values: [SGD]

    Three-letter ISO 4217 currency code in full uppercase. Must be a supported currency. Currently supports SGD.

    Deprecated: use precheckCurrency instead.

    precheckMinAmount integer

    A positive integer value in 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 this Direct Debit Authorization. Use this to prevent your payers from approving Direct Debit Authorizations with deduction limits that are too low.

    precheckMaxAmount integer

    A positive integer value in 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.

    precheckCurrency string

    Possible values: [SGD]

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

    endDate stringrequired

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

    returnUrl stringrequired

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

Responses​

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.

Schema

    id stringrequired
    billReferenceNumber stringrequired

    Possible values: Value must match regular expression ^[a-zA-Z0-9\-]{1,35}$

    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.

    payerSwiftBic stringrequired

    Payer's bank SWIFT/BIC code

    payerSegment stringrequired

    Your payer's segment: RETAIL or CORPORATE.

    payerName stringrequired

    Payer's name

    payerBankAccountNumber string

    Payer's bank account number. This field is only set after the payer has approved the Direct Debit Authorization.

    payerIdHash string

    Hash value of the payer's identification number stored in the payer's bank system.

    payerIdType string

    Possible values: [NRIC, FIN, PASSPORT, UEN]

    Payer's identification type stored in the payer's bank system.

    failureReason string

    If status is FAILED, this provides additional information about the failure.

    • PAYER_AUTHORIZATION_FAILED: Payer has failed to authorize the Direct Debit Authorization.
    • PAYER_AUTHORIZATION_TIMEOUT: Acme did not receive an authorization response in time. Acme will wait up to 20 minutes for RETAIL payer segment Direct Debit Authorizations, and up to 48 hours for CORPORATE payer segment Direct Debit Authorizations.
    • PAYER_SPECIFIED_LOWER_MAX_AMOUNT: Payer has authorized the Direct Debit Authorization with a lower maximum amount than what is required.
    • PAYER_SPECIFIED_EARLIER_END_DATE: Payer has authorized the Direct Debit Authorization with an earlier end date than what is required.
    returnUrl stringrequired

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

    cancelReturnUrl string

    Payer will be redirected to this URL after they have cancelled the Direct Debit Authorisation at their bank's website. This is only present when DDA is being cancelled.

    status stringrequired

    Possible values: [REQUIRES_AUTHORIZATION, PROCESSING, SUBMITTED, SUCCEEDED, FAILED, CANCELED]

    • REQUIRES_AUTHORIZATION: Requires the payer to perform authorization with their bank.
    • PROCESSING: A creation callback was received from the payer's bank. Normally, a DDA will transition very quickly from PROCESSING to SUBMITTED.
    • SUBMITTED: A DDA creation request was sent to the Industry Aggregator and is awaiting the final callback.
    • SUCCEEDED: The DDA has been created successfully with the bank and is ready to be used for creating Direct Debit Payments.
    • FAILED: The DDA creation failed. You should create a new DDA if you wish to try again.
    • CANCELED: The DDA has been canceled by the payer.
    startDate stringrequired
    maxAmount integerrequired
    maxAmountCurrency stringrequired

    Possible values: [SGD]

    Three-letter ISO 4217 currency code in full uppercase.

    precheckMinAmount integer
    precheckMaxAmount integer
    precheckCurrency string

    Possible values: [SGD]

    Three-letter ISO 4217 currency code in full uppercase.

    endDate string
    authorizeUrl string

    Redirect payer to this URL for logging into their bank to perform authorization. This is only present when the DDA status is REQUIRES_AUTHORIZATION.

    cancelUrl string

    Redirect payer to this URL for logging into their bank to perform cancellation. This is only present when you request for cancellation.

    createdAt stringrequired
    updatedAt stringrequired
Loading...