CollectionsDirect Debit

Direct Debit Webhooks

Example webhook bodies for direct debit authorizations, payments and payment batches.

See how to read the webhook examples. The values are made up, but every field, its order and its format match what Acme sends.

Direct Debit Authorizations

Successful direct debit authorization (direct-debit-authorizations.succeeded):

{
  "id": "wbh_0RWF7FWW5Y563",
  "createdAt": "2026-10-08T05:06:58.325593865Z",
  "mode": "LIVE",
  "event": "direct-debit-authorizations.succeeded",
  "object": {
    "id": "dda_0RWF7FW49Y7ZN",
    "billReferenceNumber": "ROCKETCUST10482",
    "payerSwiftBic": "OCBCSGSGXXX",
    "payerBankCode": null,
    "payerSegment": "RETAIL",
    "payerName": "TAN WEI MING",
    "payerBankAccountNumber": "5012846731",
    "payerIdHash": "9f2c4e81a6b03d57e1f4a8c26b9d0e73f5a1c84b2d6e09f7a3b5c18d4e2f6a90",
    "payerIdType": "NRIC",
    "status": "SUCCEEDED",
    "failureReason": null,
    "underlyingErrorMessage": null,
    "startDate": "2026-10-08",
    "precheckMinAmount": null,
    "precheckMaxAmount": 50000,
    "precheckCurrency": "SGD",
    "maxAmount": null,
    "maxAmountCurrency": null,
    "payerAuthorizedMaxAmount": 50000,
    "endDate": null,
    "authorizeUrl": "https://api.tryacme.com/redirection/direct-debit-authorizations/dda_0RWF7FW49Y7ZN/authorize",
    "cancelUrl": null,
    "returnUrl": "https://rocketshop.com/egiro/return",
    "cancelReturnUrl": null,
    "transactionReference": "ROCKETSG0120261008130336065141",
    "createdAt": "2026-10-08T05:03:36.065Z",
    "updatedAt": "2026-10-08T05:06:58.318Z"
  }
}
  • maxAmount and maxAmountCurrency are deprecated. Use precheckMaxAmount and precheckCurrency instead.
  • In live mode, maxAmount and maxAmountCurrency have a value only for a Singapore authorization created with them. Otherwise they are null.
  • In test mode, maxAmount can also hold the amount the payer authorized.
  • When the Singapore payer authorizes less than precheckMaxAmount, precheckMaxAmount is lowered to payerAuthorizedMaxAmount.

Failed direct debit authorization (direct-debit-authorizations.failed). An authorization the payer did not complete in time also arrives as this event, with failureReason set to PAYER_AUTHORIZATION_TIMEOUT:

{
  "id": "wbh_0RWF7FX0DY607",
  "createdAt": "2026-10-08T05:09:14.508116730Z",
  "mode": "LIVE",
  "event": "direct-debit-authorizations.failed",
  "object": {
    "id": "dda_0RWF7FX01Y43X",
    "billReferenceNumber": "ROCKETCUST10483",
    "payerSwiftBic": "OCBCSGSGXXX",
    "payerBankCode": null,
    "payerSegment": "RETAIL",
    "payerName": "TAN WEI MING",
    "payerBankAccountNumber": null,
    "payerIdHash": null,
    "payerIdType": null,
    "status": "FAILED",
    "failureReason": "PAYER_AUTHORIZATION_FAILED",
    "underlyingErrorMessage": "BA3002: Consent not given by applicant on bank website for eDDA creation. eDDA creation unsuccessful",
    "startDate": "2026-10-08",
    "precheckMinAmount": null,
    "precheckMaxAmount": 100000,
    "precheckCurrency": "SGD",
    "maxAmount": null,
    "maxAmountCurrency": null,
    "payerAuthorizedMaxAmount": 0,
    "endDate": null,
    "authorizeUrl": "https://api.tryacme.com/redirection/direct-debit-authorizations/dda_0RWF7FX01Y43X/authorize",
    "cancelUrl": null,
    "returnUrl": "https://rocketshop.com/egiro/return",
    "cancelReturnUrl": null,
    "transactionReference": "ROCKETSG0120261008130840117302",
    "createdAt": "2026-10-08T05:08:40.117Z",
    "updatedAt": "2026-10-08T05:09:14.496Z"
  }
}

Canceled direct debit authorization (direct-debit-authorizations.canceled):

{
  "id": "wbh_0RWFS5YQ7AXFQ",
  "createdAt": "2026-10-09T01:02:44.133720198Z",
  "mode": "LIVE",
  "event": "direct-debit-authorizations.canceled",
  "object": {
    "id": "dda_0RWFS5YQ3AZKF",
    "billReferenceNumber": "RSHK000918",
    "payerSwiftBic": "HSBCHKHHHKH",
    "payerBankCode": "004",
    "payerSegment": null,
    "payerName": "CHAN TAI MAN",
    "payerBankAccountNumber": "004123456838",
    "payerIdHash": null,
    "payerIdType": null,
    "status": "CANCELED",
    "failureReason": null,
    "underlyingErrorMessage": null,
    "startDate": "2026-10-08",
    "precheckMinAmount": 0,
    "precheckMaxAmount": 500000,
    "precheckCurrency": "HKD",
    "maxAmount": null,
    "maxAmountCurrency": null,
    "payerAuthorizedMaxAmount": 0,
    "endDate": null,
    "authorizeUrl": null,
    "cancelUrl": null,
    "returnUrl": null,
    "cancelReturnUrl": null,
    "transactionReference": null,
    "createdAt": "2026-10-08T07:44:58.302Z",
    "updatedAt": "2026-10-09T01:02:44.120Z"
  }
}

