---
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`

## Request

- The document declares no server URL.
- Auth: none declared. Required headers: `X-PARTNER-ID`, `X-EXTERNAL-ID`, `Authorization`, `X-TIMESTAMP`, `X-SIGNATURE`

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.dev/doku/apis/direct-debit-core-system-notify-binding-to-merchant-emoney-o.md) - [All operations](https://skmtc.dev/doku/apis/direct-debit-core-system-notify-binding-to-merchant-emoney-o/llms.txt) - [OpenAPI document](https://skmtc.dev/doku/apis/direct-debit-core-system-notify-binding-to-merchant-emoney-o/revisions/7887174f57bc?raw)
