Public catalogue
GET /api/v1/catalog returns the curated service and country catalogue. It is descriptive data, not a live provider stock feed. GET /openapi.json describes the current HTTP endpoints. Provider credentials are never sent to the browser.
User-bound quotes
POST /api/v1/quotes accepts a service and country from an authenticated, same-origin session. Quotes belong to that user and expire after 60 seconds. Their USD amount is computed on the server using verified source-currency conversion, markup and the selling-price floor.
Idempotent orders
POST /api/v1/orders accepts a quoteId and an Idempotency-Key. A retry with the same key returns the same order instead of buying another number. The wallet reservation is recorded atomically. An ambiguous provider response holds the order for review; it does not trigger an automatic second purchase.
Status and completion
GET /api/v1/orders/{id} reads an owned order and its SMS state. POST to the same endpoint with action finish or cancel requests a state transition. The server enforces the initial 120-second cancellation lock and records a refund once, after the provider confirms cancellation.
Payment confirmation
Stripe Checkout credits the matching live or test wallet only after a verified webhook and authenticated payment check. The supplied live and test keys belong to different Stripe accounts, so their keys, endpoint secrets and deposits are kept separate. NOWPayments uses a verified IPN, invoice binding and a settled-payment check with a ±0.50% amount tolerance. A browser success redirect is never proof of payment.
Access and availability
The main site and catalogue are public. Wallets, quotes and orders require authentication and ownership checks. Live actions depend on configured credentials, provider access and verified confirmations; API examples do not claim that a paid purchase or the full payment cycle has already been validated.
GET /api/v1/catalog
GET /api/v1/offers?service=whatsapp&country=usa
POST /api/v1/quotes
Content-Type: application/json
{"service":"whatsapp","country":"usa"}
POST /api/v1/orders
Idempotency-Key: <unique-request-key>
{"quoteId":"<owned-unexpired-quote-id>"}
GET /api/v1/orders/<order-id>
POST /api/v1/orders/<order-id>
{"action":"cancel"}