Crypto Payment API Integration: What Your Team Actually Has to Build

A pre-launch guide and a step-by-step video breakdown

Question {{n}} of {{t}}

Ready to go live

Your team has answers to the key questions. You are close to launch: run your tests with real payments before you go live.

Almost there

A few gaps remain. Close them before launch: each one is covered in a section of this article.

Not ready yet

Several key decisions are still open. Hosted Checkout takes the most work off your team, and you can request a live demo from the Volet.com sales team to see the payment flow first.

API pre-launch checklist

Nine questions to answer before you go live. Pick the answer that fits your team: each answer opens a short note and points to the part of this article that explains it.

Question 1 of 9

1. Does the product require a custom payment UI?

Yes, we need our own UI

No, a hosted page works

Not decided yet

If it does, you need API-only, and your team builds and maintains the payment screens. If not, Hosted Checkout is the lower-effort path, and it also accepts payments from Volet.com account balances.

→ See: API or Hosted Checkout: a practical comparison, below

2. Must we control every step of the payment funnel, or is a redirect acceptable?

We must control every step

A redirect is fine

Not decided yet

With a redirect to Hosted Checkout, Volet.com sends status notifications to your Status URL. With your own payment UI on the API, your backend has to check the payment status itself.

→ See: API or Hosted Checkout: a practical comparison, below

3. Do we have capacity to build and maintain the payment interface, expiration handling and status checks?

Yes, we have the capacity

No, Hosted Checkout fits us better

Not sure yet

API-only means your team owns the payment screens, invoice expiry (an invoice rate is valid for 60 or 15 minutes) and regular status checks.

→ See: What your team actually needs to build, below

4. Have we defined how internal orders map to payment attempts and how duplicate fulfillment will be prevented?

Yes, it is defined

Not yet

Keep each order separate from its payment attempts, use a unique orderId for every attempt and fulfill each order only once.

→ See: Backend order and payment model, below

5. Have we decided how to reconcile provider transactions, received amounts, fees and settlement currency?

Yes, we have a process

Not yet

Store the Volet.com transaction ID, the amount received and the settlement currency with every order, so each payment matches an invoice.

→ See: Backend order and payment model, below

6. Have we budgeted for failure scenarios, end-to-end QA and production monitoring?

Yes, it is in the plan

Not yet

Estimate the happy path and the failure paths separately: timeouts, expired invoices and repeat attempts take real engineering time.

→ See: Estimate the work realistically, below

7. Have we decided how to handle underpayment, overpayment, late payments and wrong-network payments?

Yes, our rules are set

Not yet

Gateway settings decide whether underpayments and overpayments are accepted. Payments sent through the wrong network may be lost. Write your rules and refund policy into your terms of sale.

→ See: How crypto payments differ from card payments, below

8. Does finance know which currency payments settle in and how conversion is priced?

Yes, finance knows

Not yet

You can keep the crypto you receive or auto-convert it. USD, USDT and USDC convert at a fixed 1:1 rate; other conversions cost extra.

→ See: What it costs with Volet.com, below

9. Have we planned how to test with real payments, given that there is no sandbox?

Yes, we have a test plan

Not yet

Volet.com has no sandbox. Request a live demo, create the gateway early and test with real payments before launch.

→ See: Testing without a sandbox, below

Your result

Answer all nine questions to see your result.

Still open:

 

How crypto payments differ from card payments

If your team has integrated card payments before, some habits will not carry over. With cards, the merchant charges the customer. With crypto, the customer sends funds from their own wallet, and your system has to react to what actually arrives. That changes what the integration must handle.

The amount can differ from the invoice. A customer may send slightly less or more than requested, for example because of network fees or exchange-rate differences. Decide in advance whether to accept underpayment and overpayment.

For example, you can accept small differences, contact the customer or issue a refund. Whatever you decide, state it in your terms of sale, together with your refund rules and who pays the network fee on a refund.

The network matters. The same token exists on several blockchains. Funds sent through the wrong network or to the wrong address may be lost.

