Sign in

v1

latestOpenAPI 3.0.32026-07-23167675.4 KB
Binding

Card Binding (Card Registration)

Registers a credit card for a customer under a merchant account.

Flow:

  1. Merchant submits the encrypted card data along with customer information.
  2. The system decrypts the card data, validates it against the ALTO/KKI network, and creates an AcquirerToken.
  3. On success, a redirectUrl is returned (when CHANNEL-ID: DH) pointing to the OTP verification page.
  4. The customer completes OTP verification, which finalises the binding and issues a bankCardToken.

Card Data Encryption: Encrypt the CardDataPayload JSON object using AES-CBC with the merchant's sharedKey. The resulting Base64-encoded ciphertext is submitted as the cardData field.

post/direct-debit/core/v1/registration-card-bind

Headers

X-PARTNER-IDstring required

Merchant's client ID registered with DOKU

X-EXTERNAL-IDstring required

Unique reference ID for this request (per-day uniqueness required). Used for idempotency and tracing.

Authorizationstring required

B2B access token obtained from the Get B2B Token API

X-TIMESTAMPstring required

Request timestamp in ISO 8601 format (yyyy-MM-ddTHH:mm:ss+07:00)

X-SIGNATUREstring required

HMAC-SHA512 asymmetric signature for request integrity verification

CHANNEL-ID'DH' | 'H2H'

Channel identifier determining the post-registration redirect behaviour.

  • DH (Direct Hosting, default): returns a redirectUrl pointing to the DOKU-hosted OTP page.
  • H2H (Host-to-Host): no redirect; merchant handles the OTP flow independently.

Request body

partnerReferenceNostring

Merchant's unique reference number for this binding request

cardDatastring required

AES-CBC encrypted JSON of the card data, Base64-encoded. Encrypt the CardDataPayload object using the merchant's sharedKey provided by DOKU. See the CardDataPayload schema for the plaintext structure.

custIdMerchantstring required

Merchant's unique identifier for the customer

journeyIdstring

Optional journey or session ID for tracking the binding flow end-to-end

phoneNostring

Customer's phone number (used for OTP delivery during OTP verification step)

Response

Card binding request accepted. The customer must complete OTP verification to finalise the binding. Use redirectUrl (DH flow) or additionalInfo.authCode (H2H flow) to proceed.

responseCodestring

Response code: HTTP Status (3) + Service Code 01 (2) + Case Code (2). Example: 2000100 = HTTP 200 + service 01 + case 00 (Successful).

responseMessagestring

Human-readable response message

referenceNostring

DOKU-generated reference number for this binding request

redirectUrlstring

URL for OTP verification page hosted by DOKU. Only present when CHANNEL-ID: DH. Merchant must redirect the customer here to complete the binding via OTP entry.

bankCardTokenstring

Reusable token representing the bound credit card. Present only after OTP verification is successfully completed (final binding state). Use this token for subsequent payment requests.

chargeTokenstring

Charge token from the ALTO network (from the decrypted card data), if applicable