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.
ModuleMethodPathDescription
AuthenticationGET/open-api/v1/merchant/tokenGet Access-Token (only requires Api-Key; no Access-Token needed)
CardholderPOST/open-api/v1/cardholder/applyCardholder authentication application
CardholderPOST/open-api/v1/cardholder/listCardholder list
CardholderGET/open-api/v1/cardholder//infoCardholder details
CardPOST/open-api/v1/card/applyApply for card (pass package_no for credit, card_bin_no for auth)
CardPOST/open-api/v1/card/listCard list
CardGET/open-api/v1/card//detailCard details
CardGET/open-api/v1/card//private/infoCard privacy JSON (data is an AES-encrypted string)
CardPOST/open-api/v1/card/activePhysical card activation (cvv must be AES-encrypted)
CardPOST/open-api/v1/card/status/updateUpdate card status (Frozen / Activated / Delete)
CardPOST/open-api/v1/card/pin/setSet physical card PIN (pin must be AES-encrypted)
ConsumptionGET/open-api/v1/card/consume//infoConsumption details
ConsumptionPOST/open-api/v1/card/consume/listConsumption list
PCIGET/open-api/v1/merchant/client//tokenIssue PCI Client Access Token (called when integrating iframe)

​
2. Credit Extension Mode Interfaces (CREDIT_EXTENSION)

Only merchants with credit extension integration mode can call these.
ModuleMethodPathDescription
AccountPOST/open-api/v1/account/transferCardholder fund transfer (fixed to TUSDT)
AccountGET/open-api/v1/account//infoCardholder account list
AccountPOST/open-api/v1/account/transfer/listAccount transfer flow list
CardPOST/open-api/v1/card/package/listCard package list

​
3. Authorization Mode Interfaces (AUTHORIZATION)

Only merchants with authorization integration mode can call these.
ModuleMethodPathDescription
CardPOST/open-api/v1/card/support/binsSupported card BIN list

​
4. Transaction Simulation Interfaces (Webhook Testing)

Integration/testing interfaces. After querying and assembling data, simulate Webhook callbacks to the business system. Do not use the standard Api-Key / Access-Token authentication headers for these interfaces. Path prefix:
  • Sandbox: https://sandbox-openplatform.keysecure.io/open-api/v1/simulate
ModuleMethodPathDescription
SimulationPOST/authSimulate authorization
SimulationPOST/consumption_clearSimulate consumption clearance success
SimulationPOST/consumption_failSimulate consumption failure
SimulationPOST/reversalSimulate reversal/cancellation
SimulationPOST/refundSimulate refund

​
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

​
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

InterfaceRequires Api-KeyRequires Access-TokenNotes
Get Token✓✗Only requires Api-Key + Timestamp
Other interfaces✓✓Requires full authentication

​
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: 
{
  "code": 1003,
  "msg": "IP address not allowed"
}
Common error codes (see “Appendix” → “Error Codes”):
CodeMeaningCommon Cause
1003IP address incorrectRequest IP not in whitelist
1005Timestamp expiredTimestamp deviation from server exceeds 60 seconds
1007Access-Token expiredToken has expired or is invalid
2002Cardholder does not existCardholder not found
4005Current card status does not allow this operationCard status unsupported for this operation
For more error codes, see “Appendix” → “Error Codes”.