API integration
Accept cryptocurrency payments from external crypto wallets through the Merchant API.
With API integration, your application creates crypto invoices, shows payment instructions to customers, and tracks payment status through the API or Status URL notifications.
You can use the API in three ways:
-
API only with status polling — your application builds the full payment experience and checks payment status through the API.
-
API only with Status URL notifications — your application builds the full payment experience, while a Hosted Checkout configuration provides the Status URL used for payment notifications. The Hosted Checkout page itself is not used.
-
API + Hosted Checkout — your backend uses the API for order tracking and reconciliation, while Hosted Checkout provides the customer-facing payment page.
When to use API integration
Use API integration when you want to control the payment flow in your own website, application, bot, or AI agent.
API integration is useful when:
- You want to build your own checkout UI.
- You need to create crypto invoices programmatically.
- You want to show payment instructions inside your own product.
- You need to track payment status from your backend.
- You want to receive payment status notifications on your server.
- You want to combine Hosted Checkout with backend order reconciliation.
If you want the fastest integration with a ready-made payment page, use Hosted Checkout integration instead.
Integration models
| Model | Customer experience | Backend responsibility | Status handling |
|---|---|---|---|
| API only + polling | Built by your application | Create invoice, display payment details, track status | Poll GET /api/orders |
| API only + Status URL | Built by your application | Create invoice, display payment details, process notifications | Hosted Checkout Status URL, with API lookup for reconciliation |
| API + Hosted Checkout | Hosted by Volet.com | Track orders and reconcile payment status | Hosted Checkout Status URL, with API lookup for reconciliation |
Before you start
To accept crypto payments through the API, you need:
- A verified Volet.com account.
- A configured API in the Payment Tools section.
- The following API permissions:
- Make transactions → Accept crypto payments — to create crypto invoices.
- Find transaction — to retrieve payment orders.
- A Hosted Checkout configuration whose name you can pass as
sciName.
See Create payment gateway to create and configure your API and Hosted Checkout.
sciName requirementThe current GET /api/orders implementation requires a Hosted Checkout name (sciName) to retrieve an order.
Until this requirement is removed, create a Hosted Checkout configuration and pass its name as sciName when creating crypto invoices that you need to track.
You do not need to redirect customers to the Hosted Checkout page. The configuration can be used only to provide the required sciName and, optionally, Status URL notifications.
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:
curl -X POST https://api.volet.com/api/invoice/crypto-invoice/deposit \
-H "Content-Type: application/json" \
-H "Api-Name: my-store-api" \
-H "Authentication-Token: c98e6521afe72b0945d9fdefdf3fd0b4dea10baa7f69325a7d6381c15f2421fd" \
-d '{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"sciName": "Store",
"orderId": "ORDER-1001"
}'
API-only payment flow
Use this flow when your application handles the full crypto payment experience.
- Create an order in your system.
- Optionally check calculated invoice details.
- Create a crypto invoice through the API.
- Show the payment address, amount, currency, network, and expiration time to the customer.
- The customer sends the payment from a crypto wallet.
- Track the payment through
GET /api/orders, Status URL notifications, or both. - When the payment is completed, update the order status in your system.
Step 1 (optional): Check invoice details
Before creating an invoice, you can check calculated invoice values.
Use this step to preview the sender amount, receiver amount, currency conversion, and expiration time before creating the actual invoice.
Endpoint:
POST /api/invoice/crypto-invoice/check
See Check crypto invoice in the API reference.
Example request:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com"
}
Example response:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com",
"senderAmount": 100,
"receiverAmount": 100,
"expirationDate": "2026-01-15T10:30:00",
"expirationDateMillis": 1768473000000
}
This step does not create a payment address and does not start the payment.
Step 2: Create a crypto invoice
Create a crypto invoice when the customer is ready to pay.
Endpoint:
POST /api/invoice/crypto-invoice/deposit
See Create crypto invoice in the API reference.
Example request:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com"
}
The response returns the payment details that your application should show to the customer.
Example response:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001",
"subMerchantURL": "https://merchant.example.com",
"address": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"addressOldFormat": null,
"destinationTag": null,
"senderAmount": 100,
"receiverAmount": 100,
"expirationDate": "2026-01-15T10:30:00",
"expirationDateMillis": 1768473000000
}
The amounts in these examples are illustrative. The actual senderAmount and receiverAmount depend on the selected currencies, exchange rate, and applicable fees.
Invoice request fields
| Field | Required | Description |
|---|---|---|
receiverCurrency | Yes | Currency credited to your Volet.com account after the payment is completed. See Create crypto invoice for supported values. |
senderCurrency | Yes | Currency and network the customer should use to pay, for example USDT_TRC20. |
amount | Yes | Payment amount. How this amount is interpreted depends on transferAction. |
transferAction | Yes | Defines which side amount refers to. Possible values: GIVE, GET. See GIVE and GET. |
note | No | Payment note or order description. Up to 255 characters. |
sciName | No* | Hosted Checkout name set in your Volet.com account. Currently required if you want to retrieve the order through GET /api/orders or receive Status URL notifications through the Hosted Checkout configuration. |
orderId | No* | Your internal order ID, up to 64 characters. Required to retrieve the payment later with GET /api/orders. Use a unique value for each payment. If you pass sciName, Volet.com rejects a second invoice with the same orderId for that Hosted Checkout. |
subMerchantURL | No | Website URL of the sub-merchant, if the payment is processed on behalf of another merchant. See Sub-merchants. |
* The invoice creation endpoint may accept the field as optional, but it is required for the tracking flows described in this guide.
GIVE and GET
transferAction determines which currency the request amount is expressed in.
Choose the model that matches your pricing and accounting:
- Use
GETwhen the order is priced in the currency you want to receive, for example a price in USD. The customer pays the equivalent in the selected cryptocurrency. - Use
GIVEwhen the customer should send a fixed amount of a specific cryptocurrency.
The choice affects how you display the price, explain the amount due, and reconcile payments. Use POST /api/invoice/crypto-invoice/check to validate the calculated amounts before you create live invoices.
| Value | amount means |
|---|---|
GIVE | The amount the customer sends, expressed in senderCurrency. |
GET | The amount to be credited to your Volet.com account, expressed in receiverCurrency. |
The final senderAmount and receiverAmount returned by the API may differ because of exchange rates and applicable fees.
Currency codes
Some cryptocurrency codes include the blockchain network after an underscore.
For example:
USDT_TRC20— USDT on Tron.USDT_ERC20— USDT on Ethereum.USDC_SOL— USDC on Solana.
Other assets use a single currency code, such as BTC, ETH, or TON.
senderCurrency takes the code with the network, while receiverCurrency is a wallet currency without one (USD, EUR, USDT, USDC). For all codes and the fields that use them, see Currency codes and amounts in the API reference.
Invoice response fields
| Field | Description |
|---|---|
address | Crypto address where the customer should send the payment. |
addressOldFormat | Alternative address format, if available for the selected network. |
destinationTag | Destination tag, memo, or additional identifier required by some networks. |
senderAmount | Amount the customer should send. |
senderCurrency | Currency and network the customer should use. |
receiverAmount | Amount expected to be credited to your account. |
receiverCurrency | Currency expected to be credited to your account. |
expirationDate | Invoice expiration date and time. |
expirationDateMillis | Invoice expiration time as a Unix timestamp in milliseconds. |
Always show the exact senderAmount, senderCurrency, address, and destinationTag if it is returned.
Use expirationDateMillis to calculate and display the invoice expiration time.
Step 3: Show payment instructions
In API-only mode, your application is responsible for showing payment instructions to the customer.
Show at least:
- Amount to send.
- Currency and blockchain network.
- Crypto address.
- Destination tag or memo, if required.
- Expiration time.
- A warning to send funds only on the selected network.
Example:
Send exactly 100 USDT on Tron (TRC-20) to:
TXXXXXXXXXXXXXXXXXXXXXXXXXXXX
This invoice expires at 2026-01-15 10:30 UTC.
Do not send funds on another network.
For networks that require a destination tag or memo, show it clearly next to the address.
Step 4: Check payment status
After creating the invoice, your backend can retrieve the payment order through the API.
Endpoint:
GET /api/orders
See Get payment order in the API reference.
Current query parameters:
| Parameter | Required | Description |
|---|---|---|
orderId | Yes | Merchant order identifier, up to 64 characters. |
sciName | Yes* | Hosted Checkout name associated with the invoice. |
* sciName is currently required by the API implementation when retrieving an order.
Example request:
GET /api/orders?orderId=ORDER-1001&sciName=Store
sciName workaroundAt the moment, an API-created order cannot be reliably retrieved by orderId alone.
Create a Hosted Checkout configuration, use its name as sciName when creating the crypto invoice, and pass the same value to GET /api/orders.
You can use this workaround without displaying the Hosted Checkout page to the customer.
Example response:
{
"orderId": "ORDER-1001",
"sciName": "Store",
"paymentStatus": "COMPLETED",
"paymentMethod": "CRYPTO_INVOICE",
"paymentCreated": "2026-01-15T10:00:00",
"transaction": {
"id": "11111111-1111-4111-8111-111111111111",
"status": "COMPLETED",
"senderAmount": 100,
"senderCurrency": "USDT_TRC20",
"receiverAmount": 100,
"receiverCurrency": "USD",
"created": "2026-01-15T10:00:00"
},
"invoice": {
"created": "2026-01-15T10:00:00",
"received": "2026-01-15T10:12:00",
"invoiceStatus": "COMPLETED",
"externalStatus": "PAYMENT_RECEIVED",
"penalties": [],
"cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"initialSenderAmount": 100,
"actualReceivedAmount": 100,
"senderCurrency": "USDT_TRC20",
"cryptoCurrencyTransactionId": "3d2ab8f84818a8b4e0ed8270a0142e13ca02f5ab760a85304586f64eafb7bac0"
}
}
If no matching order is found, the API returns an error. Check the orderId and sciName before creating another invoice for the same order.
Payment status
Use the top-level paymentStatus to determine whether the payment has completed.
| Status | Meaning | Recommended action |
|---|---|---|
CREATED | The invoice is created. Volet.com has not finished processing a payment for it. | Keep the order pending. |
PROCESSING | Volet.com is processing the payment. | Keep the order pending. |
COMPLETED | The payment is completed, and the funds are credited to your account. Final status. | Mark the order as paid and deliver the product or service. |
FAILED | The payment failed or its transaction was canceled. Final status. | Do not fulfill the order. |
Only treat an order as paid when paymentStatus is COMPLETED.
paymentStatus has no value for refunds. A refund shows in transaction.status (REFUNDING, then REFUNDED) and in invoice.invoiceStatus.
When the invoice expires, paymentStatus does not change to FAILED by itself. A customer can still send a payment after the expiration time; see Invoice status and penalties.
For all statuses, including transaction and invoice statuses, see Statuses in the API reference.
Invoice status and penalties
The invoice object describes the crypto payment in more detail than paymentStatus. Use it to explain a problem payment to your support team or the customer, not to decide whether the order is paid.
invoiceStatus values:
| Status | Meaning |
|---|---|
NEW | The invoice is created, and no payment has been received yet. |
RECEIVED | A blockchain transaction for the invoice is received. Checks can still be running, so the funds are not credited yet. |
EXCHANGING | Volet.com is converting the received crypto to the receiver currency. |
COMPLETED | The invoice is processed, and the funds are credited to your account. |
REFUND_CONFIRMATION | A refund of the payment is waiting for confirmation. |
REFUND_REQUESTED | A refund is requested. |
REFUNDED | The payment is returned to the customer. |
CLOSED | The invoice is closed. |
penalties lists how the received payment differs from the invoice. It is empty when the payment matches:
UNDERPAYMENT— the customer sent less thansenderAmount.OVERPAYMENT— the customer sent more thansenderAmount. A small overpayment within the allowed tolerance is not flagged.EXPIRED— the payment arrived after the invoice expired.
A payment with EXPIRED is not credited automatically: Volet.com either returns it to the customer or credits it to your account. How underpayments and overpayments are handled depends on your gateway settings. See Payment handling.
externalStatus combines invoiceStatus and penalties into one value, for example UNDERPAYMENT_RECEIVED or EXPIRED_PAYMENT_REFUNDED. PAYMENT_RECEIVED does not mean that the funds are credited. Use externalStatus for display only.
cryptoCurrencyTransactionId is the hash of the blockchain transaction that paid the invoice. Use it to find the payment in a blockchain explorer. It is empty until a payment is received.
Receive Status URL notifications
Polling GET /api/orders is not the only way to track API-created crypto invoices.
The API configuration in your Volet.com account does not currently provide fields for webhook URLs. However, you can use the Status URL configured for a Hosted Checkout gateway to receive payment status notifications for invoices created through the API.
You do not need to display or redirect customers to Hosted Checkout for this flow.
Set up Status URL notifications
- Create a Hosted Checkout configuration in your Volet.com account.
- Configure its Status URL and select the required HTTP method.
- Use the Hosted Checkout name as
sciNamewhen creating crypto invoices through the API. - Keep the customer-facing payment flow in your own application.
- When a transaction is created for the payment and when it is completed, Volet.com sends a notification to the Status URL configured for that Hosted Checkout.
- Verify the notification signature before updating the order in your system.
- Check orders that stay pending through
GET /api/orders.
Example invoice request:
{
"receiverCurrency": "USD",
"senderCurrency": "USDT_TRC20",
"amount": 100,
"transferAction": "GET",
"note": "Order #1001",
"sciName": "Store",
"orderId": "ORDER-1001"
}
In this example, Store is the name of the Hosted Checkout configuration that contains the Status URL.
The customer still sees your own payment interface. The Hosted Checkout payment page is not opened.
The same sciName can therefore serve two purposes in an API-only integration:
- It allows the current
GET /api/ordersimplementation to find the order. - It links the API-created invoice to the Hosted Checkout configuration used for Status URL notifications.
For notification parameters and signature verification, see Hosted Checkout integration.
Polling and Status URL notifications
You can use either:
- API polling.
- Status URL notifications.
- Both together.
Do not rely on Status URL notifications alone. Volet.com does not guarantee that a notification is delivered again if your endpoint is unavailable or returns an error. Check orders that stay pending through GET /api/orders, so a missed notification does not leave a paid order unfulfilled.
The same notification can arrive more than once. Process notifications by your orderId and the transaction ID in ac_transfer, so a repeated notification does not fulfill the order twice.
Do not create a duplicate invoice simply because a status request or notification delivery fails.
API + Hosted Checkout flow
Use this model when you want Hosted Checkout itself to provide the customer-facing payment page, while your backend uses the API for tracking and reconciliation.
The payment flow:
- Create an order in your system.
- Redirect the customer to Hosted Checkout using your Hosted Checkout integration.
- Pass your
orderIdin the Hosted Checkout payment request. - The customer completes the payment on the Hosted Checkout page.
- Volet.com sends a payment status notification to your Status URL.
- Your backend verifies the notification signature.
- Your backend updates the order status.
- Optionally, your backend checks the order through the API for reconciliation.
In this model, Hosted Checkout handles:
- The payment page.
- Payment method selection.
- Payment instructions.
- Customer redirects.
The API can still be used to retrieve the payment order by orderId and sciName and reconcile the status in your system.
Status handling with Hosted Checkout
When using the Hosted Checkout page, do not rely only on Success URL or Failed URL redirects.
Customer redirects are part of the browser flow and may not always reach your server.
Use the Status URL notification to update the order on your backend and the API order lookup for reconciliation when needed.
Recommended approach:
- Receive the Hosted Checkout Status URL notification.
- Verify the notification signature.
- Update the order if the notification is valid.
- Use
GET /api/ordersas a fallback or reconciliation check.
See Hosted Checkout integration for the notification payload and signature verification rules.
Order and payment model
Keep each order in your system separate from its payment attempts. This makes it easier to handle abandoned checkouts, expired invoices, repeated payment attempts, and status updates that arrive after the customer has left the page.
- Create a new invoice with a unique
orderIdfor each payment attempt, and store in your database which order each attempt belongs to. - Fulfill each order only once. Process status updates by your own
orderId, so a repeated notification or a second status check cannot fulfill the order twice. - Store with each payment attempt the Volet.com transaction ID, the amount received, the settlement currency, and the final payment status.
If the customer leaves the payment page
Closing the payment page neither cancels nor confirms the payment. The order stays pending in your system, and the payment continues independently:
- Your backend checks the payment status through the API or receives a Status URL notification.
- When
paymentStatusisCOMPLETED, your backend marks the order as paid and fulfills it. - If the customer returns to your website, they see the updated order status.
Your backend, not the browser redirect, determines when the order can be fulfilled.
Reconcile payments with orders
Match each Volet.com transaction to your payment attempt and order. Compare the transaction ID, the expected and received amounts, the currency, and the final payment status.
If a payment is missing, late, or does not match the expected amount, flag it for investigation instead of marking the order as paid automatically.
A customer says the payment is confirmed, but the order is not paid
Find the payment with GET /api/orders by orderId and check paymentStatus.
A transaction can be confirmed on the blockchain and still not match the invoice, for example:
- The amount is lower or higher than requested. How such payments are handled depends on your gateway settings.
- The payment was sent after the invoice expired.
- The payment was sent on another network or in another token.
- The payment did not pass transaction screening, for example because the funds come from a high-risk source.
See Payment handling for how these payments are processed.
Error handling
Merchant API errors use a structured response with one or more errors in data.errors.
Example structure:
{
"status": "error",
"data": {
"errors": [
{
"errorMessage": "resourceNotFound",
"errorType": "GENERAL",
"errorId": "3f69d9b6",
"errorDescription": "Resource not found",
"errorField": null,
"params": [],
"requestParams": {}
}
]
}
}
Error fields:
| Field | Description |
|---|---|
errorMessage | Machine-readable error code returned by the API. |
errorType | Error category: FIELD (one field is invalid, see errorField), FORM (the request as a whole), or GENERAL. |
errorId | Error identifier that can be included in logs and support requests. |
errorDescription | Human-readable error description. |
errorField | Request field related to the error, if available. |
params | Additional parameters associated with the error, if available. |
requestParams | Request parameters associated with the error, if available. |
Common HTTP responses include:
| HTTP status | Meaning |
|---|---|
400 | The request is malformed, contains invalid parameters, or cannot be processed. Also returned when an order or other entity is not found. |
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). Retry later. |
500 | Unexpected server error. |
503 | A service is temporarily unavailable (serviceTemporaryUnavailable). Retry later. |
Exact errorMessage values depend on the endpoint and error. Do not derive an application error code from the HTTP status alone.
When an error occurs:
- Log
errorIdfor support and diagnostics. - Check
errorFieldwhen available. - Use
errorMessagerather thanerrorDescriptionin programmatic error handling. - Fix authentication and parameter errors instead of repeating the same request.
- Retry read requests, such as
GET /api/orders, after409,503, or a timeout, with a growing delay between attempts. - Do not repeat an invoice creation request after a timeout or a
5xxerror: the invoice may have been created. First check the order throughGET /api/ordersby itsorderId.
For common error codes and what they mean, see Errors in the API reference.
Testing and sandbox
Volet.com does not currently offer a sandbox or staging environment for integration testing.
If you use Hosted Checkout, you can preview the customer-facing payment page on the Hosted Checkout page for developers. The preview is not a sandbox and cannot be used as a replacement for integration testing.
For a walkthrough of the API, Hosted Checkout, and payment flow before going live, contact the Volet.com sales team.
Testing checklist
Before accepting live crypto payments, verify the complete flow used by your integration.
For API-only integrations:
- Invoice check, if used.
- Invoice creation.
- Correct payment address display.
- Destination tag or memo display where required.
- Correct currency and network display.
- Invoice expiration handling.
orderIdandsciNamestorage.- Order lookup through
GET /api/orders. - Completed payment handling.
- Failed payment handling.
- Late, underpaid, and overpaid payments (
penalties). - Duplicate
orderIdhandling. - API error handling.
If you use Status URL notifications:
- Hosted Checkout configuration contains the correct Status URL.
- The same Hosted Checkout name is passed as
sciName. - Notification delivery reaches your backend.
- Notification signatures are verified.
- Duplicate notifications are handled safely.
- Orders without a completed notification are checked through
GET /api/orders.
If you use the Hosted Checkout payment page, also verify:
- Customer redirection to Hosted Checkout.
- Success URL redirect.
- Failed URL redirect.
- Status URL notification delivery.
- Notification signature validation.
- API order lookup for reconciliation.
Important notes
- API-only integrations do not require customers to visit Hosted Checkout.
- The current order lookup flow requires
sciName. - A Hosted Checkout configuration can be used only for
sciNameand Status URL notifications without displaying the Hosted Checkout page. - Always use a unique
orderIdfor each payment. - Always show the exact address, amount, currency, network, and destination tag returned by the API.
- Do not mark an order as paid until
paymentStatusisCOMPLETED. - Use
expirationDateMilliswhen calculating invoice expiration. - Crypto payments depend on blockchain confirmations and network conditions.
- Sending funds to the wrong address or network may result in permanent loss of funds.
- Do not automatically create another invoice after an ambiguous timeout or temporary API error.
Related
- Create payment gateway — create and configure the API and Hosted Checkout
- Accept custodial crypto payments — how custodial crypto payments work
- Hosted Checkout integration — use the hosted payment page and Status URL notifications
- Currency codes and amounts — currency and network codes in API requests
- API reference — complete methods, parameters, and response documentation
- Crypto payment API integration: what your team actually has to build — a blog article on what to plan and build before launch