SMS verification API design: quote, order, status and cancel

Separate the client interface from provider access

The browser should request your application API; your server calls the SMS provider. Store provider credentials in runtime secrets and return only the order fields the authenticated user needs. A public catalog is different from a private account or inbox. Check ownership on every order operation, including status polling, cancellation and completion. Authentication on the purchase route alone is insufficient.

Make the quote authoritative and short lived

ReceiveSMSGo's implemented POST /api/v1/quotes creates a user-bound quote that lasts 60 seconds. Its server calculates USD pricing as max($0.39, converted provider cost × 2). The client sends a quote identifier, not a trusted price, when creating an order. If the quote expires, request a new one. An offer can disappear between lookup and purchase, so represent availability errors explicitly.

Reserve once and handle uncertain purchases

POST /api/v1/orders requires an Idempotency-Key and a quoteId. Reusing the same key for the same intended operation returns its existing order. The implemented wallet reservation and ledger update are atomic. If the provider's purchase response is ambiguous, the order moves to review instead of automatically purchasing again. Idempotency protects your application boundary; it does not magically reconcile a provider timeout.

1. Create one key for one intended purchase and retain it through retries.
2. Submit the current quote identifier with authenticated user context.
3. Reconcile ambiguous outcomes before beginning another purchase.

Poll the owned order without hammering providers

GET /api/v1/orders/{id} returns the user's order and may refresh active provider status. The implementation limits provider checks to at most one per five seconds per order. Model waiting, received, finished, cancelled, expired and review states separately. Do not manufacture an expiration time when provider documentation leaves its units unclear. A browser closing is not evidence that the remote order ended.

Confirm cancellation before touching the balance

POST /api/v1/orders/{id} accepts cancel or finish actions. Cancellation is blocked for 120 seconds after creation; afterwards, the server requests provider cancellation before applying one refund. Finishing requires a received SMS code. Concurrent actions use state transitions to prevent overlapping work. A failed network request must not be interpreted as either successful cancellation or permission to issue a duplicate credit.

Verify callbacks and distinguish code from operational readiness

An incoming callback is not automatically authoritative. Stripe signature verification is followed by a canonical payment lookup before crediting. An unsigned SMS status notification is only a hint to fetch authenticated order status. Test and live Stripe events must match their endpoint secret, account and deposit environment. External callbacks must be reachable; a redirect is not proof of payment. Workspace APIs require an authenticated site session, not a public developer API key. Review enabled operations and OpenAPI before integration.