Invoices

This document describes invoices: how to create one with POST /v1/invoices, read its state with GET /v1/invoices/{id}, and interpret its statuses, amounts and fees. Read it before accepting the first payment.

An invoice is the expectation of a payment of a specific amount in a specific asset before a deadline. The merchant, called a project in the cabinet (Dashboard), creates an invoice for an order and either shows the customer the amount and the address or sends the customer to the checkout page. The customer is the person who pays. All times in requests and responses are ISO 8601 in UTC, for example 2026-09-11T21:03:05.531Z.

Assets

What the service accepts. The contract addresses were read from the network, not taken from articles. Which of these assets are available to your project right now is what GET /v1/assets says: the operator can switch an asset or a network off, for maintenance for example, and then they are not in the answer.

Assets on TRON

USDC_TRON is switched off by the operator entirely: Circle has stopped minting USDC on TRON. An invoice in USDC_TRON and an invoice with USDC_TRON in currencies are refused with 422 asset_payments_disabled; the checkout page does not offer it, and it is not in the assets of a permanent address; a payout in it is refused with 422 asset_payouts_disabled. Invoices in it that are already open are still paid, and a USDC transfer to a per_user permanent address is credited as before — see what arrives at an address.

Assets on the EVM networks

• There are no payouts on the EVM networks: a payout in any of these assets is refused with 422 asset_not_payable.
• USDT on Polygon, Arbitrum and OP Mainnet is USDT0, a separate contract with an asset identifier of its own. To the customer it is the same USDT; to your code it is a different asset.
• The decimals differ: USDT and USDC on BNB Smart Chain have 18, on the other networks 6. Do not hard-code this number.
• The confirmation count is the depth at which the service treats a payment on that network as final. It differs: from 1 on Avalanche to 4800 on Arbitrum, where a block comes about every 0.25 seconds.

Assets on TON

The contract is the jetton master of the token, in the raw form the catalog holds; the same contract in the user-friendly form is EQCxE6mUtQJKFnGfaROTKOt1lZbDiiX1kCixRv7Nw2Id_sDs:

A payment on TON needs one confirmation: TON produces a masterchain block about every 0.4 seconds, and the service counts only transactions the network has finalized, so a payment is confirmed within seconds. The address of a TON invoice is in the user-friendly form — see addresses on TON.

Assets on Solana

The contract is the mint of the token, in base58 and case-sensitive. Both mints belong to the classic SPL Token program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA:

• There are no payouts on Solana: a payout in any of these assets is refused with 422 asset_not_payable.
• A payment on Solana needs one confirmation, because the service counts only what the network has settled at the commitment level the operator configured. By default that is finalized, the only level that cannot be rolled back.
• Solana has no chain id. A network of this family is told apart by its genesis hash, not by a number. The identifiers your code sees are the network ids of the registry: solana for the mainnet.
• An address and a transaction signature on Solana are base58 and case-sensitive. The signature the service returns in tx_hash is 86 to 88 base58 characters, not 64 hexadecimal digits. Never lower-case either of them — see addresses on Solana.
• A token on Solana is held not at the owner's address but in its associated token account, a separate account for the pair (owner, mint). The service creates that account when it issues the address, so a customer's wallet pays to the address as usual and needs to know nothing about it.

Native coins

TRX_TRON, GRAM_TON, SOL_SOLANA and the native coins of the EVM networks pay invoices just as tokens do: a price in US dollars is converted into the coin at an exchange rate, like any asset with a rate — see price and exchange rate. There are no payouts in them: a payout is refused with 422 asset_not_payable.

A native coin of an EVM network is credited whether a wallet or a smart contract sent it: the value of the transaction itself, or a transfer a smart contract made within it — a smart-contract wallet, a multisig, an exchange's withdrawal. The service finds a transfer from a contract by tracing the block and credits it only when the trace accounts for the whole rise of the address's balance; one it cannot account for is not credited automatically: the invoice stays unpaid, no webhook is sent, and the operator resolves it by hand. A token is credited by its transfer event, however it was sent.

A transfer of a coin to the address of an invoice in another asset is recorded as unexpected_asset: it is not credited to the merchant and does not close the invoice — see what arrives at an address.

Test networks

An installation on a TRON test network (Nile or Shasta) accepts only USDT_TRON, with that network's contract. Its TON network is the TON testnet, with GRAM_TON only: USDT is issued on the TON mainnet only. Its Solana network is solanadevnet, the Solana devnet, with USDC and the native coin only; the asset identifiers and the mint there are the devnet's own — USDC on the devnet is 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU.