The quote expires. An invoice rate is valid for 60 minutes if you settle in the same currency and for 15 minutes if conversion is needed. A customer who pays late may need a new payment request.

Confirmation takes time. Funds are credited only after the blockchain confirms the payment, so your interface and order logic must handle the wait.

There are no chargebacks and no automatic reversals. A confirmed on-chain transaction cannot be canceled. A refund is a separate payment under your own policy and applicable consumer protection rules.

Settlement is a business decision. Funds are credited to your Volet.com account once the payment completes. You can keep the crypto you received or auto-convert it into stablecoins or fiat, so finance can reconcile in one currency and avoid volatility.


More details: Volet.com's Business Account Fees


What Volet.com takes care of

Network confirmations handled for you. Volet.com monitors the blockchain, waits for the required confirmations and credits the funds, so your backend does not have to track blocks or confirmation counts.

One stablecoin balance across networks. A stablecoin received on one network can be withdrawn through another supported network without a separate cross-chain bridge service.

No rolling reserve. Volet.com does not hold back part of your completed payments as a rolling reserve.

Your rules for underpayment and overpayment. In the gateway settings you decide whether to accept payments that are short of or above the invoice amount. For example, if customers top up a balance with you, you can credit exactly what arrived and accept underpayments. With an overpayment, only the order amount is credited to your account.

Late payments handled. If a payment arrives after the invoice has expired, Volet.com either returns it to the customer or, in some cases, credits it to your account.

Money in, money out. The same Volet.com balance can fund your outgoing payments: mass payouts to contractors, creators or partners, or withdrawals for your own users. For example, an exchange can accept users' crypto deposits and process their crypto withdrawals from the same Volet.com balance through the API.

Volet.com helps build your global payments
In fiat, crypto, and stablecoins. Via API, hosted checkout, or easy-to-install plugins. Accept, send, and manage funds — all from code.

API or Hosted Checkout: a practical comparison

The key decision is how much of the payment experience your product needs to own — and how much engineering effort you are prepared to invest in it.

Choose API-only when you need your own payment UI and control over the full payment funnel. Your application owns every customer-facing step, from showing payment instructions to keeping the customer informed until the payment is confirmed or expires. Your team builds and maintains all of it.


Volet.com's Guides: API integration


Choose Hosted Checkout when a custom payment UI and full control over every step are not requirements. Volet.com hosts the payment page, making this generally the simpler, lower-effort path. It also works inside Telegram bots and mini apps, where the payment page opens in an in-app browser window (webview).


Read more: Crypto Payments in Telegram Mini Apps — Setup Guide, Stars Rules & Real Fees


You can also combine Hosted Checkout with the API for order lookup and reconciliation. Either way, Hosted Checkout still needs backend work. Your application keeps its own order records and matches them with the payment status on the Volet.com side. Your backend also signs the requests it sends to Hosted Checkout, which helps protect against tampered requests that could redirect a customer's payment away from your store.

Decision factorAPI-onlyHosted Checkout
Customer-facing payment UIBuilt and maintained by your teamHosted by Volet.com
Control over the payment funnelHigh: your application owns the experienceMore limited: the customer follows the hosted flow
Engineering effortHigher: UI, status checks, expiry and edge casesLower for payment UI; the backend still signs payment requests, handles notifications and updates orders
Best fitCustom checkout on a website or in an app, bot or platformA standard payment flow where redirecting to a hosted page is acceptable, including Telegram bots and mini apps
Status handlingBackend checks payment status through the APIStatus URL notifications plus API lookup for reconciliation as needed
Payment from a Volet.com account balanceNot available: API-only accepts crypto from external walletsAvailable: customers can pay from their Volet.com account balance, fee 0.25%

Volet.com's Guides: Hosted Checkout integration


Volet.com helps build your global payments
In fiat, crypto, and stablecoins. Via API, hosted checkout, or easy-to-install plugins. Accept, send, and manage funds — all from code.

What your team actually needs to build

The invoice endpoints are only one part of an API-only implementation. Before committing to it, account for the product and operational responsibilities below.

