Read the catalog and set a price ceiling
Start with GET /api/auth/me to confirm the authenticated account and balance. GET /api/catalog/services and GET /api/catalog/countries provide selection identifiers. Read current offers with GET /api/catalog/prices?service=tg, replacing tg with the chosen service code; an optional country query narrows the result.
POST /api/orders accepts service, country, max_price_micros and idempotency_key. Send country as a string. Money limits use integer micro USD: 1,000,000 units equal 1 USD. Use the returned price_micros as your ceiling rather than inventing a price. If the offer exceeds your ceiling, refresh it and obtain approval for the new amount.
Make retries refer to the same purchase
Generate a unique idempotency_key for each intended purchase and persist it before sending the request. If a response is interrupted, retry that same operation with the same key. Generating a fresh key for a transport retry can create a second purchase.
Inspect the returned status rather than treating every HTTP 200 response as an allocated number. An order may be purchasing, waiting, received, failed or under review. Review can mean the provider's outcome is uncertain and the wallet charge remains reserved; do not automatically replace it with another purchase.
Read status and act on the existing order
GET /api/orders lists your orders, and GET /api/orders/{id} reads one order. POST /api/orders/{id}/refresh requests a status refresh. Respect rate limits and use bounded polling with backoff. Once the code has been used, POST /api/orders/{id}/finish can complete an eligible received activation.
POST /api/orders/{id}/cancel follows the same waiting-period and no-code requirements as the website. A cancellation request or timeout is not proof of a refund. Read the resulting order and GET /api/wallet/transactions to reconcile your records.
Treat the API key as account access
Do not put keys in frontend JavaScript, public repositories, URLs or screenshots. Revoke a key from the Developer API area if it is exposed or no longer required. Avoid logging authorization headers and full verification messages when they are unnecessary for support.
Build clear handling for insufficient balance, unavailable inventory, price changes, rate limits and uncertain provider outcomes. Test with a small, intentional workflow, keep the order ID in your own records, and consult the interactive API reference before deploying your integration.