Rules that follow from the tables:

• A transfer below the minimum deposit of its asset is dust: the service records it but does not credit it to the merchant and does not count it toward any invoice. The exception is the rest of a per_invoice invoice: once a payment to the invoice has arrived and the amount is not reached yet, a transfer in the invoice's asset to its address is a payment of any amount above zero — see partial payment.
• An invoice priced in US dollars (created without asset) can be paid in any asset the project accepts and the service has an exchange rate for; currencies narrows that list. Which assets those are at a given moment is what GET /v1/assets says.
• Decimals, minimum deposits and confirmation counts come from the service's asset catalog. The code has none of these numbers built in.

Amounts

Amounts are passed as strings in units of the asset, for example "49.900000". JSON numbers are not used for amounts: parsing into a floating-point number loses cents.

• In a request, an amount is digits with an optional fractional part: 49, 49.9, 49.90, 0.5. It is refused with 400 validation_failed if it has a sign, an exponent, a space, a comma, a leading zero (049), a point without digits on both sides (49., .9), or more fractional digits than the asset has.
• In a response, every amount of an asset has exactly as many fractional digits as the asset has: "49.900000" for an asset with 6 decimals. A price in US dollars (price.amount) always has 6.
• Decimals. Do not build the number 6 into your code: count the digits after the point in amount_expected, which always carries all the decimals of the invoice's asset.
• Comparison. Compare amounts as decimal numbers, not as strings: "49.9" in a request and "49.900000" in a response are the same amount.

List the assets

GET /v1/assets returns the assets the merchant can create an invoice in at the moment of the request, with the network, the contract, the decimals and the minimum deposit of each. Use it to decide which tokens to offer instead of building the list into your code.

Request

The request has no parameters and no body. The answer carries an ETag, so a product that keeps its list of coins up to date pays for one 304 while the catalog is unchanged — see conditional reads.

Response

200 with the array assets, in the order of the networks set by the operator, then by identifier. An asset is listed when all of these hold:

• the service accepts it for payments, and the operator has not disabled payments in it;
• it is not disabled in the project settings;
• its network is enabled, and the service issues addresses in that network now.

• The list shows what can be offered now, not what is credited: a transfer in an asset that has dropped out of the list is handled by the rules of its address — see what arrives at an address.
• The list does not depend on the review of the merchant or on a paused address mode: those refuse POST /v1/invoices itself, with their own codes.

Errors

Example

curl -s https://api.stons.io/v1/assets \
  -H "X-Api-Key: $API_KEY"

200 on the TRON mainnet:

{
  "assets": [
    {
      "asset": "USDT_TRON",
      "symbol": "USDT",
      "network": "tron",
      "network_name": "TRON",
      "token_standard": "TRC-20",
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "decimals": 6,
      "min_amount": "1.000000",
      "confirmations": 20,
      "icon": "usdt"
    }
  ]
}

Create an invoice

POST /v1/invoices creates an invoice for an order, or returns the invoice that already exists for the same order_id — see idempotency.

Request

The body is a JSON object with Content-Type: application/json, no larger than 16 KiB. A field that is not in the table is refused with 400 validation_failed.

The request takes one query parameter, include, whose only value is qr: the response then carries the QR code of the address. Any other query parameter, and any other value, is refused with 400 validation_failed.

An optional field is omitted when it has no value: null is refused with 400 validation_failed.

Response

201 means the invoice was created, 200 means an invoice for this order_id had already been created earlier. The body is the same in both cases. Every field is always present; a field that does not apply is null.

Idempotency

order_id is the idempotency key. When a request arrives with an order_id that already has an invoice, the service compares the request with that invoice:

• The same request gets 200 and the current state of the invoice. The request is the same when all of these match:
  • for an invoice created with asset: the same asset and the same amount as a number, compared with amount_requested, not with amount_expected;
  • for an invoice created without asset: no asset, the same price as a number, compared with price.amount, and the same set of currencies, ignoring order and repeats. This holds after the customer has chosen the token too;
  • in both cases the same external_user_id, return_url and cancel_url; a field that is absent matches only an absent field.
• Any difference gets 409 order_id_conflict: it is a different payment. A request with asset for an invoice created without it, and the reverse, is a difference.
• expires_in is not compared. A retry with another value gets the invoice with its original expires_at.

Concurrent requests with the same order_id create one invoice; the others get 200 or 409 by the same comparison. The response to a retry shows the terms recorded when the invoice was created, even if the fee rate or the merchant's settings have changed since.

