Skip to main content

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​

ModelCustomer experienceBackend responsibilityStatus handling
API only + pollingBuilt by your applicationCreate invoice, display payment details, track statusPoll GET /api/orders
API only + Status URLBuilt by your applicationCreate invoice, display payment details, process notificationsHosted Checkout Status URL, with API lookup for reconciliation
API + Hosted CheckoutHosted by Volet.comTrack orders and reconcile payment statusHosted 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.

Current sciName requirement

The 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:

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:

curl -X POST https://api.volet.com/api/invoice/crypto-invoice/deposit \
-H "Content-Type: application/json" \
-H "Api-Name: my-store-api" \
-H "Account-Email: [email protected]" \
-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.

  1. Create an order in your system.
  2. Optionally check calculated invoice details.
  3. Create a crypto invoice through the API.
  4. Show the payment address, amount, currency, network, and expiration time to the customer.
  5. The customer sends the payment from a crypto wallet.
  6. Track the payment through GET /api/orders, Status URL notifications, or both.
  7. 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​

FieldRequiredDescription
receiverCurrencyYesCurrency credited to your Volet.com account after the payment is completed. See Create crypto invoice for supported values.
senderCurrencyYesCurrency and network the customer should use to pay, for example USDT_TRC20.
amountYesPayment amount. How this amount is interpreted depends on transferAction.
transferActionYesDefines which side amount refers to. Possible values: GIVE, GET. See GIVE and GET.
noteNoPayment note or order description. Up to 255 characters.
sciNameNo*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.
orderIdNo*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.
subMerchantURLNoWebsite 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 GET when 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 GIVE when 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.

Valueamount means
GIVEThe amount the customer sends, expressed in senderCurrency.
GETThe 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​

FieldDescription
addressCrypto address where the customer should send the payment.
addressOldFormatAlternative address format, if available for the selected network.
destinationTagDestination tag, memo, or additional identifier required by some networks.
senderAmountAmount the customer should send.
senderCurrencyCurrency and network the customer should use.
receiverAmountAmount expected to be credited to your account.
receiverCurrencyCurrency expected to be credited to your account.
expirationDateInvoice expiration date and time.
expirationDateMillisInvoice 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:

ParameterRequiredDescription
orderIdYesMerchant order identifier, up to 64 characters.
sciNameYes*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
Temporary sciName workaround

At 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.

StatusMeaningRecommended action
CREATEDThe invoice is created. Volet.com has not finished processing a payment for it.Keep the order pending.
PROCESSINGVolet.com is processing the payment.Keep the order pending.
COMPLETEDThe payment is completed, and the funds are credited to your account. Final status.Mark the order as paid and deliver the product or service.
FAILEDThe 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:

StatusMeaning
NEWThe invoice is created, and no payment has been received yet.
RECEIVEDA blockchain transaction for the invoice is received. Checks can still be running, so the funds are not credited yet.
EXCHANGINGVolet.com is converting the received crypto to the receiver currency.
COMPLETEDThe invoice is processed, and the funds are credited to your account.
REFUND_CONFIRMATIONA refund of the payment is waiting for confirmation.
REFUND_REQUESTEDA refund is requested.
REFUNDEDThe payment is returned to the customer.
CLOSEDThe 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 than senderAmount.
  • OVERPAYMENT — the customer sent more than senderAmount. 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​

  1. Create a Hosted Checkout configuration in your Volet.com account.
  2. Configure its Status URL and select the required HTTP method.
  3. Use the Hosted Checkout name as sciName when creating crypto invoices through the API.
  4. Keep the customer-facing payment flow in your own application.
  5. 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.
  6. Verify the notification signature before updating the order in your system.
  7. 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.

note

The same sciName can therefore serve two purposes in an API-only integration:

  • It allows the current GET /api/orders implementation 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:

  1. Create an order in your system.
  2. Redirect the customer to Hosted Checkout using your Hosted Checkout integration.
  3. Pass your orderId in the Hosted Checkout payment request.
  4. The customer completes the payment on the Hosted Checkout page.
  5. Volet.com sends a payment status notification to your Status URL.
  6. Your backend verifies the notification signature.
  7. Your backend updates the order status.
  8. 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:

  1. Receive the Hosted Checkout Status URL notification.
  2. Verify the notification signature.
  3. Update the order if the notification is valid.
  4. Use GET /api/orders as 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 orderId for 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:

  1. Your backend checks the payment status through the API or receives a Status URL notification.
  2. When paymentStatus is COMPLETED, your backend marks the order as paid and fulfills it.
  3. 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:

FieldDescription
errorMessageMachine-readable error code returned by the API.
errorTypeError category: FIELD (one field is invalid, see errorField), FORM (the request as a whole), or GENERAL.
errorIdError identifier that can be included in logs and support requests.
errorDescriptionHuman-readable error description.
errorFieldRequest field related to the error, if available.
paramsAdditional parameters associated with the error, if available.
requestParamsRequest parameters associated with the error, if available.

Common HTTP responses include:

HTTP statusMeaning
400The request is malformed, contains invalid parameters, or cannot be processed. Also returned when an order or other entity is not found.
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). Retry later.
500Unexpected server error.
503A 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 errorId for support and diagnostics.
  • Check errorField when available.
  • Use errorMessage rather than errorDescription in programmatic error handling.
  • Fix authentication and parameter errors instead of repeating the same request.
  • Retry read requests, such as GET /api/orders, after 409, 503, or a timeout, with a growing delay between attempts.
  • Do not repeat an invoice creation request after a timeout or a 5xx error: the invoice may have been created. First check the order through GET /api/orders by its orderId.

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.
  • orderId and sciName storage.
  • Order lookup through GET /api/orders.
  • Completed payment handling.
  • Failed payment handling.
  • Late, underpaid, and overpaid payments (penalties).
  • Duplicate orderId handling.
  • 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 sciName and Status URL notifications without displaying the Hosted Checkout page.
  • Always use a unique orderId for 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 paymentStatus is COMPLETED.
  • Use expirationDateMillis when 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.