Skip to main content

Create Crypto Transfers

Overview​

A crypto transfer sends USDT from the user's available balance to an external wallet address on the TRON network. Once the transfer is created, the specified amount is immediately deducted from the user's balance.

If the transfer is rejected or fails, the funds are automatically refunded back to the user's balance.

Every crypto transfer points to a payout destination: a saved wallet address, optionally identified with a friendly label so it is easy to find later. You can either reference a destination you already created, or describe the wallet inline and let the API create it for you.


Endpoint​

POST /payout/withdrawal

API Reference: Create a crypto payout


Authentication​

This endpoint requires a valid x-api-key and a Bearer Token issued to a store role in headers.

x-api-key: <your_api_key>
Authorization: Bearer <access_token>

Non store user requests will be rejected.

See the Authentication Guide to see more details.


Request Body​

FieldTypeRequiredDescription
amountstringYesPositive decimal amount with up to two decimals. Example: "1000.50"
currencystringYesMust be USDT
destinationobjectYesThe wallet that receives the funds. See Payout Destination

Payout Destination​

The destination object accepts one of two shapes. They are mutually exclusive: sending id together with the wallet fields is rejected.

Option A — Reuse a saved destination​

Send the id of an existing, active payout destination.

{
"destination": {
"id": "123e4567-e89b-12d3-a456-426614174000"
}
}

Option B — Provide the wallet inline​

Send the wallet details and the API finds the matching destination or creates it if it does not exist yet.

FieldRequiredDescription
railYesNetwork used to reach the wallet. Use TRON for USDT on TRON
accountIdentifierValueYesThe destination wallet address. It is validated against the selected rail
labelNoFriendly name for the wallet, e.g. "Treasury wallet"
{
"destination": {
"rail": "TRON",
"accountIdentifierValue": "TKbVBEh8tDZCnqw9EqL7fTRHxbTAPBrnEX",
"label": "Treasury wallet"
}
}

Wallet destinations do not require country, institution or beneficiary data.

An invalid wallet address for the selected rail will result in a validation error.

Managing destinations ahead of time​

You can also create and look up destinations on their own, which is useful to build a saved list of wallets for your users:

Editing a destination never affects past crypto transfers: each transfer keeps a snapshot of the destination as it was when the transfer was created.


Request Examples​

A created crypto transfer starts with pending status

Using a wallet address​

curl -X POST "/api/v1/payout/withdrawal" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-d '{
"amount": "1000.50",
"currency": "USDT",
"destination": {
"rail": "TRON",
"accountIdentifierValue": "TKbVBEh8tDZCnqw9EqL7fTRHxbTAPBrnEX",
"label": "Treasury wallet"
}
}'

Using a saved destination​

curl -X POST "/api/v1/payout/withdrawal" \
-H "Content-Type: application/json" \
-H "x-api-key: <your_api_key>" \
-H "Authorization: Bearer <your_access_token>" \
-d '{
"amount": "1000.50",
"currency": "USDT",
"destination": {
"id": "123e4567-e89b-12d3-a456-426614174000"
}
}'

Response Behavior​

A successful request returns 201 Created with the created payout:

  • type is withdrawal
  • payoutNumber is the unique reference of the transfer
  • destination is a snapshot of the wallet used, including the id and label of the saved destination

You can retrieve it later with Get payout by ID, or list your transfers with Get paginated list of payouts filtering by type=withdrawal.


Transfer Lifecycle​

The status field of the payout progresses through the following values:

StatusDescription
pendingTransfer created. Awaiting processing.
in_progressTransfer is being actively processed.
sanction_reviewTransfer is on hold while a compliance review is completed.
paidTransfer completed successfully. Terminal state.
rejectedTransfer rejected. Funds are restored. Terminal state.

Balance Impact​

EventEffect on Balance
Transfer createdAmount is immediately deducted from the user's available balance
Transfer rejectedAmount is automatically restored to the user's balance

Daily Limit​

Crypto transfers count toward the store's daily payout limit, which is shared with bank transfers. Check the remaining amount before creating a transfer with Get the daily payout limit usage. Exceeding it returns the PAYOUT_DAILY_LIMIT_EXCEEDED error code.


Important Notes​

  • A transfer with an amount higher than the user's available balance will result in an error
  • Crypto transfers initiate real and irreversible on-chain operations. Double-check the wallet address and network before submitting
  • Sending a currency your account is not allowed to operate returns 403 Forbidden