Withdraw from a Card
POST/openapi/v2/funds/cardWithdrawals| Item | Value |
|---|---|
| HTTP method | POST |
| Request path | /openapi/v2/funds/cardWithdrawals |
| Request type | application/json |
Request parameters:
| Field | Type | Required | Description |
|---|---|---|---|
requestNo | string | Yes | Caller-provided business idempotency key, up to 64 characters. |
cardId | string | Yes | Card ID, up to 128 characters. |
amount | number | Yes | Total withdrawal amount including the platform fee; greater than 0, with up to 18 integer digits and 18 decimal places. |
currency | string | Yes | Withdrawal currency; supported values are USD and USDT, up to 32 characters. |
Response data
| Field | Type | Description |
|---|---|---|
orderNo | string | Platform withdrawal order number. |
requestNo | string | Caller-provided business idempotency key. |
cardId | string | Card ID. |
amount | string | Requested total withdrawal amount including the platform fee. |
currency | string | Withdrawal currency. |
feeAmount | string | Total fee; equal to the platform fee for new orders. |
platformFeeAmount | string | Platform fee amount. |
tenantFeeAmount | string | Compatibility field; always 0 for new orders. Historical orders retain their original snapshot. |
totalAmount | string | Requested total withdrawal amount, equal to amount. |
accepted | boolean | Whether the provider has explicitly accepted the request; false when the submission result is unknown. |
status | string | Order status: PROCESSING, SUCCESS, FAILED. |
failCode | string | Failure code; SUBMIT_UNKNOWN when the provider submission result is unknown. |
failMessage | string | Failure message. |
createTime | string | Order creation time. |
completedTime | string | Time when the order reached its terminal state. |
Response amounts are non-scientific decimal strings; trailing zeros are not guaranteed. The request amount remains a JSON number.
Amount relationships:
text
Platform fee = calculated from amount
Principal = amount - platformFeeAmount
Service-provider transfer amount = amount
Tenant credit = Principal
Platform credit = platformFeeAmountIf the provider call throws an error, returns an empty response, or omits transferId, the API returns status=PROCESSING, accepted=false, and failCode=SUBMIT_UNKNOWN. This does not indicate failure: the total withdrawal amount remains frozen until a subsequent definitive success or failure webhook settles the order.
