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.

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, cancelled, 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")`. Only the generated token is sent, never the password.

Keep your API secret private. Never expose API credentials or authentication tokens in frontend code, mobile apps, bots, or client-side scripts.

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

Example response:

[
  {
    "walletId": "W000000000001",
    "amount": 1000.50,
    "currency": "USD"
  },
  {
    "walletId": "W000000000002",
    "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

Tariffs:

GET /api/account/tariffs

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

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

Example request:

{
  "srcWalletId": "W000000000001",
  "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

Example request:

{
  "srcWalletId": "W000000000001",
  "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": "W000000000001",
  "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

You can also match account holder details when your flow requires additional recipient checks.

Endpoint:

GET /api/account/matching

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

Example request:

{
  "srcWalletId": "W000000000002",
  "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

Example request:

{
  "srcWalletId": "W000000000002",
  "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": "W000000000002",
  "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

Example request:

{
  "srcWalletId": "W000000000001",
  "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

Example request:

{
  "srcWalletId": "W000000000001",
  "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": "W000000000001",
  "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}

You can also search transaction history.

Endpoint:

GET /api/transactions

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 cancelled.	Mark the payout as cancelled.
`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 cancelled while cancellation is still allowed.

Endpoint:

DELETE /api/transactions/{transactionId}

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. If your application retries a request after a timeout, first check whether a transaction was already created for that payout item.

Error handling

Merchant API errors return structured error responses.

Common error cases include:

HTTP status	Meaning
`400`	The request is malformed or contains invalid parameters.
`401`	Authentication headers are missing or invalid.
`403`	The API does not have permission to use the requested operation.
`404`	The requested resource was not found.
`500`	Unexpected server error.

When an error occurs:

Log errorId for support and diagnostics.
Check errorField to identify the request field related to the error.
Do not automatically create a replacement payout until you confirm that no transaction was created.
Retry only when it is safe to do so.

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, cancelled, 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.

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

How mass payouts work through the API​

Before you start​

Authentication​

Recommended payout flow​

Step 1: Get wallet balances​

Step 2: Check limits and tariffs​

Step 3: Check exchange rate information​

Payout method 1: Send payouts to Volet.com users​

Validate payout to a Volet.com user​

Create payout to a Volet.com user​

Optional: Validate Volet.com recipient accounts​

Payout method 2: Send crypto payouts without conversion​

Validate crypto payout without conversion​

Create crypto payout without conversion​

Payout method 3: Send crypto payouts with conversion​

Validate crypto payout with conversion​

Create crypto payout with conversion​

Request fields​

GIVE and GET​

Tracking payout status​

Transaction statuses​

Cancelling payouts​

Batch processing recommendations​

Error handling​

Testing checklist​

Important notes​

Related​

How mass payouts work through the API

Before you start

Authentication

Recommended payout flow

Step 1: Get wallet balances

Step 2: Check limits and tariffs

Step 3: Check exchange rate information

Payout method 1: Send payouts to Volet.com users

Validate payout to a Volet.com user

Create payout to a Volet.com user

Optional: Validate Volet.com recipient accounts

Payout method 2: Send crypto payouts without conversion

Validate crypto payout without conversion

Create crypto payout without conversion

Payout method 3: Send crypto payouts with conversion

Validate crypto payout with conversion

Create crypto payout with conversion

Request fields

`GIVE` and `GET`

Tracking payout status

Transaction statuses

Cancelling payouts

Batch processing recommendations

Error handling

Testing checklist

Important notes

Related