Cryptocurrency
Orders in fiat or in cryptocurrency paid by the payer in cryptocurrency
Before you start
Authorization
How to sign your requests with the API token.
Create payment
The base order request that this page extends.
This payment method is not enabled for all merchants. Check availability with your manager.
Overview
A crypto payment is a regular order. No extra fields are needed: the method is selected by the terminal your service is connected to. You can create the order in fiat or directly in cryptocurrency:
| Order currency | What the payer pays | Amount to pay |
|---|---|---|
RUB, USD | Cryptocurrency, e.g. USDT (TRC-20) or BTC | The order amount converted into the token at the current rate |
USDT, USDC, BTC, ETH, LTC, TRX, TON, SOL, BNB, DOGE, XMR, MATIC | The same cryptocurrency; the token network (e.g. TRC-20 for USDT) is set by the terminal | Exactly the order amount, no conversion |
The payer does not choose the token or the network: they are fixed in the terminal settings. Ask your manager which tokens and networks are enabled for your account.
Amount precision
| Currency | Decimal places | Minimum order amount |
|---|---|---|
Fiat, USDT, USDC | up to 2 | 1 |
BTC, ETH, LTC, TRX, TON, SOL, BNB, DOGE, XMR, MATIC | up to 8 | greater than 0 |
A request with more decimal places is rejected with 400. Amounts in API responses and webhooks are rounded to the same precision.
Request example
An order in fiat is a regular order creation request in RUB or USD:
curl -X POST "https://api.panel.valutix.kz/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": "5000.00",
"currency": "RUB",
"serviceId": 3,
"externalId": "order_12345",
"purpose": "Payment for order #12345",
"successUrl": "https://example.com/success",
"failUrl": "https://example.com/fail",
"callbackUrl": "https://example.com/webhooks/payments"
}'An order in cryptocurrency is created in the currency the payer pays with, and the amount is in that currency:
curl -X POST "https://api.panel.valutix.kz/v1/orders" \
-H "Content-Type: application/json" \
-H "X-Api-Token: YOUR_API_TOKEN" \
-d '{
"amount": 0.00125,
"currency": "BTC",
"serviceId": 4,
"externalId": "order_12346",
"successUrl": "https://example.com/success",
"callbackUrl": "https://example.com/webhooks/payments"
}'Response
The response is a standard order object. The order is created with the CREATED status; redirect the payer to paymentLink to complete the payment.
Order object fields
Crypto orders get paymentType: "CRYPTO" once the payment link is issued.
What the payer sees
Redirect the payer to paymentLink. Depending on the terminal, the payer lands on one of two pages:
- the provider's payment page, where the payment is completed;
- our payment page with the transfer details:
- wallet address and its QR code;
- exact amount in the token;
- tag / memo, if the network requires one. A transfer without it is not credited, so the payer must enter it exactly as shown;
- a timer showing how long the details are valid.
Wallet details are shown only on the payment page. The API does not return them: you cannot render them in your own interface.
Final amount
The amount of a crypto order can differ from the amount you requested. If the payer transfers less than required, the order stays PENDING until the payment time runs out: during this time the payer can still send the rest. After that the order is closed as COMPLETED for the amount actually paid in the order currency: the fiat equivalent for a fiat order, the transferred token amount for a crypto order. The amount field of the order is updated to this value.
A transfer in another token is not credited automatically: such an order is reviewed manually.
Credit the payer with the amount from the webhook or from the order status, not with the amount from your request. A transfer received after the payment time has run out does not change the order.
Statuses
Crypto orders use the regular order statuses:
| Status | When |
|---|---|
PENDING | Awaiting the transfer and its confirmation in the network, or awaiting the rest of an underpaid amount |
COMPLETED | The transfer is confirmed. amount is the amount actually paid, see Final amount |
EXPIRED | Nothing was paid before the payment time ran out |
FAILED | The payment failed on the provider's side |
Webhooks are sent on every status change, the same way as for other methods, see Order status and webhooks.
Test mode
On a test terminal no transfer is made; the order status follows the amount, as for other methods: 1000 — COMPLETED, 1001 — CANCELED, 1002 — FAILED, 1003 — COMPLETED, then REFUND, any other amount — EXPIRED in 5 minutes.
Recommendations
- Take the paid amount from the webhook, not from your request: it can be lower after an underpayment.
- Wait for
COMPLETEDbefore delivering goods: a transfer in the network is not yet a confirmed payment. - Store crypto amounts as decimal strings or decimal types, not floats: BTC and ETH have up to 8 decimal places.