Skip to content

Withdraw from a Card ​

POST /openapi/v2/funds/cardWithdrawals
ItemValue
HTTP methodPOST
Request path/openapi/v2/funds/cardWithdrawals
Request typeapplication/json

Request parameters:

FieldTypeRequiredDescription
requestNostringYesCaller-provided business idempotency key, up to 64 characters.
cardIdstringYesCard ID, up to 128 characters.
amountnumberYesTotal withdrawal amount including the platform fee; greater than 0, with up to 18 integer digits and 18 decimal places.
currencystringYesWithdrawal currency; supported values are USD and USDT, up to 32 characters.

Response data ​

FieldTypeDescription
orderNostringPlatform withdrawal order number.
requestNostringCaller-provided business idempotency key.
cardIdstringCard ID.
amountstringRequested total withdrawal amount including the platform fee.
currencystringWithdrawal currency.
feeAmountstringTotal fee; equal to the platform fee for new orders.
platformFeeAmountstringPlatform fee amount.
tenantFeeAmountstringCompatibility field; always 0 for new orders. Historical orders retain their original snapshot.
totalAmountstringRequested total withdrawal amount, equal to amount.
acceptedbooleanWhether the provider has explicitly accepted the request; false when the submission result is unknown.
statusstringOrder status: PROCESSING, SUCCESS, FAILED.
failCodestringFailure code; SUBMIT_UNKNOWN when the provider submission result is unknown.
failMessagestringFailure message.
createTimestringOrder creation time.
completedTimestringTime 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 = platformFeeAmount

If 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.