HUO BI LABUAN API Specification

This document outlines the API integration guidelines for the HUO BI LABUAN Card Management System. The API utilizes a single-endpoint RPC architecture via HTTPS POST, processing encrypted JSON payloads.

1.1 Environments

Production API URL: https://huobilabuan.com/api/card/

Staging API URL: https://huobilabuan.com/api/staging-card/

2. Communication Protocol & Security

All communications must be executed over HTTPS using the POST method with UTF-8 encoding.

2.1 Global HTTP Headers

Header Key	Type	Description
`lang`	String	Localization. `zh_CN` (Simplified Chinese), `zh_Hant` (Traditional Chinese), `en_US` (English).
`merchantId`	String	Your assigned Merchant Code (e.g., `M000000053`).
`version`	String	API Version. Fixed value: `2.0.0`.
`sign`	String	SHA256 Signature for request verification.

2.2 Standard Request Payload (Body)

Parameter	Type	Required	Description
`version`	String	Yes	Fixed value: `2.0.0`.
`method`	String	Yes	The target API method name (e.g., `card.createCard`).
`timestamp`	Integer	Yes	Current epoch timestamp in milliseconds.
`token`	String	No	JWT token (Required for specific user/card operations based on config).
`data`	Mixed	Yes	The business payload (JSON, Array, or String). Must be AES encrypted.

2.3 Standard Response Object

Parameter	Type	Description
`status`	String/Int	HTTP/Business status code (`200` = Success, `500` = Failure, etc.).
`success`	Boolean	Indicates if the transaction was successful (`true`/`false`).
`message`	String	Human-readable response message.
`response`	Mixed	The decrypted business data payload. Can be an Object, Array, or empty.

2.4 Cryptography Flow

Step 1: Generate Signature

Applied to Header sign

Algorithm: SHA256
Formula: SHA256(Raw JSON Request String + AppId)

Step 2: Encrypt Payload

Applied to Body data

Algorithm: AES/ECB/PKCS7Padding
Key: Merchant AES Key from dashboard.
Note: Response `data` must be decrypted using this key.

3. API Endpoints Reference

Note: All requests are made to the base RPC endpoint URL using the method parameter to route the request.

3.1 Get System Dictionary POST

Retrieves platform configuration enumerations (e.g., supported countries).

method: common.getDict

Request Payload (Data Type: String)

{
  "version": "2.0.0",
  "method": "common.getDict",
  "timestamp": 1735196181137,
  "data": "sys_country"
}

Response Payload

{
  "message": "Transaction successful",
  "status": "200",
  "success": true,
  "response": [
    {
      "dictKey": "ARE",
      "dictLabel": "阿联酋",
      "dictValue": "AE",
      "remark": "(784)United Arab Emirates"
    }
  ]
}

3.2 Get Supported Card Products POST

Retrieves available card tiers, limits, and issuance pricing.

method: card.getSupportCardList

Request Payload (Data Type: Empty String)

{
  "version": "2.0.0",
  "method": "card.getSupportCardList",
  "timestamp": 1735531570514,
  "data": "",
  "token": "eyJ0eXAiOiJKV1..."
}

Response Payload

{
  "message": "Transaction successful",
  "status": "200",
  "success": true,
  "response": [
    {
      "id": 1,
      "cardName": "普卡",
      "cardBin": "49372401",
      "cardInstitution": "VISA",
      "cardType": "SINGLE",
      "cardCurrency": "USD",
      "cardLimit": 500.0000,
      "cardChargeLimit": 500.0000,
      "cardTransLimit": 500.0000,
      "rateAmount": 5,
      "rateCurrency": "USD"
    }
  ]
}

3.3 Create & Issue Card POST

Issues a new card to a specific cardholder profile.

method: card.createCard

Request Payload (Data Type: JSON Object)

{
  "version": "2.0.0",
  "method": "card.createCard",
  "timestamp": 1735532366771,
  "token": "eyJ...",
  "data": {
    "firstName": "fff",
    "lastName": "lll",
    "country": "CN",
    "phoneNumber": "13800138000",
    "email": "13800138001@139.com",
    "address": "testAddr",
    "addrCity": "testCity",
    "addrCountry": "CN",
    "postalCode": "123456",
    "supportCardId": "8"
  }
}

Response Payload

{
  "message": "Transaction successful",
  "status": "200",
  "success": true,
  "response": {
    "id": 84,
    "cardNo": "461199*********",
    "cardName": "普卡",
    "cardInstitution": "VISA",
    "cardCurrency": "USD",
    "cardStatus": "PENDING",
    "customerId": 47,
    "createTime": "2025-05-04 10:02:33"
  }
}

3.4 Get Card List POST

Fetches a high-level list of all cards issued by the merchant.

method: card.getCardList

Request Payload

{
  "version": "2.0.0",
  "method": "card.getCardList",
  "timestamp": 1735532885688,
  "data": "",
  "token": "eyJ..."
}

Response Payload

{
  "message": "Transaction successful",
  "success": true,
  "response": [
    {
      "id": 44,
      "cardNo": "49372401******8012",
      "cardInstitution": "VISA",
      "cardCurrency": "USD",
      "cardStatus": "ACTIVE",
      "createTime": "2024-11-06 16:27:22"
    }
  ]
}

3.5 Get Card Info POST

Retrieves general status and balance information for a specific card.

method: card.getCardInfo

Request Payload (Data: Card ID Integer)

{
  "version": "2.0.0",
  "method": "card.getCardInfo",
  "timestamp": 1735533158066,
  "data": 44,
  "token": "eyJ..."
}

Response Payload