Some checks run before the service looks for an existing invoice, so a retry that fails them gets the error, not the invoice:

• the request format, including the bounds of expires_in (400 validation_failed);
• external_user_id in per_user mode (400 validation_failed);
• with asset: the asset is accepted for payments (422 asset_not_supported), the amount format and decimals (400 validation_failed), the minimum deposit (422 amount_below_minimum);
• without asset: the price format and that the price is above zero (400 validation_failed).

All other checks run only when no invoice exists for the order_id yet, so they never refuse a retry of a created invoice. These checks are: merchant approval, the platform's pause of the address mode, the asset switches of the operator and of the merchant, the checks of currencies and of the exchange rates, the return URLs, and the fee settings.

Errors

What the client does for each code — see errors.

Example

curl -s -X POST https://api.stons.io/v1/invoices \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_1001", "asset": "USDT_TRON", "amount": "49.9", "expires_in": 3600}'

201:

{
  "invoice_id": "6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "order_id": "ord_1001",
  "status": "created",
  "asset": "USDT_TRON",
  "network": "tron",
  "network_name": "TRON",
  "address": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "address_explorer_url": "https://tronscan.org/#/address/TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "payment_uri": null,
  "price": null,
  "currencies": null,
  "asset_selected_at": null,
  "quote": null,
  "amount_requested": "49.900000",
  "amount_expected": "49.900000",
  "amount_received": "0.000000",
  "amount_remaining": "49.900000",
  "amount_credited": "0.000000",
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "fixed": "0.000000", "amount": "0.000000" },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "external_user_id": null,
  "return_url": null,
  "cancel_url": null,
  "checkout_url": "https://pay.example.com/pay/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "expires_at": "2026-09-11T21:03:05.531Z",
  "created_at": "2026-09-11T20:03:05.531Z",
  "deposits": []
}

A price in dollars in the asset you name

The shortest path when you keep prices in dollars and already know what you want to be paid in: one request, and the answer carries everything needed to pay. The service does the rate and the conversion.

curl -s -X POST https://api.stons.io/v1/invoices \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_2001", "asset": "SOL_SOLANA", "amount": "99", "price_currency": "USD", "expires_in": 3600}'

price_currency: "USD" means amount is a price in dollars rather than a number of coins. The field is optional: without it amount is still an amount in units of the asset, and nothing in your integration changes.

The answer carries what you show the customer right away:

• address — where to pay;
• amount_expected — how many coins to send;
• price — the price in dollars, as you sent it;
• quote.rate — the rate the amount was computed at, and quote.expires_at — how long it holds;
• expires_at — the invoice deadline; qr with include=qr.

Such an invoice needs no checkout page: you chose the token.

What happens to the rate afterwards

The amount is fixed by a quote. In a token pegged to the US dollar, such as USDT_TRON, it holds until the invoice's deadline and is never requoted. In any other token, when the quote's window runs out while the invoice still waits for money, the service requotes the remainder at the new rate: what arrived stays as it arrived, and what is still owed is counted in dollars at the invoice's rate. See quote window.

If there is no rate, or it is stale, the invoice is not created: the answer is 503 rate_unavailable and nothing is left in the database. An honest refusal beats an invoice with no address and no amount.

A repeat with the same order_id returns the same invoice with the same amount, as for any other invoice.

Showing «≈ 0.45 SOL» before you create anything

GET /v1/rates answers, for every asset of your project, with the rate the invoice will actually use: the market rate with the service's markdown already taken off. So the number you show in advance is the number the invoice carries.

curl -s https://api.stons.io/v1/rates -H "X-Api-Key: $API_KEY"

{
  "rates": [
    {
      "asset": "SOL_SOLANA",
      "symbol": "SOL",
      "rate": "213.450000000000000000",
      "market_rate": "220.050000000000000000",
      "markdown_percent": "3.00",
      "observed_at": "2026-10-06T12:31:07.218Z",
      "fresh": true,
      "currency": "USD"
    }
  ]
}

Change feed

GET /v1/invoices returns the invoices of the project in the order their state changed, oldest change first. It is the catch-up path: a webhook arrives in seconds and stays the main one, while the feed is for when the receiver was down longer than the seven deliveries cover.

Request

Any other query parameter is refused with 400 validation_failed; include is among them, so the feed never carries QR codes. The answer carries an ETag: a walk that finds nothing new costs one 304 without a body — see conditional reads.

Response

Transfers are left out on purpose: a page of fifty invoices would carry hundreds of rows nobody asked for, and the amounts of the invoice already say how much arrived. When transfers are wanted, read the invoice by its id.

