Platform Card API

Overview

The Card API is a RESTful backend that wraps the card platform. As a third-party developer you interact only with this API — you never call Platform directly.

Base URL

# Live (Production)
https://{api-domain}

# Sandbox
https://{api-domain}/sandbox

Authentication

Every request to /api/v1/* must include your API key in the X-API-KEY request header.

# Example — all requests require this header
X-API-KEY: wc_YourSecretKeyHere
Content-Type: application/json

Getting a Key

API keys are issued by the platform administrator via the admin portal. Each key is tied to your developer account. Contact the admin to receive yours.

Missing or Invalid Key

{
  "success": false,
  "code":    401,
  "msg":     "Invalid or missing API key.",
  "data":    null
}

Request Format

All requests use JSON bodies with Content-Type: application/json. Unless otherwise stated, endpoints use the POST method.

cURL Example

curl -X POST https://{api-domain}/sandbox/api/v1/cardholders/occupations \
  -H "X-API-KEY: wc_YourSecretKeyHere" \
  -H "Content-Type: application/json"

Request with Body

curl -X POST https://{api-domain}/sandbox/api/v1/cards/balance \
  -H "X-API-KEY: wc_YourSecretKeyHere" \
  -H "Content-Type: application/json" \
  -d '{
    "cardNo": "4111111111111111"
  }'

Response Format

Every response — success or error — uses the same JSON envelope:

{
  "success": true,      // boolean — true only when code=200
  "code":    200,       // integer status code
  "msg":     "Success",  // human-readable message
  "data":    { ... }    // payload — object, array, or null
}

Always check success === true (or code === 200) before processing data.

Successful List Response Example

{
  "success": true,
  "code":    200,
  "msg":     "Success",
  "data": {
    "total":   42,
    "records": [ ... ]
  }
}

Error Codes

Validation Error Example

{
  "success": false,
  "code":    422,
  "msg":     "Validation failed.",
  "data": {
    "email": [ "The email field must be a valid email address." ],
    "cardHolderModel": [ "The selected card holder model is invalid." ]
  }
}

Rate Limiting

Each API key is limited to 60 requests per minute. Exceeding this returns HTTP 429. Implement exponential back-off in your client.

# Retry strategy (example)
attempt 1: immediate
attempt 2: wait 1s
attempt 3: wait 2s
attempt 4: wait 4s

Common — Reference Data

Lookup tables required for other API calls. Cache these responses — they rarely change.

Wallet

On-chain top-up addresses, deposit orders, and wallet transaction history.

Create Top-Up Address

Call POST /api/v1/wallet/v2/create?coinKey=USDT_BEP20. The user should deposit to data.address. Pass externalUserId or userId for tracking, but the returned address is the funding wallet address for the selected network.

{
  "success": true,
  "code": 200,
  "msg": "SUCCESS",
  "data": {
    "coinKey": "USDT_BEP20",
    "externalUserId": "CUSTOMER_001",
    "chain_id": "56",
    "token_id": null,
    "address": "0x..."
  }
}

Create Card Top-Up Order

Create this record so the wallet deposit webhook knows which card to load. The system matches by txHash first, then falls back to API token, amount, source address, coin key, and pending order uniqueness. If the same txHash is submitted again for the same card, the existing order is returned. If the same txHash is submitted for a different card, the API rejects it.

POST /api/v1/wallet/card-topup-orders

{
  "cardNo": "USER_CARD_NO",
  "amount": "100.00",
  "coinKey": "USDT_BEP20",
  "externalUserId": "CUSTOMER_001",
  "sourceAddress": "0xUSER_SENDING_WALLET",
  "txHash": "0xTRANSACTION_HASH"
}

When the wallet deposit is confirmed, the deposit fee is deducted and the net amount is loaded to the card automatically. The net card top-up amount after fees must be at least 1.00 USD; otherwise the order is rejected or marked failed and the funds remain in the wallet balance. The customer does not need to call /cards/deposit for this automated flow.

Check Card Top-Up Order Status

Use GET /api/v1/wallet/card-topup-orders/{id} for one order, or search using id, txHash, cardNo, externalUserId, or status.

GET /api/v1/wallet/card-topup-orders?txHash=0xTRANSACTION_HASH

Status values are pending, deposit_requested, completed, and failed. If status is failed, check errorMessage.

If the chain is not configured yet, the API returns HTTP 503:

{
  "success": false,
  "code": 503,
  "msg": "Deposit address chain mapping is not configured for USDT_BEP20.",
  "data": null
}

POST /api/v1/wallet/v2/address-list returns the funding wallet addresses. Deposit callbacks are handled internally; clients should not call the internal callback endpoint directly.

Cards

Full card lifecycle: create, manage, fund, and query transaction history.

Cardholders

KYC onboarding and cardholder lifecycle. Cardholder creation is async — the initial response returns wait_audit and the final result arrives via webhook.

B2B vs B2C Model

Accounts

Merchant wallet accounts — balances, ledger history, and fund transfers between accounts.

Work Orders

Submit and track platform work orders (e.g. card activation requests).

Webhooks — Overview

Several operations are asynchronous: the API returns an immediate pending status, and the final result is delivered later via webhook. Your server must poll the Webhook Events API to retrieve these results.

Async Operations (always poll for final result)

Webhook Event Reference

Cardholder Status Values

Polling Webhook Events

Use GET /api/v1/webhook-events to retrieve stored async results. Filter by category and reference_id for the specific operation you're waiting on.

Example: Poll for cardholder creation result

# Step 1 — create cardholder, get holderId from response
curl -X POST https://{api-domain}/sandbox/api/v1/cardholders/create-v2 \
  -H "X-API-KEY: wc_..." -d '{ "cardHolderModel": "B2C", ... }'
# Response: { "data": { "holderId": 124024, "status": "wait_audit" } }

# Step 2 — poll until status is pass_audit or reject
curl "https://{api-domain}/sandbox/api/v1/webhook-events?category=card_holder&reference_id=124024" \
  -H "X-API-KEY: wc_..."

Query Parameters

Sample Response

{
  "success": true,
  "code": 200,
  "data": {
    "total": 1,
    "data": [
      {
        "id": 5,
        "category":          "card_holder",
        "reference_id":     "124024",
        "merchant_order_no": "ORDER20250101000001",
        "status":           "pass_audit",
        "payload": {          // full raw payload from platform
          "holderId":    124024,
          "status":      "pass_audit",
          "description": "Approved"
        },
        "created_at": "2026-04-18T10:30:00.000000Z"
      }
    ]
  }
}