{
  "message": "Transaction successful",
  "success": true,
  "response": {
    "id": "44",
    "cardNo": "49372401******8012",
    "cardBalance": "100.00",
    "cardStatus": "ACTIVE",
    "formFactor": "VIRTUAL"
  }
}

3.6 Get Card Details (Secure PCI Data) POST

Retrieves sensitive data (Full PAN, CVV, Expiry) for a specific card.

method: card.getCardInfoDetail

Request Payload (Data: Card ID Integer)

{
  "version": "2.0.0",
  "method": "card.getCardInfoDetail",
  "timestamp": 1735533511171,
  "data": 44
}

Response Payload

{
  "message": "Transaction successful",
  "success": true,
  "response": {
    "cardNumber": "400000000000012",
    "expireDate": "01/29",
    "cvv": "000",
    "firstName": "fname",
    "lastName": "lname"
  }
}

3.7 Card Top-Up (Recharge) POST

Funds a specific card from the merchant's master balance.

method: card.reCharge

Request Payload

{
  "version": "2.0.0",
  "method": "card.reCharge",
  "timestamp": 1735532366771,
  "data": {
    "cardId": 44,
    "amount": "10.12",
    "merchantOrderNo": "M_ORD_12345"
  }
}

Response Payload

{
  "message": "Transaction successful",
  "status": "200",
  "success": true,
  "response": {}
}

3.8 Get Card Transactions POST

Retrieves authorization and fee history for a card.

method: common.getTransList

Request Payload

{
  "version": "2.0.0",
  "method": "common.getTransList",
  "timestamp": 1735532366771,
  "data": {
    "cardId": 44,
    "pageNum": 1,
    "pageSize": 10
  }
}

Response Payload

{
  "success": true,
  "response": {
    "total": 52,
    "records": [
      {
        "orderNo": "TRN_1753",
        "cardNo": "49372401******8012",
        "transAmount": "1.68",
        "transCurrency": "USD",
        "transStatus": "SUCCESS",
        "transactionType": "AUTHORIZATION",
        "billMerchantName": "WEIXIN*Crying"
      }
    ]
  }
}

3.9 Get Card Recharge Transactions POST

Retrieves the history of top-ups applied to cards.

method: common.getCardRechargeTransList

Request Payload

{
  "version": "2.0.0",
  "method": "common.getCardRechargeTransList",
  "data": {
    "cardId": 44,
    "pageNum": 1,
    "pageSize": 10
  }
}

Response Payload

{
  "success": true,
  "response": {
    "total": 16,
    "records": [
      {
        "orderNo": "ORC_0000001727",
        "cardNo": "49372401******8012",
        "chargeAmount": 10.00,
        "chargeCurrency": "USD",
        "status": "SUCCESS"
      }
    ]
  }
}

3.10 Get Cardholder List POST

Retrieves a list of registered cardholders under the merchant.

method: user.getCardHolders

Request Payload

{
  "version": "2.0.0",
  "method": "user.getCardHolders",
  "data": ""
}

Response Payload

{
  "success": true,
  "response": [
    {
      "id": 23,
      "firstName": "ff",
      "lastName": "ll",
      "email": "*********@163.com",
      "country": "CN"
    }
  ]
}

3.11 Bind Physical Card POST

Maps a physical card PAN to a specific Cardholder ID.

method: user.bindPhysicsCard

Request Payload (Data: Array)

{
  "version": "2.0.0",
  "method": "user.bindPhysicsCard",
  "data": [
    "4096360800020104",
    "23"
  ]
}

Response Payload

{
  "success": true,
  "response": {
    "cardId": 51
  }
}

3.12 Activate Physical Card POST

Activates a physical card using the Card ID, Activation Code, and PIN.

method: card.activateCard

Request Payload (Data: Array)

{
  "version": "2.0.0",
  "method": "card.activateCard",
  "data": [
    "49",
    "123456",
    "888888"
  ]
}

Response Payload

{
  "success": true,
  "response": {}
}

3.13 Create Cardholder Profile POST

Registers a new customer profile required before card issuance.

method: card.createCardHolder

Request Payload (Data: JSON Object)

{
  "version": "2.0.0",
  "method": "card.createCardHolder",
  "data": {
    "firstName": "ff",
    "lastName": "gg",
    "country": "CN",
    "phoneNumber": "13900000005",
    "email": "abc2@qq.com",
    "address": "akljhcioe",
    "addrCity": "ccc",
    "addrCountry": "CN",
    "postalCode": "123456"
  }
}

Response Payload

{
  "success": true,
  "response": {
    "id": 134,
    "userId": 47,
    "firstName": "ff",
    "lastName": "gg",
    "cardholderStatus": "SUCCESS"
  }
}

3.14 Query Order POST

Queries the real-time status of a specific recharge or transaction order.

method: trans.orderQuery

Request Payload

{
  "version": "2.0.0",
  "method": "trans.orderQuery",
  "data": {
    "orderNo": "ORC_0000000337"
  }
}

Response Payload

{
  "success": true,
  "response": {
    "orderNo": "ORC_0000000337",
    "cardNo": "461199******1048",
    "chargeAmount": 500.00,
    "status": "SUCCESS"
  }
}

3.15 Query Merchant Balance POST

Queries the available pre-funded balance for the master merchant account.

method: trans.getBalance

Request Payload (Data: Array)

{
  "version": "2.0.0",
  "method": "trans.getBalance",
  "data": [1]
}

Response Payload

{
  "success": true,
  "response": {
    "amount": 975914.9800,
    "freezeAmount": 0.0000,
    "currency": "USD",
    "status": "SUCCESS"
  }
}