v1

latestOpenAPI 3.0.32026-07-2618073.2 KB

Purchases

Request verification code

Requests verification code and password from provider. Updates purchase status to SUCCESS.

Idempotent Operation. Safe to retry on network errors - will not generate duplicate codes.

Behavior.

First call: Fetches code from provider, updates status to SUCCESS
Subsequent calls: Returns conflict error (use GET /purchases/:id to retrieve existing code)

Provider timeout. Code retrieval may take 5-30 seconds depending on provider availability.

Webhook notification. Optionally provide callback_url to receive a POST webhook when code is retrieved. See Webhooks section for payload structure and Models section for WebhookSuccessPayload / WebhookFailedPayload schemas.

post/v1/purchases/{purchase_id}/request-code

Path parameters

purchase_idinteger required

Unique purchase identifier.

Example:12345

Request body

callback_urlstring uri

URL to receive webhook notification when code is received. POST request will be sent with either WebhookSuccessPayload or WebhookFailedPayload.

Retry policy. If your endpoint does not return HTTP 200, webhook will be retried up to 3 times with delays: immediately, after 10 seconds, after 30 seconds. Any non-200 response triggers retry.

Example request

{
  "callback_url": "https://example.com/webhooks/code-received"
}

Response

Response for status 200

Example response

{
  "purchase": {
    "id": 12345,
    "country_code": "US",
    "display_name": {
      "ru": "США",
      "en": "United States"
    },
    "phone_number": "+12025550123",
    "price": {
      "amount": "1.50",
      "currency_code": "USD"
    },
    "status": "SUCCESS",
    "purchase_type": "SINGLE",
    "verification": {
      "code": "12345",
      "password": "secret123",
      "received_at": "2024-11-19T07:52:00.000Z"
    },
    "created_at": "2024-11-19T07:50:00.000Z"
  },
  "code_request": {
    "status": "pending",
    "attempt": 1,
    "max_attempts": 18,
    "next_attempt_at": "2024-01-15T10:30:00.000Z",
    "retry_after": 10
  }
}