A page ends at its last row and the next page starts strictly after it, so an invoice that changes during the walk never shifts a page — unlike an offset, where a row can be skipped or read twice. A cursor this service did not give out is refused with 400 validation_failed.

How to keep your orders in step:

1. Handle webhooks — that is the fast path.
2. Keep the moment of the last change you processed.
3. If webhooks stopped arriving, walk the feed from that moment, page after page, until next_cursor is null, and move the moment forward.

The customer chooses the token

A request without asset creates an invoice without a token: the customer chooses the coin and the network on the checkout page and sees the amount and the address only after the choice.

• Price. amount is a price in US dollars. At the choice the service converts it into the chosen token at an exchange rate — see price and exchange rate.
• Checkout page. It is required. If the installation has none, the request is refused with 422 asset_required.
• Allowed tokens with currencies. At creation, each listed asset must be accepted for payments (422 asset_not_supported), enabled by the operator (422 asset_payments_disabled) and in the project settings (422 asset_disabled_by_merchant), and have an exchange rate (422 asset_not_offered). The price converted at the current rate must not be below its minimum deposit (422 amount_below_minimum).
• Allowed tokens without currencies. At creation, the service takes every asset that is accepted for payments, enabled by the operator and in the project settings, and has an exchange rate. If there is none, the response is 422 no_payable_assets. Each asset taken must take the price, converted at the current rate, as at least its minimum deposit, with the same error as above.
• No fresh rate at creation. An allowed asset whose rate is not fresh at this moment is not checked against its minimum deposit: the checkout page checks it when it offers the choice. If none of the allowed assets has a fresh rate, the request is refused with 503 rate_unavailable and no invoice is created: nobody could pay it right now.
• What the page offers. Of the allowed tokens, the checkout page offers those that pass the same checks at the moment the page is shown, each with its amount at the current rate.
• Before the choice, asset, network, address, quote, amount_requested, amount_expected, amount_received, amount_remaining, amount_credited, fees.service.fixed and fees.service.amount are null, and price holds the price. The fee rate and the payers are recorded at creation, as for any invoice.
• The choice is possible while the status is created and the service's clock has not reached expires_at. The choice is final: the token cannot be changed. At the choice the service records the asset, issues the address, converts the price into the token and records the first quote. It computes amount_expected from the converted price the same way as for an invoice created in that asset: with the fee rate and the payers recorded at creation and the fixed part of the fee of that asset at the moment of the choice. asset_selected_at is the moment of the choice. From then on the invoice is paid like an invoice created with that asset, except that what is still owed is quoted again after the quote window.
• No choice by the deadline. When the service's clock reaches expires_at, the invoice becomes expired, and invoice.expired arrives with asset and the amounts set to null. Such an invoice cannot be paid: it has no address.
• per_user mode. external_user_id is required, as always, and after the choice the invoice gets the user's permanent address. A transfer to that address that appeared in a block before the choice does not pay the invoice: it is a top-up, credited to the merchant's balance with the top-up fee, and deposit.confirmed arrives with invoice_id set to null. The checkout page shows the address only after the choice, so do not give the customer the permanent address to pay such an invoice outside the page.

curl -s -X POST https://api.stons.io/v1/invoices \
  -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"order_id": "ord_1002", "amount": "49.9", "currencies": ["USDT_TRON"]}'

201:

{
  "invoice_id": "8d2c7a4e-1b3f-4c5d-9e6f-7a8b9c0d1e2f",
  "order_id": "ord_1002",
  "status": "created",
  "asset": null,
  "network": null,
  "network_name": null,
  "address": null,
  "address_explorer_url": null,
  "payment_uri": null,
  "price": { "amount": "49.900000", "currency": "USD" },
  "currencies": ["USDT_TRON"],
  "asset_selected_at": null,
  "quote": null,
  "amount_requested": null,
  "amount_expected": null,
  "amount_received": null,
  "amount_remaining": null,
  "amount_credited": null,
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "fixed": null, "amount": null },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "external_user_id": null,
  "return_url": null,
  "cancel_url": null,
  "checkout_url": "https://pay.example.com/pay/8d2c7a4e-1b3f-4c5d-9e6f-7a8b9c0d1e2f",
  "expires_at": "2026-09-11T21:03:05.531Z",
  "created_at": "2026-09-11T20:03:05.531Z",
  "deposits": []
}

Price and exchange rate

The service converts a price in US dollars into a token at an exchange rate: the price of one whole unit of the token's coin in US dollars. The service collects the rates itself from a market data source and uses a rate only while it is fresh.

