Skip to main content

​
API List (merchant-api)

All interface paths use the /open-api prefix. Except for Get Token, all other interfaces require the headers: Api-Key, Timestamp, Access-Token.

​
1. Common Interfaces (Both Credit & Authorization Modes)

Interfaces supported by both credit extension and authorization modes.

​
2. Credit Extension Mode Interfaces (CREDIT_EXTENSION)

Only merchants with credit extension integration mode can call these.

​
3. Authorization Mode Interfaces (AUTHORIZATION)

Only merchants with authorization integration mode can call these.

​
4. Transaction Simulation Interfaces

Sandbox integration APIs: simulate card transactions and push Webhooks to your callback URL. Do not use the Api-Key / Access-Token headers. See Transaction Simulation Overview. Path prefix:
  • Sandbox: https://sandbox-openplatform.keysecure.io/open-api/v1/simulate

​
Quick Navigation

​
By Business Flow

Cardholder Flow:
  1. Get Token → GET /merchant/token
  2. Cardholder authentication application → POST /cardholder/apply
  3. Query cardholder → POST /cardholder/list or GET /cardholder/{cardholder_no}/info
Card Application Flow:
  1. Get card packages/BINs → POST /card/package/list or POST /card/support/bins
  2. Apply for card → POST /card/apply
  3. Query card list → POST /card/list or get card details → GET /card/{card_no}/detail
  4. Activate physical card → POST /card/active (physical cards only)
  5. Set PIN → POST /card/pin/set (physical cards, optional)
Transaction Flow:
  1. Query consumption details → GET /consume/{consume_no}/info
  2. Query consumption list → POST /consume/list
Account Flow (Credit Extension Mode):
  1. Query account info → GET /account/{cardholder_no}/info
  2. Execute transfer → POST /account/transfer
  3. Query transfer flow → POST /account/transfer/list
Transaction Simulation Flow:
  1. Simulate authorization → POST /simulate/auth
  2. Simulate clearance success / failure → POST /simulate/consumption_clear or POST /simulate/consumption_fail
  3. Simulate reversal / refund → POST /simulate/reversal or POST /simulate/refund

​
By HTTP Method

GET Methods:
  • /merchant/token — Get Token
  • /cardholder/{cardholder_no}/info — Cardholder details
  • /card/{card_no}/detail — Card details
  • /card/{card_no}/private/info — Card privacy info (PCI)
  • /consume/{consume_no}/info — Consumption details
  • /account/{cardholder_no}/info — Account info
  • /merchant/client/{card_no}/token — PCI Client Token
POST Methods:
  • /cardholder/apply — Cardholder application
  • /cardholder/list — Cardholder list
  • /card/apply — Card application
  • /card/list — Card list
  • /card/active — Card activation
  • /card/status/update — Update card status
  • /card/pin/set — Set PIN
  • /card/package/list — Card packages (credit)
  • /card/support/bins — Supported BINs (auth)
  • /consume/list — Consumption list
  • /account/transfer — Transfer (credit)
  • /account/transfer/list — Transfer flow (credit)
  • /merchant/pci/card/detail — PCI card sensitive info

​
Permissions & Prerequisites

​
Authentication Requirements

​
Prerequisites

Before Card Application:
  • The cardholder must exist and have passed KYC authentication (status: Approved)
  • Otherwise returns 2002 (cardholder not found) or 2005 (authentication failed)
Card Privacy Interface:
  • Requires merchant to have PCI enabled
  • Not enabled returns 1013
  • Card status must be Activated
Physical Card Activation:
  • Card status must be ToActivate
  • CVV must be AES-encrypted before being passed
Set PIN:
  • Physical cards only
  • Card status must be Activated
  • PIN must be AES-encrypted before being passed

​
Error Handling

All error responses follow a unified format:
Common error codes (see “Appendix” → “Error Codes”): For more error codes, see “Appendix” → “Error Codes”.