---
title: "Card Binding (Card Registration)"
method: POST
path: "/direct-debit/core/v1/registration-card-bind"
tags: ["Binding"]
---

# Card Binding (Card Registration)

`POST /direct-debit/core/v1/registration-card-bind`

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.

## Headers

- `X-PARTNER-ID` string, required
- `X-EXTERNAL-ID` string, required
- `Authorization` string, required
- `X-TIMESTAMP` string, required
- `X-SIGNATURE` string, required
- `CHANNEL-ID` 'DH' | 'H2H'

## Request body

- CardBindingRequest — Request body for card binding (registration)
  - `partnerReferenceNo` string — Merchant's unique reference number for this binding request
  - `cardData` string, 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.
  - `custIdMerchant` string, required — Merchant's unique identifier for the customer
  - `journeyId` string — Optional journey or session ID for tracking the binding flow end-to-end
  - `phoneNo` string — Customer's phone number (used for OTP delivery during OTP verification step)
  - `additionalInfo` BindingAdditionalInfo, required — Additional information for the card binding request
    - `channel` 'KARTU_KREDIT_INDONESIA', required — Product channel. Must be `KARTU_KREDIT_INDONESIA` for this operation.
    - `customerName` string — Full name of the cardholder
    - `email` string, email — Email address of the cardholder
    - `address` string — Cardholder's billing address
    - `dateOfBirth` string — Cardholder's date of birth in `YYYYMMDD` format
    - `idCard` string — National ID card number (KTP) of the cardholder
    - `country` string — ISO 3166-1 alpha-2 country code of the cardholder
    - `successRegistrationUrl` string — Merchant URL to redirect to after successful OTP verification
    - `failedRegistrationUrl` string — Merchant URL to redirect to after failed OTP verification

## Response `200`

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.

- CardBindingResponse — Response body for a successful card binding request
  - `responseCode` string — Response code: HTTP Status (3) + Service Code `01` (2) + Case Code (2). Example: `2000100` = HTTP 200 + service `01` + case `00` (Successful).
  - `responseMessage` string — Human-readable response message
  - `referenceNo` string — DOKU-generated reference number for this binding request
  - `redirectUrl` string — 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.
  - `bankCardToken` string — 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.
  - `chargeToken` string — Charge token from the ALTO network (from the decrypted card data), if applicable
  - `additionalInfo` BindingResponseAdditionalInfo — Additional information in the binding response
    - `custIdMerchant` string — The merchant's customer ID echoed back from the request
    - `status` 'PENDING' | 'SUCCESS' | 'FAILED' — Current binding status of the token: - `PENDING` — OTP verification not yet completed - `SUCCESS` — Binding fully completed - `FAILED` — Binding failed
    - `authCode` string — Session ID / authentication code for the OTP verification step. Used internally by the redirect URL (DH) or passed to the OTP verification API (H2H).

## Other responses

- `202` — Request in progress (timeout from ALTO network; may still succeed asynchronously)
- `400` — Bad request — missing or invalid fields
- `401` — Authentication failure — invalid token or card data decryption failed
- `403` — Forbidden — transaction not permitted or card restrictions
- `404` — Not found — merchant, card, or transaction record not found
- `409` — Conflict — duplicate transaction or duplicate token
- `500` — Internal server error or external system malfunction

---

[API](https://skmtc.net/doku/apis/direct-debit-core-system-notify-binding-to-merchant-emoney-o.md) · [All operations](https://skmtc.net/doku/apis/direct-debit-core-system-notify-binding-to-merchant-emoney-o/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/doku/direct-debit-core-system-notify-binding-to-merchant-emoney-o/revisions/7887174f57bc/schema)