• Stablecoins too. A token pegged to the US dollar is converted at its own market rate, never one to one: at 0.9991 USD per USDT, a price of 100 USD is 100.090082 USDT.
• A token not pegged to the US dollar is converted at its market rate lowered by the platform's markdown, so the customer sends more coins. A token pegged to the US dollar has no markdown.
• Rounding up. The amount is rounded up to the step of the token, so the customer pays at least the price. The step follows what the token is pegged to. A token pegged to the dollar steps by its cent: a price of $229.00 at a rate of 0.9999 asks for 229.03, not 229.024488. A token pegged to nothing steps by 0.00000001 of its unit: a cent of ether would be 26 dollars, so it must not be rounded to one. The step is never finer than the token's own minimal unit.
• Any price with up to 6 decimals can be converted: there is no refusal because a price cannot be written exactly in a token.
• Which rate. The rate the checkout page showed the customer, if it is still fresh at the choice; otherwise the latest fresh rate. The amount recorded at the choice is the amount shown while the shown rate is fresh.
• The service fee is computed from the converted price, as for an invoice created in that token — see fees.
• Compare your price with price.amount. amount_requested of such an invoice is the price converted into the token.

The quote

quote describes the rate the current amounts in the token were computed at:

quote is null for an invoice created with asset, before the choice, and for an invoice whose token was chosen before exchange rates were introduced: such an invoice was converted one to one and is not quoted again.

quote right after the choice of USDT_TRON at 0.9991 USD per USDT; expires_at is the invoice's deadline, since the token is pegged to the dollar:

{
  "rate": "0.999100000000000000",
  "market_rate": "0.999100000000000000",
  "markdown_percent": "0.00",
  "currency": "USD",
  "number": 1,
  "expires_at": "2026-09-11T21:03:05.531Z"
}

Quote window

The amounts of a quote hold until quote.expires_at.

• A token pegged to the US dollar (USDT_*, USDC_*): quote.expires_at is the invoice's expires_at. The amount fixed at the choice holds for the whole life of the invoice, and so does the rest after a partial payment: such a token trades within hundredths of a percent of the dollar, there is no tolerance for an underpayment, and an amount that moved under the customer would leave one who paid exactly what was shown a few cents short. The rate is still read at the choice; it is not taken as one to one.
• Any other token: a window the platform sets, counted from the moment of the quote and never later than the invoice's expires_at.
• After the window of a token not pegged to the dollar the service quotes what is still owed again at the current rate, if the invoice is created or partially_paid, its deadline has not passed, and no transfer to it is waiting for confirmations. The window is judged by block time: the service quotes again only after it has processed blocks later than the end of the window, so every transfer sent inside the window is already counted.
• What changes. The rest still owed is worth, in US dollars, what it was worth at the old rate; the new quote asks for that worth at the new rate, rounded up the same way. amount_expected becomes amount_received plus the new rest, and amount_remaining follows it. amount_requested changes by the same amount: the part of amount_expected that is the service fee paid by the customer keeps its amount in units of the token. quote gets the next number, new rates and a new expires_at.
• What does not change. The price in price, the status, the address, the fee rate and the payers. No webhook is sent: read the current amounts with GET /v1/invoices/{id}. The checkout page shows them by itself.
• A payment of the previous amount. The customer may have copied the amount while the previous quote held, and the transfer may reach a block only after the new one replaced it. A transfer in a block no later than 10 minutes after the end of the previous quote's window is judged against the previous quote's amount as well: if the payments by then cover it, the invoice becomes confirmed, and its amount_requested, amount_expected and quote are those of the previous quote again. A later transfer is judged against the quote in force only. What is credited is always what arrived.
• No fresh rate. The old amounts hold until a fresh rate appears; the service tries again on its next pass.
• An invoice created with asset is never quoted again: its amount is set by the merchant in the token.

Retrieve an invoice

GET /v1/invoices/{id} returns the current state of an invoice. Decide whether to fulfill an order by this response — after a webhook, after a redirect from the checkout page, and when polling — not by the webhook body: see webhooks.

Request

The read is conditional: the answer carries an ETag, and a request that returns it in If-None-Match gets 304 Not Modified with no body while nothing has changed — see conditional reads.

Response

200 with the same object as the response to creation — see create an invoice. Fields of a deposits element:

deposits lists only payments to this invoice, in the order of their blocks. It does not list dust, transfers of another asset, transfers that disappeared in a chain reorganization, or per_user top-ups.

Errors

