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.

You can use the API in two ways:

API only — your application builds the full payment experience and displays the crypto address, amount, network, and expiration time to the customer.
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 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	Built by your application	Create invoice, display payment details, track status	Poll payment status through the API
API + Hosted Checkout	Hosted by Volet.com	Create or track orders, reconcile payment status	Use Hosted Checkout Status URL and API order lookup

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.
API permissions for crypto payment acceptance.
A Hosted Checkout configuration if you use the API together with Hosted Checkout.

See Create payment gateway 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`	Request authentication token generated using your API secret.

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

API-only flow

Use this flow when your application handles the full crypto payment experience.

The payment flow:

Create an order in your system.
Optionally check invoice details before creation.
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.
Your backend checks the payment status through the API.
When the payment is completed, update the order status in your system.

Step 1: 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

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

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
}

Invoice request fields

Field	Required	Description
`receiverCurrency`	Yes	Currency credited to your Volet.com account after the payment is completed.
`senderCurrency`	Yes	Currency and network the customer should use to pay.
`amount`	Yes	Payment amount. How this amount is interpreted depends on `transferAction`.
`transferAction`	Yes	Defines whether the amount is treated as the amount to send or the amount to receive. Possible values: `GIVE`, `GET`.
`note`	No	Payment note or order description.
`sciName`	No	Hosted Checkout or store name associated with the payment flow.
`orderId`	No	Your internal order ID. Use a unique value for each payment.
`subMerchantURL`	No	Website URL of the sub-merchant, if the payment is processed on behalf of another merchant.

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 credited to your account.
`expirationDate`	Invoice expiration date and time.
`expirationDateMillis`	Invoice expiration timestamp in milliseconds.

Always show the exact senderAmount, senderCurrency, address, and destinationTag if it is returned.

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.
Warning to send funds only on the selected network.

Example instruction:

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 should check the payment status.

Endpoint:

GET /api/orders

Required query parameter:

Parameter	Description
`orderId`	Merchant order identifier.

Optional query parameter:

Parameter	Description
`sciName`	Hosted Checkout or store name associated with the order.

Example request:

GET /api/orders?orderId=ORDER-1001&sciName=Store

Example response:

{
  "orderId": "ORDER-1001",
  "sciName": "Store",
  "paymentStatus": "PROCESSING",
  "paymentMethod": "CRYPTO_INVOICE",
  "paymentCreated": "2026-01-15T10:30:00",
  "transaction": {
    "status": "PROCESSING"
  },
  "invoice": {
    "invoiceStatus": "PROCESSING",
    "cryptoCurrencyAddress": "TXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "initialSenderAmount": 100,
    "actualReceivedAmount": 100,
    "senderCurrency": "USDT_TRC20",
    "cryptoCurrencyTransactionId": "11111111-1111-4111-8111-111111111111"
  }
}

Payment statuses

Use paymentStatus to decide how to update the order in your system.

Status	Meaning	Recommended action
`CREATED`	Invoice has been created and is waiting for payment.	Keep the order pending.
`PROCESSING`	Payment has been detected or is being processed.	Keep the order pending and continue checking.
`COMPLETED`	Payment has been completed successfully.	Mark the order as paid and deliver the product or service.
`FAILED`	Payment failed, expired, or could not be completed.	Do not deliver the order. Ask the customer to create a new payment.

Only treat the order as paid after the status becomes COMPLETED.

API + Hosted Checkout flow

Use this model when you want Hosted Checkout to handle the customer-facing payment page, while your backend keeps API-level control over order 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 orderId in 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 also checks the order through the API for reconciliation.

In this model, Hosted Checkout handles the payment page, payment method selection, payment instructions, and customer redirects.

The API can still be used to retrieve the payment order by orderId and reconcile the final status in your system.

Status handling with Hosted Checkout

When using Hosted Checkout, 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 and API order lookup to update order status reliably.

Recommended approach:

Receive the Hosted Checkout Status URL notification.
Verify the notification signature.
Update the order status if the notification is valid.
Use the API order lookup as a fallback or reconciliation check.

Error handling

Merchant API errors return a structured error response.

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 create a duplicate order automatically.
Retry only when it is safe to do so.

Testing checklist

Before accepting live crypto payments, test the full flow.

For API-only integrations, verify:

Invoice check.
Invoice creation.
Payment address display.
Destination tag or memo display, where required.
Invoice expiration handling.
Order status polling.
Completed payment handling.
Failed or expired payment handling.
Duplicate orderId handling.

For API + Hosted Checkout integrations, also verify:

Customer redirection to Hosted Checkout.
Status URL notification delivery.
Notification signature validation.
Success URL and Failed URL redirects.
API order lookup for reconciliation.

Important notes

API-only integrations do not use Hosted Checkout callbacks.
Your backend should check payment status through the API.
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 the payment status is COMPLETED.
Crypto payments depend on blockchain confirmations and network conditions.
Sending funds to the wrong address or network may result in permanent loss of funds.

Create payment gateway — create and configure your API
Accept custodial crypto payments — how custodial crypto payments work
Hosted Checkout integration — use the hosted payment page
API reference — complete methods, parameters, and response documentation

When to use API integration​

Integration models​

Before you start​

Authentication​

API-only flow​

Step 1: Check invoice details​

Step 2: Create a crypto invoice​

Invoice request fields​

Invoice response fields​

Step 3: Show payment instructions​

Step 4: Check payment status​

Payment statuses​

API + Hosted Checkout flow​

Status handling with Hosted Checkout​

Error handling​

Testing checklist​

Important notes​

Related​

When to use API integration

Integration models

Before you start

Authentication

API-only flow

Step 1: Check invoice details

Step 2: Create a crypto invoice

Invoice request fields

Invoice response fields

Step 3: Show payment instructions

Step 4: Check payment status

Payment statuses

API + Hosted Checkout flow

Status handling with Hosted Checkout

Error handling

Testing checklist

Important notes

Related