How the flow works with API-only:

  1. Create the order in your own system.
  2. Create a crypto invoice through the API.
  3. Show the customer the address, amount, currency, network and expiry time returned by the API.
  4. The customer sends the payment from their wallet.
  5. Your backend checks the payment status through the API.
  6. Once the payment is confirmed, mark the order as paid and fulfill it.

How the flow works with Hosted Checkout and the API:

  1. Create the order in your system and redirect the customer to Hosted Checkout with your orderId.
  2. The customer pays on the Hosted Checkout page.
  3. Volet.com sends a notification to your Status URL, the endpoint on your server that receives payment updates.
  4. Your backend verifies the signature and, if needed, confirms the order through the API.
  5. Mark the order as paid and fulfill it.

Payment UI and invoice lifecycle. Your application must display the payment details returned by the API accurately: amount to send, currency, blockchain network, address, any destination tag or memo, and expiry time. It should warn customers to send funds only through the specified network. Incorrect payment instructions can result in loss of funds, so this is a functional requirement, not a visual detail.

Do not tell the customer that a payment has failed or completed before the payment status confirms it.

Backend order and payment model. Keep your internal order separate from a payment attempt or invoice. This makes it easier to handle abandoned checkouts, expired invoices, a customer trying again, and status updates that arrive after the user has left the page.

Use a unique orderId for each payment attempt, as the API documentation describes. Define in your own database how each attempt maps to the order. Store the Volet.com transaction ID, the amount received and the settlement currency with each order, so finance can match every payment to an invoice without manual spreadsheets. Tax treatment of crypto receipts depends on your jurisdiction, so agree on it with your accountant.

Choose the invoice amount model. Decide whether the order is priced in the currency you expect to receive or whether the customer should send a fixed amount of a specific cryptocurrency. This choice affects price display, reconciliation, and how you explain the amount due. Align it with your pricing and accounting model, and validate the calculated values before creating live invoices. The API documentation explains how to set up each option.


Volet.com's Guides: API integration


Suppose your customer places an order for €120 and pays in crypto. Your backend should retain enough information to match the completed payment to the original order. For this payment, it would store:

  • Your order ID (ORD-10482) identifies the purchase in your system.
  • The Volet.com transaction ID (VLT-839201) links the payment to the transaction on the Volet.com side.
  • The amount received (about 139 USDT) shows what the customer actually sent.
  • The settlement currency (EUR) records the currency your finance team accounts in.
  • The payment status (final, confirmed by the API) tells you whether the payment can be treated as complete.

To reconcile, match the Volet.com transaction to your payment attempt and order, then compare the transaction ID, expected and received amounts, currency and final payment status. If a payment is missing, late or does not match the expected amount, flag it for investigation instead of automatically marking the order as paid.

A customer creates an order, opens the payment page and sends the required crypto. Before the blockchain confirms the transaction, they close the browser tab and leave your website.

Your backend keeps tracking the payment:

  1. The customer's order remains pending in your system.
  2. The payment attempt continues independently. With API-only, your backend checks its status through the API. With Hosted Checkout, Volet.com sends a notification to your Status URL.
  3. Your backend verifies the payment status through the API.
  4. Once the payment is confirmed as complete, your system marks the order as paid and triggers fulfillment.
  5. If the customer returns to your website, they see the updated order status.

The important point: closing the checkout page does not cancel the payment or confirm it. Your backend, not the browser redirect, determines when the order can be fulfilled.

Status handling and recovery. With API-only, your team needs to choose a polling strategy (how often the backend checks the status), avoid unnecessary requests, and handle temporary lookup failures without incorrectly changing the order state.

Treat a notification as a signal, not as proof of payment: verify its signature and look up the order through the API before fulfilling it. Process each order once, keyed by your own orderId, so a repeated notification or a second status check cannot fulfill it twice.

Fulfill an order only after the API confirms that the payment is complete, not when invoice creation succeeds or the browser redirects. The exact status values and how to handle each one are described in the API documentation.


Volet.com's Guides: API integration