A merchant that has not been approved can read its invoices: this route does not return merchant_not_approved.

Example

curl -s https://api.stons.io/v1/invoices/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44 -H "X-Api-Key: $API_KEY"

200, the invoice from the creation example after it was paid:

{
  "invoice_id": "6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "order_id": "ord_1001",
  "status": "confirmed",
  "asset": "USDT_TRON",
  "network": "tron",
  "network_name": "TRON",
  "address": "TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "address_explorer_url": "https://tronscan.org/#/address/TUEZSdKsoDHQMeZwihtdoBiN46zxhGWYdH",
  "payment_uri": null,
  "price": null,
  "currencies": null,
  "asset_selected_at": null,
  "quote": null,
  "amount_requested": "49.900000",
  "amount_expected": "49.900000",
  "amount_received": "49.900000",
  "amount_remaining": "0.000000",
  "amount_credited": "49.401000",
  "fees": {
    "service": { "payer": "merchant", "percent": "1.00", "fixed": "0.000000", "amount": "0.499000" },
    "network": { "payer": "merchant", "quote": null, "quote_rate": null, "actual": null, "status": "included" }
  },
  "external_user_id": null,
  "return_url": null,
  "cancel_url": null,
  "checkout_url": "https://pay.example.com/pay/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44",
  "expires_at": "2026-09-11T21:03:05.531Z",
  "created_at": "2026-09-11T20:03:05.531Z",
  "deposits": [
    {
      "tx_hash": "50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c",
      "amount": "49.900000",
      "confirmations": 20,
      "status": "confirmed",
      "block_time": "2026-09-11T20:10:42.000Z",
      "late": false,
      "explorer_url": "https://tronscan.org/#/transaction/50d858e0985ecc7f60418aaf0cc5ab587f42c2570a884095a9e8ccacd0f6545c"
    }
  ]
}

Where the money goes

A confirmed payment waits on the deposit address until the service moves it. Where it is moved is a property of the project, set by the operator, and it changes nothing about the API: the same requests, the same statuses, the same webhooks.

• By default the money goes to the service's treasury, and the merchant's balance is what the service owes it — read with balance and withdrawn in the Dashboard.
• A project the operator has switched to direct settlement gets the money of each payment forwarded to its own wallet, net of the service fee, without asking for anything. Its balance therefore stays at zero: a zero there means the money is already in its own wallet, not that nothing was paid.

What this changes for an integration:

• settled means "the money has left the deposit address". For a project settled directly, that is its own wallet; for every other project, the treasury. The order is fulfilled at confirmed either way — never wait for settled.
• Small payments accumulate. The service moves money only when the transfer is worth its cost, which is a threshold per asset: below it the payment waits on the deposit address until later payments to the same address add up, or until staff move it by hand. On TRON a transfer costs about a dollar, so the threshold there is tens of dollars; on the EVM networks and TON it is cents. The invoice is confirmed all the same, and amount_received is the truth about what arrived.
• A withdrawal request still works for whatever a project earned before the switch. Money already on its way to the project's own wallet is not offered for withdrawal: it would be the same money twice.

QR code

A product that draws its own payment screen asks for the QR code of the address with include=qr, on creation and on a read of one invoice:

curl -s "https://api.stons.io/v1/invoices/6f1d3c1e-2f7a-4f0e-9a51-0c8b3e2d7a44?include=qr" -H "X-Api-Key: $API_KEY"

The invoice then has one field more, qr, with the code as an SVG image in a data: URL — shortened here, the whole value is about 11 KB:

"qr": { "address": "data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNDUgNDUi…" }

Show it as the src of an <img>: no QR library on your side, and no second request.

<img src="data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgNDUgNDUi…" alt="" width="240" height="240">

• The code holds the payment address, in full and in the form the invoice gives it. It is the same image the checkout page draws, so a wallet reads your screen and ours alike.
• qr.address is null while the customer has not chosen the token: the invoice has no address yet. The field itself is absent unless include=qr asked for it.
• Only POST /v1/invoices and GET /v1/invoices/{id} take include. The change feed does not: a page of fifty codes is half a megabyte nobody asked for.
• The code does not hold payment_uri. Our own page offers that link as a button, not as a code; draw your own code of it if you have checked that your customers' wallets read such links from a camera.
• The image is an SVG that runs nothing, black on white, and scales to any size. Give it a size in your markup, and keep alt empty: the address is beside it in text, in full, and a screen reader must read that, not a picture.

Statuses

