Frequently Asked Questions

Use production for live keys and sandbox for sandbox keys.

Production: https://{api-domain}/api/v1
Sandbox:    https://{api-domain}/sandbox/api/v1

No. Sandbox keys only work on the sandbox path. Production keys only work on the production path.

Every API request must include the API key in the X-API-KEY header.

X-API-KEY: wc_your_api_key
Content-Type: application/json
Accept: application/json

No. Cards, cardholders, deposits, transactions, webhook events, wallet addresses, and balances are filtered by the authenticated API token.

Typical B2C KYC needs these file IDs:

• idFrontId: IC/passport front image.
• idBackId: IC/passport back image, if applicable.
• idHoldId: selfie or user holding ID, if required.

No. KYC does not support the China (mainland) national identity card. Applicants from China must verify with a passport instead — submit idType: PASSPORT with the passport images.

It is optional when idType is GOVERNMENT_ISSUED_ID_CARD. If omitted, the API forwards 2099-12-31 as the no-expiry placeholder. For other document types, include the expiry date when creating or updating a B2C cardholder.

ipAddress is the end user or cardholder public IP address at the time they submit KYC.

"ipAddress": "203.0.113.10"

Do not use an internal server IP such as 172.18.0.8 in production.

The supported reference value is +65 for Singapore. The API also accepts 65 and normalizes it to +65 before forwarding.

"areaCode": "65",
"mobile": "88569936"

• Town/city codes: GET /common/cities or GET /common/cities/hierarchical.
• Occupation codes: POST /cardholders/occupations.
• Supported countries and area codes: common/reference APIs and POST /cards/support-bins.

Use letters, numbers, spaces, and hyphen only. Avoid symbols such as #, commas, slashes, or special characters.

Wrong: 461B Yishun Ave 6 #10-1061
Right: 461B Yishun Ave 6 10-1061

The initial API response can return a pending status such as wait_audit. The final result is asynchronous and should be checked through webhook events or cardholder list status.

Use POST /cards/create-v2. Required fields depend on the card type returned by POST /cards/support-bins.

Physical:
BIN: 49372410
cardTypeId: 111059
status: online

Virtual:
BIN: 49372410
cardTypeId: 111069
status: online

Not always. Some physical-card flows require the provider card ID instead of the printed PAN. If /cards/bind returns Card does not exist, confirm whether the input is the required provider card ID.

bindExistingCard is the OpenAPI operation ID / SDK function name, not the endpoint URL. The correct API path is POST /api/v1/cards/bind. For physical cards, pass the correct cardTypeId for the card BIN. For BIN 49372410, use cardTypeId: 111059.

curl --location --request POST 'https://wasabi.alphalinx.top/api/v1/cards/bind' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "cardNo": "4937241005769252",
    "cardTypeId": 111059,
    "holderId": 211980
  }'

No. The virtual card issuing fee applies to virtual card creation only. Physical card bind should not be charged as virtual card issuing.

userId and externalUserId mean the end-user/customer ID from your system. You may include either field when requesting the funding address, then use the same value when creating the card top-up order.

POST /wallet/v2/create?coinKey=USDT_TRC20&userId=11
POST /wallet/v2/create?coinKey=USDT_TRC20&externalUserId=11

POST /api/v1/wallet/v2/create?coinKey=USDT_BEP20&externalUserId=CUSTOMER_001

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"
}

Yes. Create a pending card top-up record before or after the user sends funds. The safest match is by txHash. If txHash is not available yet, store sourceAddress, amount, coin key, user ID, and card number so the webhook can match the deposit later.

{
  "coinKey": "USDT_TRC20",
  "internalId": null,
  "externalUserId": "11",
  "userId": "11",
  "address": "FUNDING_WALLET_ADDRESS"
}

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

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

Yes. It is encrypted and can be stored with your customer top-up record. It is not the raw database ID.

The spendable balance is merchant-level under the API token. The user ID is your customer reference for your own top-up record; your backend should enforce that a customer's credited amount is only used for that customer's card.

Use the coin keys returned by POST /wallet/v2/coins. Common supported examples are:

• USDT_TRC20
• USDT_BEP20
• USDT_ERC20

The deposit address service could not issue an address. Common causes are missing configuration, no existing reusable address for that token/coin, address quota reached, or chain mapping not available. Retry only after configuration or quota is resolved.

The net card top-up amount after fees must be at least 1.00 USD. If the calculated net amount is below this minimum, the order is rejected or marked failed and the funds remain in the wallet balance.

Check the top-up status with GET /api/v1/wallet/card-topup-orders/{id} or search by transaction hash with GET /api/v1/wallet/card-topup-orders?txHash=0x....

Use GET /accounts/assets. The response is scoped to the current API token only.

The API token balance does not have enough available funds to cover the requested amount plus applicable fees. Fund the token balance first, then retry.

Yes. Fees can be configured per API token. If no token-specific fee is set, the global fee can be used.

• POST /cards/auth-transactions for authorization/spend records.
• POST /cards/auth-fee-transactions for authorization fee records.
• POST /cards/operation-transactions-v2 for lifecycle operations.
• POST /cards/3ds-transactions for OTP, authorization URL, or activation-code records.

Poll GET /webhook-events. Filter by category, reference_id, merchant_order_no, or status.

Yes. API token users only see webhook events assigned to their own token.

Use a supported mobile code such as +65 for Singapore. Sending 65 is also accepted by this API and normalized before forwarding.

Re-upload the three KYC files using the same API key and same environment, then use the new returned file IDs in create-v2.

This happens inside the KYC cardholder API when the submitted idFrontId, idBackId, or idHoldId cannot be accepted for the current request.

• Upload the KYC documents again using POST /common/files/upload.
• Use the same environment: live files for live KYC, sandbox files for sandbox KYC.
• Use the same X-API-KEY for file upload and cardholders/create-v2.
• Use supported file types: jpg, jpeg, png, or pdf, maximum 2 MB.

The submitted town is not a valid city/town code for the selected country. Fetch valid values from the city API and use the returned code.

The selected cardTypeId does not support the requested cardHolderModel. Use /cards/support-bins to confirm whether the BIN supports B2B or B2C.

The selected card type is physical and requires a physical card number or provider card identifier, depending on the flow.

The card number/provider card ID is not found or not assigned to the account. Confirm the correct card identifier and physical inventory mapping.

The card, cardholder, wallet address, transaction, or event belongs to another API token. Use only resources created or assigned under the current API key.

The API token balance is not enough to perform the operation. Fund the token balance first, then retry the card create or top-up.