Skip to main content

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.
AI agents instead of the API

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:

  1. Prepare a payout batch in your system.
  2. Check your available Volet.com wallet balances.
  3. Check limits, tariffs, and exchange rates where needed.
  4. Validate each payout before creation.
  5. Create payout transactions through the API.
  6. Store returned transaction IDs in your system.
  7. Track payout statuses through the API.
  8. 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:

HeaderDescription
Api-NameAPI name configured in your Volet.com account.
Account-EmailEmail address of the Volet.com account that owns the API.
Authentication-TokenSHA-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 "Account-Email: [email protected]" \
-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.

Before creating payouts, your backend should validate and prepare each payout item.

Recommended flow:

  1. Get wallet balances.
  2. Check minimum limits for the selected payout method and currency.
  3. Check tariffs or fees.
  4. Check exchange rate information if the payout uses conversion.
  5. Validate the payout request.
  6. Create the payout transaction.
  7. Store the returned transactionId.
  8. 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",
"destEmail": "[email protected]"
}

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",
"destEmail": "[email protected]"
}

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": {
"email": "[email protected]"
}
}

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": {
"email": "[email protected]"
}
}

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",
"email": "[email protected]"
}
}

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",
"email": "[email protected]"
}
}

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:

FieldRequiredUsed forDescription
srcWalletIdNoAll payout methodsSource wallet ID in your Volet.com account.
amountYesAll payout methodsPayout amount. How the amount is interpreted depends on action.
actionYesAll payout methodsAmount mode. Possible values: GIVE, GET.
noteNoAll payout methodsInternal note or payout description.
srcCurrencyNoVolet.com user payouts, crypto payouts with conversionSource currency used for the payout.
destCurrencyYesAll payout methodsCurrency credited to the recipient or sent to the external crypto wallet.
destEmailNoVolet.com user payoutsRecipient's Volet.com account email.
destWalletIdNoVolet.com user payoutsRecipient wallet ID, where applicable.
address.addressYesExternal crypto payoutsRecipient crypto wallet address.
address.memoNoExternal crypto payoutsMemo, destination tag, or similar identifier if required by the selected network.
receiverInfoNoExternal crypto payoutsRecipient 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.

ActionMeaning
GIVEThe amount is treated as the amount to send from the source side.
GETThe 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:

FilterDescription
paymentDirectionsFilter by DEPOSIT or WITHDRAWAL.
transactionStatusFilter by transaction status.
walletsFilter by wallet IDs.
startDate / endDateFilter by creation date range.
searchLabelSearch by text label, where applicable.
offset / limitPaginate results.
sortOrderSort results by creation date.

Transaction statuses​

Use transaction status to update payout status in your own system.

StatusMeaningRecommended action
CREATEDPayout transaction has been created.Store the transaction and continue tracking.
READY_TO_PROCESSPayout is ready for processing.Continue tracking.
PENDINGPayout is pending.Continue tracking.
PROCESSINGPayout is being processed.Continue tracking.
EXCHANGINGCurrency conversion is in progress.Continue tracking.
COMPLETEDPayout has been completed.Mark the payout as completed in your system.
CANCELLINGCancellation is in progress.Wait for final status.
CANCELEDPayout has been canceled.Mark the payout as canceled.
REFUNDINGRefund is in progress.Wait for final status.
REFUNDEDPayout 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:

  1. Assign an internal payout batch ID.
  2. Assign an internal item ID to each payout.
  3. Validate every payout item before creating transactions.
  4. Create payout transactions only for validated items.
  5. Store the mapping between your internal item ID and the returned transactionId.
  6. Track each transaction separately.
  7. Retry only failed or uncreated items.
  8. 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 statusMeaning
400The request is malformed, contains invalid parameters, or cannot be processed.
401Authentication headers are missing or invalid, or the account has used up its hourly request limit (attemptsHaveEndedException).
404The requested endpoint was not found.
409The data is temporarily locked (tryAgainAfterAWhile).
500Unexpected server error.
503A service is temporarily unavailable (serviceTemporaryUnavailable).

When an error occurs:

  • Log errorId for support and diagnostics.
  • Check errorField to 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.
  • EXCHANGING and COMPLETED statuses.
  • 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 transactionId values.
  • 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.