The watcher changes statuses. It reads blocks one block behind the head of the chain, so a transfer becomes visible within a few seconds. A USDT confirmation on TRON takes 20 blocks, about a minute. On TON it takes one block, a few seconds.

Terms used below:

• On time — a transfer whose block_time is not later than expires_at. Late — a transfer whose block_time is later.
• The deadline has passed — the service has processed a block whose time is later than expires_at. For an invoice whose token has not been chosen: the service's clock has reached expires_at.

Transitions:

• created → seen: an on-time transfer appears in a block.
• seen → confirmed: the confirmed on-time transfers reach amount_expected.
• seen → partially_paid: before the deadline, the last unconfirmed on-time transfer is confirmed or disappears in a reorganization, and the confirmed on-time transfers are below amount_expected.
• partially_paid → seen: before the deadline, another on-time transfer appears in a block.
• seen → created: before the deadline, the only on-time transfer disappears in a chain reorganization.
• created → expired: the deadline passes without on-time transfers.
• partially_paid → underpaid, partially_paid → paid_late: the deadline has passed without the rest arriving on time; the new status follows from the table.
• seen → underpaid, seen → paid_late, seen → expired: the deadline has passed, and the last unconfirmed on-time transfer is confirmed or disappears; the new status follows from the table.
• underpaid → paid_late, expired → paid_late: a late transfer is confirmed.
• underpaid → seen, expired → seen: a transfer that disappeared in a reorganization returns to a block before the deadline. This is rare.
• confirmed → settled: the funds have left the deposit address — see where the money goes.

stateDiagram-v2
  [*] --> created
  created --> seen: on-time transfer in a block
  seen --> created: transfer vanished in a reorganization
  seen --> confirmed: confirmed on-time total reached the amount
  seen --> partially_paid: part of the amount confirmed before the deadline
  partially_paid --> seen: another on-time transfer in a block
  partially_paid --> underpaid: deadline, the rest did not arrive
  partially_paid --> paid_late: deadline, late transfer confirmed
  created --> expired: deadline without transfers
  seen --> underpaid: deadline, confirmed less than expected
  seen --> expired: deadline, on-time transfer vanished
  seen --> paid_late: deadline, late transfer confirmed
  underpaid --> paid_late: late transfer confirmed
  expired --> paid_late: late transfer confirmed
  underpaid --> seen: transfer returned to the chain
  expired --> seen: transfer returned to the chain
  confirmed --> settled: funds have left the address

Rules:

• Before the deadline, transfers to the invoice address add up: the first transfer is not final.
• A confirmed transfer stays counted. Only an unconfirmed transfer can disappear in a reorganization; the merchant then receives deposit.orphaned.
• A transfer to a confirmed, settled or paid_late invoice does not change its status: amount_received grows, and deposit.confirmed reports the transfer.
• Because the deadline is decided by processed blocks, an invoice can stay created, seen or partially_paid for a few seconds after expires_at, and longer while an on-time transfer waits for confirmations.

When the status changes, the merchant receives the webhook named after the new status: invoice.seen, invoice.partially_paid, invoice.confirmed, invoice.underpaid, invoice.expired or invoice.paid_late. An overpayment also sends invoice.overpaid together with invoice.confirmed. The transitions to created and to settled have no webhook. The event arrives on every transition: an invoice that goes from partially_paid to seen with a new transfer, and back when that transfer disappears, receives invoice.seen and invoice.partially_paid again.

Partial payment

There is no tolerance for an underpayment: an invoice becomes confirmed only when confirmed on-time transfers cover the whole amount_expected. If the customer sent less, they can send the rest to the same address before the deadline.

• partially_paid is the moment to ask for the rest. Show the customer amount_remaining and the same address, and remind them of expires_at. The checkout page does this by itself — see checkout page.
• A rest below the minimum deposit of the asset pays the invoice too. While a payment to the invoice has already arrived and amount_expected is not reached yet, a transfer in the invoice's asset to its address is a payment even below min_amount, as long as it is above zero. The first transfer to an invoice, and a transfer after the amount is reached, are still dust when they are below the minimum deposit.
• seen means a transfer is waiting for confirmations, and amount_remaining does not count it yet. Do not ask for more: the rest may already be on its way. After the confirmation the invoice becomes confirmed, or partially_paid with the exact rest.
• After the deadline the rest no longer pays the invoice. A transfer in a block later than expires_at makes it paid_late, and without such a transfer the invoice becomes underpaid. The merchant decides what happens to the order.
• An invoice created without asset in a token not pegged to the US dollar can have its rest quoted again after the quote window: take amount_remaining from a fresh response, not from an earlier one.
• An exchange may keep its withdrawal fee out of the amount the customer sends, and less arrives at the address. Warn the customer: the whole amount must arrive at the address.

