Purchases

Create new purchase

Changed on Nov 3, 2026

Creates a new purchase for specified country. Deducts balance immediately and returns purchase with PENDING status.

Purchase Creation Process

Validates country availability and user balance.
Reserves account from provider.
Atomically deducts balance and creates purchase record.
Returns purchase in PENDING status.

Next steps. Call POST /purchases/:id/request-code to retrieve login credentials.

Country availability. Accounts may become unavailable between checking /accounts and creating purchase. Always handle availability errors gracefully.

post/v1/purchases/

Request

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

Request body

country_codestring required

ISO 3166-1 alpha-2 country code.

Example request

{
  "country_code": "US"
}

Response

Response for status 200

idinteger required

Unique purchase identifier.

country_codestring required

ISO 3166-1 alpha-2 country code.

emojistring required

Country flag emoji.

phone_numberstring nullable required

E.164 International Format. Phone number with country code prefix (e.g., +12025550123 for US, +79991234567 for Russia).

Usage. This is your Telegram account login. Use it with verification.code and verification.password to access the account.

status'PENDING' | 'SUCCESS' | 'ERROR' | 'REFUND' | 'EXPIRED' required

Purchase Status Lifecycle. PENDING (initial) → SUCCESS (after code request) or ERROR (provider failure). Any status can transition to REFUND via admin action.

Important. Status is immutable once set to SUCCESS, ERROR, or REFUND.

Filter options

PENDING - code not requested.
SUCCESS - code ready.
ERROR - provider failed.
REFUND - money returned.

purchase_type'SINGLE' | 'BULK' | 'ADMIN' required

Type of purchase: SINGLE (regular), BULK (batch purchase), ADMIN (admin deduction)

purchase_source'BOT' | 'WEB' | 'API' required

Purchase channel: BOT (Telegram), WEB (site JWT), API (x-api-key)

created_atstring required

Purchase creation time in ISO 8601 format (UTC).

Example response

{
  "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"
}

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 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