Purchases

Request verification code

Changed on Nov 3, 2026

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

Request

Base URL
https://api.getmytg.com
URL
https://api.getmytg.com/v1/purchases/{purchase_id}/request-code
Auth
- API key in header x-api-key
- or HTTP bearer

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",
    "emoji": "🇺🇸",
    "display_name": {
      "ru": "США",
      "en": "United States"
    },
    "phone_number": "+12025550123",
    "price": {
      "amount": "1.50",
      "currency_code": "USD"
    },
    "status": "SUCCESS",
    "purchase_type": "SINGLE",
    "purchase_source": "BOT",
    "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
  }
}

Changes

Nov 3, 2026aa3ff24cbee2 Revision changes
- breaking
  the response property // became nullable for the status
- warning
  added the new EXPIRED enum value to the / response property for the response status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
- info
  added the required property / to the response with the status
- info
  added the required property / to the response with the status

Operation history