amount_remaining is amount_expected minus amount_received, but not below zero, so it is zero for confirmed and settled. For underpaid and paid_late it is the shortfall against amount_expected: late transfers count in amount_received.

per_user mode

In per_user mode a user of the merchant has one permanent address, and all invoices of the user are paid to it — see addresses. When a transfer to that address appears in a block, the service decides once what it pays:

• An invoice, if the user has one that matches: the same asset, amount_expected equal to the transfer amount, status created with no other transfer, and expires_at not earlier than the time of the transfer's block. Of several such invoices, the earliest created one is paid.
• A top-up otherwise: the transfer is credited to the merchant's balance with the top-up fee, and deposit.confirmed arrives with invoice_id set to null. A top-up never pays an invoice later.

Consequences:

• a transfer of a different amount is a top-up, not a partial payment;
• a transfer of the exact amount after the deadline is a top-up;
• an invoice whose token has not been chosen takes no part;
• the amount compared is amount_expected: if the customer pays the service fee, it is the price together with the fee;
• partially_paid and underpaid do not occur in this mode, and paid_late occurs only if a reorganization moves the matched transfer into a block after the deadline.

Fees

STONS withholds a service fee from every confirmed payment: a percentage and a fixed amount set by the operator. The percentage is common to the platform or set for a specific merchant; the fixed amount is set per asset and is the same for all merchants. Either number can be zero. The project setting "Who pays the fees" in the cabinet decides who pays the service fee: the merchant or the customer.

An invoice has no separate network fee. The network costs of accepting a payment — moving the funds from the deposit address to the treasury — are included in the service fee. That is what the fees.network line says: status = included. Payouts have a fee of their own — see the payout fee.

The rate and the payers are recorded in the invoice when it is created, and the fixed amount when the asset becomes known: at creation for an invoice with asset, at the customer's choice for an invoice without it. Recorded terms do not change: a change of the tariff or of the project settings affects only new invoices. Invoices created before the fee was introduced carry a rate of 0, and those created before the fixed amount was introduced carry a fixed amount of 0.

Fields

How the service fee is calculated

In the formulas, "rate" is fees.service.percent divided by 100, "fixed" is fees.service.fixed, and "received" is the total of all confirmed payments of the invoice.

• The customer pays the fee. The rate applied to the price, rounded up to the last decimal place of the asset, and the fixed amount are added to the price: amount_expected = amount_requested + ⌈amount_requested × rate⌉ + fixed. An invoice for 100 USDT at 2% and 1.70 USDT expects 103.70 USDT.
• The fee is withheld when each payment is confirmed, in the same operation that credits the payment, and it is calculated from "received":
  • the merchant pays: min(received, ⌊received × rate⌋ + fixed);
  • the customer pays: min(received, fixed + ⌊max(0, received − fixed) × rate / (1 + rate)⌋): first the fixed amount, then the share of the percentage inside the amount paid.
• No more than what was received. A payment smaller than the fixed amount is withheld in full, and no more: the credited amount does not go below zero.
• Rounding down, in the merchant's favor. Each subsequent transfer withholds the difference between the fee on the new total and the fee already withheld, so an invoice paid in several transfers withholds as much as one paid in a single transfer, and the fixed amount only once.
• An exact payment by the customer withholds exactly what was added to the price, or one minimum unit of the asset less if the percentage of the price does not divide evenly: rounding down leaves that unit to the merchant.
• Overpayment: the fee is taken from the larger amount. Underpayment: from the amount received. Payment after the deadline: like any confirmed payment.
• Dust and transfers of another asset carry no fee: they are not payments. A transfer that disappears in a reorganization before confirmation is not credited and carries no fee.
• A per_user top-up carries a fee on the transfer amount at the merchant's rate and the asset's fixed amount in effect at the time of the transfer's block, no more than the transfer amount, and the merchant pays it. Each top-up is a separate operation with its own fixed amount. The merchant's balance receives the transfer amount minus this fee; deposit.* webhooks carry no fee fields.

Example: price 100 USDT, rate 2%, fixed amount 1.70 USDT, the customer pays the fee. The customer pays in two transfers: 1 USDT, then 102.70 USDT.

Your integration compares its price with amount_requested for an invoice created with asset, and with price.amount for an invoice created without it: there amount_requested is the price converted into the token. The customer is shown amount_expected: only that amount closes the invoice.