When Acme sends a cancel event

Acme sends direct-debit-authorizations.canceled when an authorization becomes CANCELED. Whether you hear about a cancellation made outside Acme depends on the bank.

Bank and marketYou cancel with Cancel a Direct Debit AuthorizationThe payer cancels at their bank
Singapore (eGIRO)Sent once DBS confirms, after the payer approves at cancelUrl.Not sent. Acme is not told.
Malaysia (FPX)Not available. The cancel endpoint answers 400 with INVALID_REQUEST_PARAMETER.Not sent. Acme is not told.
Standard Chartered Hong Kong (eDDA)Sent when the authorization becomes CANCELED.Sent when Acme reads the bank's next daily report, each morning at 08:30 Hong Kong time.
HSBC Hong Kong (eDDA)Not available. The cancel endpoint answers 422 with INVALID_OPERATION.Sent when Acme reads HSBC's next daily report, each morning at 06:00 Hong Kong time in live mode. In test mode, Acme reads it every 10 minutes.
  • For HSBC Hong Kong, an expired or deleted mandate also becomes CANCELED.
  • For HSBC Hong Kong, a suspended or dormant mandate stays SUCCEEDED, because it can become active again.
  • Where Acme is not told, the authorization stays SUCCEEDED in Acme.

Direct Debit Payments

Successful direct debit payment (direct-debit-payments.succeeded):

{
  "id": "wbh_0RWF7FX65Y4V3",
  "createdAt": "2026-10-08T05:49:56.143613113Z",
  "mode": "LIVE",
  "event": "direct-debit-payments.succeeded",
  "object": {
    "id": "dpymt_0RWF7FX59Y4W0",
    "type": "FAST",
    "amount": 1250,
    "currency": "SGD",
    "directDebitAuthorizationId": "dda_0RWF7FW49Y7ZN",
    "customerReference": "OCTSUBFEE10482",
    "receiver": {
      "bankAccountNumber": "0721845093"
    },
    "status": "SUCCEEDED",
    "resultCode": null,
    "underlyingErrorMessage": null,
    "bankReference": null,
    "createdAt": "2026-10-08T05:49:54.557Z",
    "updatedAt": "2026-10-08T05:49:56.135Z"
  }
}
  • batchId and metadata are sent only for a payment that is part of a batch.
  • Payments in a batch can arrive several at a time, under objects.
  • For a payment made with an authorization kept outside Acme (an external DDA), directDebitAuthorizationId is left out and directDebitAuthorizationInformation is sent instead. See the two external DDA tabs.
  • External DDAs are available only for Singapore FAST payments and Singapore GIRO batch payments.
  • In directDebitAuthorizationInformation, internalAccountId is the receiving bank account number. It is not the Internal Account ID sent when the payment was created.
  • bankReference is the bank's reference for the payment.
  • Only HSBC Hong Kong payments can have a bankReference. It is null for every other bank.
  • previousPaymentStatus is sent only when the bank reports the payment as a duplicate.

Failed direct debit payment (direct-debit-payments.failed). underlyingErrorMessage is the bank's code and description:

{
  "id": "wbh_0RWF7FXADY4H2",
  "createdAt": "2026-10-08T05:50:02.771904316Z",
  "mode": "LIVE",
  "event": "direct-debit-payments.failed",
  "object": {
    "id": "dpymt_0RWF7FXA9Y7VP",
    "type": "FAST",
    "amount": 1250,
    "currency": "SGD",
    "directDebitAuthorizationId": "dda_0RWF7FW49Y7ZN",
    "customerReference": "OCTSUBFEE10483",
    "receiver": {
      "bankAccountNumber": "0721845093"
    },
    "status": "FAILED",
    "resultCode": "INSUFFICIENT_FUNDS",
    "underlyingErrorMessage": "1209: Insufficient funds",
    "bankReference": null,
    "createdAt": "2026-10-08T05:50:00.204Z",
    "updatedAt": "2026-10-08T05:50:02.760Z"
  }
}

Direct Debit Payment Batches

Direct debit payment batch submitted (direct-debit-payment-batches.submitted):

{
  "id": "wbh_0RWF7FXFDY4TB",
  "createdAt": "2026-10-08T08:52:41.079452816Z",
  "mode": "LIVE",
  "event": "direct-debit-payment-batches.submitted",
  "object": {
    "id": "bddp_0QK7P3R8CW2NA",
    "type": "GIRO",
    "paymentDate": "2026-10-09",
    "currency": "SGD",
    "status": "SUBMITTED",
    "createdAt": "2026-10-08T08:47:02.318204Z",
    "updatedAt": "2026-10-08T08:52:41.067913Z"
  }
}

Direct debit payment batch rejected (direct-debit-payment-batches.rejected):

{
  "id": "wbh_0RWF7FXHHY5V0",
  "createdAt": "2026-10-08T09:14:26.544190263Z",
  "mode": "LIVE",
  "event": "direct-debit-payment-batches.rejected",
  "object": {
    "id": "bddp_0QK7P5W1JD6TB",
    "type": "GIRO",
    "paymentDate": "2026-10-09",
    "currency": "SGD",
    "status": "FAILED",
    "createdAt": "2026-10-08T08:47:02.318204Z",
    "updatedAt": "2026-10-08T09:14:26.530718Z"
  }
}

On this page