A request can time out even when the remote system has processed it. Do not blindly retry invoice creation after an ambiguous failure. Before deciding what to do next, log the API's errorId, check the existing order and payment state, and follow the documented error handling. Never create a duplicate order automatically, and retry a request only when it is safe to do so.

Security and operational readiness. Keep API secrets and authentication credentials on the server. Never expose them in frontend code, mobile apps, bots, or client-side scripts. Configure only the permissions required by the integration and restrict API access to your servers' IP addresses: allowing all IPs is not recommended in production.

Designing a reliable payment flow

A payment flow has to handle more than the successful case.

Decide what the product should do when:

  • invoice creation times out and the result is unknown;
  • a status lookup temporarily fails;
  • an invoice expires before the customer pays;
  • the customer abandons checkout and later returns;
  • the customer starts another payment attempt;
  • a status notification is delayed or received more than once.

The goal is to avoid duplicate fulfillment, keep the internal order state consistent, and give the customer a clear next step.


Volet.com's Guides: API guide with exact status definitions and response fields


Testing without a sandbox

Volet.com does not have a sandbox or test environment. Plan for this early instead of discovering it at launch:

  • Request a live demo from the Volet.com sales team to see the payment flow, the API and Hosted Checkout before you build.
  • Create the gateway early. A new custodial gateway (one where Volet.com holds the received funds on your account) goes through a compliance review that usually takes a few hours, and you can finish the integration in the meantime.
  • Test with real payments in production: success, failure, expiry, underpayment and overpayment. Each crypto test payment is a real on-chain transaction with a network fee.
  • For Hosted Checkout, also check Status URL delivery, signature validation and the success and failure redirects.
  • Mark test orders in your database so they do not mix with real revenue during reconciliation.

Estimating the work realistically

Actual effort depends on your existing checkout architecture, the required user experience, your engineers' experience with payment APIs, and testing (QA) scope.

WorkstreamAPI-onlyHosted Checkout
Account and gateway setupAccount verification, API configuration, permissions and approvalAccount verification, Hosted Checkout configuration and any required approval
Core implementationInvoice creation, payment UI, status checks and order updatesRedirect flow, Status URL handling and backend order updates
Edge casesExpiration, ambiguous timeouts, retries, duplicate attempts and network instructionsNotification validation, redirect edge cases and reconciliation
QAPayment-detail display, status checks, expiry, failures and recoveryRedirects, notification delivery, signature validation and reconciliation
Ongoing ownershipUI maintenance, monitoring, support diagnostics and status handlingBackend monitoring, order reconciliation and callback operations

Estimate the successful path and the failure paths separately, and include time for end-to-end testing and production monitoring.

What it costs with Volet.com

From 0.25% for stablecoin and crypto payments. Conversions between USD, USDT and USDC run at a fixed 1:1 rate; other conversions are priced separately. The customer pays the blockchain network fee. No setup fee and no monthly fee. You choose who pays the processing fee. High volumes may qualify for custom pricing through sales.

Accept USDT, USDC, and leading crypto tokens worldwide
Start with the crypto payment gateway — instant settlements and fees from 0.25%

Frequently Asked Questions

No. Volet.com has no test environment. You can request a live demo from the sales team. Test success, failure, expiry, underpayment and overpayment on your side before launch.

New custodial gateways go through a compliance review first. It usually takes a few hours. Your account must be verified before you create the gateway. Use the waiting time to finish the integration.

No. With API-only, your backend checks the payment status itself. If you need notifications, use Hosted Checkout together with the API.

Your gateway settings decide whether underpayments and overpayments are accepted. If a payment arrives after the invoice has expired, Volet.com either returns it to the customer or, in some cases, credits it to your account. A customer who still wants to pay may need a new payment request.

Look up the order through the API by your orderId before you reply.

A transfer can be visible on-chain and still not match the invoice: it may be short, late or sent through another network.

Give your support team access to the payment details, and agree in advance when they escalate a case to Volet.com support.

No. A confirmed on-chain transaction cannot be canceled, and there are no card-network chargebacks. A refund is a separate payment under your own policy and applicable consumer protection rules.

No. Volet.com does not provide card acquiring. Keep your card acquirer for direct card payments.