API integration
Send payouts from your Volet.com account to Volet.com users and external crypto wallets through the Merchant API.
The Mass Payout API lets your application create, validate, and track payout transactions programmatically.
You can use the API for three main payout scenarios:
- Payouts to Volet.com users — send funds from your Volet.com account to another Volet.com account.
- Crypto payouts without conversion — send cryptocurrency from the same crypto balance to an external crypto wallet.
- Crypto payouts with conversion — send cryptocurrency to an external crypto wallet from another supported balance, such as USD, EUR, USDT, or another cryptocurrency.
An AI agent can send payouts from your own wallet through a smart contract, without the API. You set up the agent once with its permissions and limits, and it makes payouts or purchases on your behalf. See Automated on-chain payouts.
How mass payouts work through the API
The Merchant API creates one payout transaction per request.
For mass payout batches, your backend prepares a list of recipients and creates a separate payout transaction for each item in the batch.
A typical batch flow:
- Prepare a payout batch in your system.
- Check your available Volet.com wallet balances.
- Check limits, tariffs, and exchange rates where needed.
- Validate each payout before creation.
- Create payout transactions through the API.
- Store returned transaction IDs in your system.
- Track payout statuses through the API.
- Reconcile completed, failed, canceled, or refunded payouts.
Before you start
To send mass payouts through the API, you need:
- A verified Volet.com account.
- A configured API in the Payment Tools section.
- Sufficient balance in your Volet.com account.
- Recipient details required for each payout method.
See Enable mass payouts to create and configure your API.
Authentication
Merchant API requests require authentication headers.
Include the following headers in each API request:
| Header | Description |
|---|---|
Api-Name | API name configured in your Volet.com account. |
Account-Email | Email address of the Volet.com account that owns the API. |
Authentication-Token | SHA-256 token generated from password:YYYYMMDD:HH (UTC), where the password is set in your Volet.com account under Payment Tools. |
For example:
SHA256("MySecret123:20261026:14")
produces:
c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd
The token value changes every UTC hour. Generate a new token immediately before each request. The API also accepts the tokens of the previous and the next hour, so a request sent at the turn of the hour or from a server with a slightly wrong clock is not rejected.
Only the generated token is sent to the API. Never send your API password.
Keep your API password private. Never expose API credentials or authentication tokens in frontend code, mobile apps, bots, or client-side scripts.
Example authenticated request that validates a USDT TRC-20 payout to an external wallet:
curl -X POST https://api.volet.com/api/withdrawal/validation/cryptowallet \
-H "Content-Type: application/json" \
-H "Api-Name: my-payouts-api" \
-H "Authentication-Token: c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd" \
-d '{
"srcWalletId": "USDT123456789012",
"amount": 100,
"action": "GIVE",
"note": "Payout batch 2026-06-26 / recipient 002",
"destCurrency": "USDT_TRC20",
"address": {
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
}'
Validation requests check the payout details without creating a transaction. To create the payout, send the same request body to POST /api/withdrawal/cryptowallet.
Recommended payout flow
Before creating payouts, your backend should validate and prepare each payout item.
Recommended flow:
- Get wallet balances.
- Check minimum limits for the selected payout method and currency.
- Check tariffs or fees.
- Check exchange rate information if the payout uses conversion.
- Validate the payout request.
- Create the payout transaction.
- Store the returned
transactionId. - Poll transaction status until the payout reaches a final state.
Step 1: Get wallet balances
Use this method to check available balances in your Volet.com wallets before creating payouts.
Endpoint:
GET /api/account/balances
See Get wallet balances in the API reference.
Example response:
[
{
"walletId": "USD123456789012",
"amount": 1000.50,
"currency": "USD"
},
{
"walletId": "USDT123456789012",
"amount": 2500,
"currency": "USDT"
}
]
Use walletId as the source wallet when creating payout requests.
Step 2: Check limits and tariffs
Before sending payouts, check the minimum limits and tariffs for the selected payout method and currency pair.
Minimum limits:
GET /api/account/limits/min
See Get minimum limits in the API reference.
Tariffs:
GET /api/account/tariffs
See Get withdrawal fees in the API reference.
Use these methods to prevent payout creation errors caused by unsupported amounts, currencies, or payment methods.
Step 3: Check exchange rate information
Use exchange rate information when the payout requires conversion.
Endpoint:
POST /api/exchange-rate/information
See Get exchange rate in the API reference.
Use this before creating payouts where the source currency and payout currency are different.
Example use cases:
- Send USDT to an external crypto wallet from a USD balance.
- Send BTC to an external crypto wallet from a EUR balance.
- Convert one supported crypto balance into another payout currency.
Payout method 1: Send payouts to Volet.com users
Use this method when the recipient has a Volet.com account.
Funds are transferred internally from your Volet.com account to the recipient's Volet.com account.
This method does not require blockchain confirmation and does not use external crypto wallet addresses.
Validate payout to a Volet.com user
Validate the payout before creating the transaction.
Endpoint:
POST /api/withdrawal/validation/internal-other
See Check transfer to Volet.com user in the API reference.
Example request:
{
"srcWalletId": "USD123456789012",
"amount": 25,
"action": "GIVE",
"note": "Payout batch 2026-06-26 / recipient 001",
"srcCurrency": "USD",
"destCurrency": "USD",
}
Validation checks the payout details without creating a transaction.
Create payout to a Volet.com user
After successful validation, create the payout transaction.
Endpoint:
POST /api/withdrawal/internal-other
See Transfer to Volet.com user in the API reference.
Example request:
{
"srcWalletId": "USD123456789012",
"amount": 25,
"action": "GIVE",
"note": "Payout batch 2026-06-26 / recipient 001",
"srcCurrency": "USD",
"destCurrency": "USD",
}
Example response:
{
"transactionId": "11111111-1111-4111-8111-111111111111",
"paymentMethodType": "INTERNAL_OTHER",
"transactionType": "WITHDRAWAL",
"status": "CREATED",
"direction": "WITHDRAWAL",
"currency": "USD",
"amount": 25,
"createdAt": "2026-01-15T10:30:00",
"walletSrcId": "USD123456789012",
"fullCommission": 0.13,
"comment": "Payout batch 2026-06-26 / recipient 001"
}
Store the returned transactionId in your system and use it to track payout status.
Optional: Validate Volet.com recipient accounts
If your payout flow collects recipient email addresses before payout creation, you can check whether Volet.com accounts exist before creating payout requests.
Endpoint:
GET /api/account/exists
See Check accounts exist in the API reference.
You can also match account holder details when your flow requires additional recipient checks.
Endpoint:
GET /api/account/matching
See Match account holder in the API reference.
Use these methods to reduce failed payouts caused by incorrect recipient details.
Payout method 2: Send crypto payouts without conversion
Use this method when you want to send cryptocurrency from the same crypto balance to an external crypto wallet.
For example:
- Send USDT from your USDT balance to an external USDT TRC-20 address.
- Send BTC from your BTC balance to an external BTC address.
- Send ETH from your ETH balance to an external ETH address.
The recipient does not need a Volet.com account.
Validate crypto payout without conversion
Validate the crypto payout before creating the transaction.
Endpoint:
POST /api/withdrawal/validation/cryptowallet
See Check crypto payout in the API reference.
Example request:
{
"srcWalletId": "USDT123456789012",
"amount": 100,
"action": "GIVE",
"note": "Payout batch 2026-06-26 / recipient 002",
"destCurrency": "USDT_TRC20",
"address": {
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"receiverInfo": {
}
}
Use the correct destCurrency for the payout token and blockchain network.
For networks that require a memo, destination tag, or similar identifier, include it in the address.memo field.
Example:
{
"address": {
"address": "rXXXXXXXXXXXXXXXXXXXXXXXX",
"memo": "123456"
}
}
Create crypto payout without conversion
After successful validation, create the payout transaction.
Endpoint:
POST /api/withdrawal/cryptowallet
See Send crypto payout in the API reference.
Example request:
{
"srcWalletId": "USDT123456789012",
"amount": 100,
"action": "GIVE",
"note": "Payout batch 2026-06-26 / recipient 002",
"destCurrency": "USDT_TRC20",
"address": {
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"receiverInfo": {
}
}
Example response:
{
"transactionId": "22222222-2222-4222-8222-222222222222",
"paymentMethodType": "CRYPTO_WALLET",
"transactionType": "WITHDRAWAL",
"status": "CREATED",
"direction": "WITHDRAWAL",
"currency": "USDT",
"amount": 100,
"createdAt": "2026-01-15T10:30:00",
"walletSrcId": "USDT123456789012",
"fullCommission": 0.25,
"comment": "Payout batch 2026-06-26 / recipient 002"
}
Payout method 3: Send crypto payouts with conversion
Use this method when the source balance and payout currency are different.
For example:
- Send USDT to an external wallet from a USD balance.
- Send BTC to an external wallet from a EUR balance.
- Send USDC on one supported network from another supported balance.
The recipient receives cryptocurrency to an external crypto wallet. Conversion is handled during the payout flow.
Validate crypto payout with conversion
Validate the payout before creating the transaction.
Endpoint:
POST /api/withdrawal/validation/crypto-external
See Check crypto payout with conversion in the API reference.
Example request:
{
"srcWalletId": "USD123456789012",
"amount": 100,
"action": "GIVE",
"note": "Payout batch 2026-06-26 / recipient 003",
"srcCurrency": "USD",
"destCurrency": "USDT_TRC20",
"address": {
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"receiverInfo": {
"firstName": "Alex",
"lastName": "Example",
}
}
Use srcCurrency to define the source balance currency and destCurrency to define the cryptocurrency and network sent to the recipient.
Create crypto payout with conversion
After successful validation, create the payout transaction.
Endpoint:
POST /api/withdrawal/crypto-external
See Send crypto payout with conversion in the API reference.
Example request:
{
"srcWalletId": "USD123456789012",
"amount": 100,
"action": "GIVE",
"note": "Payout batch 2026-06-26 / recipient 003",
"srcCurrency": "USD",
"destCurrency": "USDT_TRC20",
"address": {
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
},
"receiverInfo": {
"firstName": "Alex",
"lastName": "Example",
}
}
Example response:
{
"transactionId": "33333333-3333-4333-8333-333333333333",
"paymentMethodType": "CRYPTO_EXTERNAL",
"transactionType": "WITHDRAWAL",
"status": "CREATED",
"direction": "WITHDRAWAL",
"currency": "USD",
"amount": 100,
"createdAt": "2026-01-15T10:30:00",
"walletSrcId": "USD123456789012",
"fullCommission": 0.50,
"comment": "Payout batch 2026-06-26 / recipient 003"
}
Request fields
Common payout request fields:
| Field | Required | Used for | Description |
|---|---|---|---|
srcWalletId | No | All payout methods | Source wallet ID in your Volet.com account. |
amount | Yes | All payout methods | Payout amount. How the amount is interpreted depends on action. |
action | Yes | All payout methods | Amount mode. Possible values: GIVE, GET. |
note | No | All payout methods | Internal note or payout description. |
srcCurrency | No | Volet.com user payouts, crypto payouts with conversion | Source currency used for the payout. |
destCurrency | Yes | All payout methods | Currency credited to the recipient or sent to the external crypto wallet. |
destEmail | No | Volet.com user payouts | Recipient's Volet.com account email. |
destWalletId | No | Volet.com user payouts | Recipient wallet ID, where applicable. |
address.address | Yes | External crypto payouts | Recipient crypto wallet address. |
address.memo | No | External crypto payouts | Memo, destination tag, or similar identifier if required by the selected network. |
receiverInfo | No | External crypto payouts | Recipient information, such as name, email, date of birth, or company name, where required. |
GIVE and GET
Use action to define how the payout amount should be interpreted.
| Action | Meaning |
|---|---|
GIVE | The amount is treated as the amount to send from the source side. |
GET | The amount is treated as the amount the recipient should receive, where supported. |
For payouts with currency conversion, check exchange rate information before creating the payout. This helps your system show or store expected source and destination amounts before the transaction is created.
Tracking payout status
After creating a payout, store the returned transactionId.
Use transaction lookup to retrieve the latest payout status.
Endpoint:
GET /api/transactions/{id}
See Get transaction in the API reference.
You can also search transaction history.
Endpoint:
GET /api/transactions
See Get transaction history in the API reference.
Useful filters include:
| Filter | Description |
|---|---|
paymentDirections | Filter by DEPOSIT or WITHDRAWAL. |
transactionStatus | Filter by transaction status. |
wallets | Filter by wallet IDs. |
startDate / endDate | Filter by creation date range. |
searchLabel | Search by text label, where applicable. |
offset / limit | Paginate results. |
sortOrder | Sort results by creation date. |
Transaction statuses
Use transaction status to update payout status in your own system.
| Status | Meaning | Recommended action |
|---|---|---|
CREATED | Payout transaction has been created. | Store the transaction and continue tracking. |
READY_TO_PROCESS | Payout is ready for processing. | Continue tracking. |
PENDING | Payout is pending. | Continue tracking. |
PROCESSING | Payout is being processed. | Continue tracking. |
EXCHANGING | Currency conversion is in progress. | Continue tracking. |
COMPLETED | Payout has been completed. | Mark the payout as completed in your system. |
CANCELLING | Cancellation is in progress. | Wait for final status. |
CANCELED | Payout has been canceled. | Mark the payout as canceled. |
REFUNDING | Refund is in progress. | Wait for final status. |
REFUNDED | Payout has been refunded. | Mark the payout as refunded. |
Only treat the payout as completed after the status becomes COMPLETED.
Cancelling payouts
Some transactions can be canceled while cancellation is still allowed.
Endpoint:
DELETE /api/transactions/{transactionId}
See Cancel transaction in the API reference.
Cancellation availability depends on the payout method, transaction status, and processing stage.
Do not rely on cancellation for crypto payouts after the blockchain transaction has been broadcast. Confirm all recipient addresses, currencies, networks, and amounts before creating the payout.
Batch processing recommendations
For mass payouts, your backend should manage the batch lifecycle.
Recommended approach:
- Assign an internal payout batch ID.
- Assign an internal item ID to each payout.
- Validate every payout item before creating transactions.
- Create payout transactions only for validated items.
- Store the mapping between your internal item ID and the returned
transactionId. - Track each transaction separately.
- Retry only failed or uncreated items.
- Reconcile final statuses before marking the batch as complete.
Avoid sending duplicate payouts. The Merchant API has no idempotency key: every payout request that passes validation creates a new transaction, even if it repeats an earlier one. If a request times out or returns a 5xx error, the payout may have been created:
- Do not repeat the request automatically.
- Check your transaction history and wallet balance for the payout item.
- If it is still unclear whether the payout was created, contact support before you send it again.
To keep a timeout from turning into a second payout, send each payout item from one worker at a time, and store the full response with the returned transactionId.
Error handling
Merchant API errors return structured error responses.
Common error cases include:
| HTTP status | Meaning |
|---|---|
400 | The request is malformed, contains invalid parameters, or cannot be processed. |
401 | Authentication headers are missing or invalid, or the account has used up its hourly request limit (attemptsHaveEndedException). |
404 | The requested endpoint was not found. |
409 | The data is temporarily locked (tryAgainAfterAWhile). |
500 | Unexpected server error. |
503 | A service is temporarily unavailable (serviceTemporaryUnavailable). |
When an error occurs:
- Log
errorIdfor support and diagnostics. - Check
errorFieldto identify the request field related to the error. - Fix authentication and parameter errors instead of repeating the same request.
- Retry read and validation requests after
409,503, or a timeout, with a growing delay between attempts. - Do not automatically create a replacement payout until you confirm that no transaction was created.
For common error codes and what they mean, see Errors in the API reference.
Testing checklist
Before sending live mass payouts, test the full flow.
For payouts to Volet.com users:
- Recipient account validation.
- Payout validation.
- Payout creation.
- Transaction status tracking.
- Completed, canceled, and failed scenarios.
For crypto payouts without conversion:
- Correct token and network selection.
- Address and memo handling.
- Payout validation.
- Payout creation.
- Blockchain transaction tracking.
- Incorrect address or unsupported network handling.
For crypto payouts with conversion:
- Balance check.
- Exchange rate check.
- Payout validation.
- Payout creation.
EXCHANGINGandCOMPLETEDstatuses.- Amount reconciliation between source and destination currencies.
For batch processing:
- Partial batch failure handling.
- Retry logic.
- Duplicate prevention.
- Internal batch-to-transaction mapping.
- Final reconciliation report.
Important notes
- The API creates one payout transaction per request.
- Your backend is responsible for batch orchestration.
- Always validate payouts before creating transactions.
- Always store returned
transactionIdvalues. - Use transaction lookup or transaction history to track final status.
- Do not mark a payout as completed until the status becomes
COMPLETED. - For crypto payouts, always verify the recipient address, token, network, and memo before creating the transaction.
- Sending crypto to the wrong address or network may result in permanent loss of funds.
- API credentials must never be exposed in frontend code.
Related
- Enable mass payouts — set up your API before sending payouts
- Send payouts to Volet.com users — send internal payouts to Volet.com accounts
- Send custodial crypto payouts — send crypto to external wallets from your Volet.com account
- Mass payouts overview — compare payout methods and models
- API reference — complete methods, parameters, and response documentation