Skip to main content
All API responses use a unified JSON structure. The HTTP status code is generally 200; use the response body’s code to determine success or failure.

​
Response Structure

Field NameTypeDescription
codenumberStatus code. 0 = success; non-0 = failure
msgstringDescription message (multilingual, see notes below)
dataobject/array/stringResponse data (only returned on success; some interfaces may return an encrypted string)

​
Basic Examples

Success response: 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "access_token": "your_token",
    "expired_time": 1716393600000
  }
}
Failure response: 
{
  "code": 1003,
  "msg": "IP address not allowed"
}

​
Multilingual Support

The msg field supports multilingual responses, controlled via the Language request header:
Header ValueResponse LanguageNotes
zh_CNChinese (Simplified)Chinese Simplified
en_USEnglishEnglish
Not provided or otherEnglish (default)Default English
Example: 
curl --request GET \
     --url https://sandbox-openplatform.keysecure.io/open-api/v1/merchant/token \
     --header 'Api-Key: your_api_key' \
     --header 'Timestamp: 1716307200000' \
     --header 'Language: zh_CN'

​
Special Cases

​
1. List Interfaces

The data of list interfaces is an object containing a list array: 
{
  "code": 0,
  "msg": "Success",
  "data": {
    "list": [
      { "id": "1", "name": "item1" },
      { "id": "2", "name": "item2" }
    ]
  }
}

​
2. Card Privacy Information Interface

The response data is an encrypted string, which the merchant must decrypt using MerchantEncryptUtil: 
{
  "code": 0,
  "msg": "Success",
  "data": "Base64EncodedEncryptedString..."
}
After decryption, the following JSON structure is obtained: 
{
  "card_no": "C202605220001",
  "card_unique_no": "MERCHANT_CARD_001",
  "cvv": "123",
  "pan": "4111111111111111",
  "exp_year": "2028",
  "exp_month": "12"
}

​
3. Parameter Validation Failure

When parameter validation fails, msg is prefixed with the snake_case field name in the format field_name validation message. Examples:
  • cardholder_no invalid parameter — Required field validation failed.
  • phone_code invalid parameter — Country code format error or contains a + sign.
  • city only supports English input — Address field English validation failed.
  • address_info.city invalid parameter — Nested object field validation failed.

​
HTTP Status Codes

HTTP Status CodeDescription
200Request succeeded (check code field to determine business outcome)
400Request format error or invalid parameters
401Authentication failed (Api-Key / Access-Token invalid)
403Access forbidden (IP not in whitelist, etc.)
404Resource not found
500Server error

​
Error Code Ranges

RangeDescription
1xxxCommon exceptions, permission exceptions, authentication exceptions, PCI-related
2xxxMember/cardholder-related exceptions
3xxxAccount and transfer-related exceptions
4xxxCard, card transaction, and card privacy-related exceptions
See “Appendix” → “Error Codes”.

​
Field Name Conventions

All JSON field names are in snake_case (consistent with interface parameters). Examples:
  • cardholder_no — Cardholder order number
  • card_last_no — Last four digits of card number
  • total_balance — Total account balance
  • consume_no — Consumption order number

​
Timestamp Format

All time fields in responses are Unix millisecond timestamps (13 digits). Example: 
{
  "time": 1716307200000,
  "expired_time": 1716393600000
}
Conversion example (JavaScript): 
const timestamp = 1716307200000; // milliseconds
const date = new Date(timestamp);
console.log(date.toISOString()); // 2024-05-21T12:00:00.000Z