API docs by Redocly

Partner S2S API (1.2.0)

Download OpenAPI specification:

Server-to-Server API for automated partner integrations with digital goods distribution platform.

Changelog

1.2.0

  • GET /services/esim/{iccid}/status — response schema corrected to match the actual provider response (previously documented fields like esim_id, data_balance, active_packages did not exist in the real response; see EsimStatus/EsimPackage schemas for the current shape)
  • Added POST /catalog/quote — locks a SKU's price for ~90 seconds; pass the returned quote_id to POST /orders to guarantee the order is created at that price. See the rate limits table below for its bucket.

Authentication

All requests require Bearer token:

Authorization: Bearer {your-s2s-token}

Rate Limits

Limits are enforced per partner (not per IP), independently for each group below — exhausting one does not affect the others. Exceeding a limit returns 429 Too Many Requests. The response includes X-RateLimit-Limit and X-RateLimit-Remaining headers on every request, and Retry-After on 429 responses.

Endpoints Limit
GET /catalog/* (products, pricelist, categories) 300 requests/minute
POST /catalog/quote 120 requests/minute
GET /orders, GET /orders/{uuid} 120 requests/minute
POST /orders, POST /esim/{iccid}/topup 120 requests/minute
GET /services/esim/{iccid}/status 60 requests/minute

Order status changes are pushed via webhooks — prefer subscribing to those over polling GET /orders/{uuid}, both to reduce latency and to stay comfortably under the read limit.

Info

Authentication and balance info

Verify token

Get authenticated partner information

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get balance

Current balance with overdraft information

Authorizations:
BearerAuth

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get balance transaction history

Paginated balance transaction history

Authorizations:
BearerAuth
query Parameters
cursor
string

Pagination cursor from meta.next_cursor

per_page
integer [ 1 .. 100 ]
Default: 50

Items per page (max 100)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Catalog

Product catalog

List products

Get paginated product list with optional filters

Authorizations:
BearerAuth
query Parameters
locale
string
Enum: "en" "ru"
Example: locale=en

Locale for translations (defaults to partner's locale)

cursor
string

Pagination cursor from previous response

per_page
integer <= 200
Default: 100

Items per page

category_id
integer

Filter by category

type
string
Enum: "voucher" "recharge_fixed" "recharge" "voucher_open_range" "esim" "other"

Filter by product type

include_skus
boolean
Default: false

Include SKU list (without pricing)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Get product details

Get product with SKUs, pricing and stock information

Authorizations:
BearerAuth
path Parameters
uuid
required
string <uuid>
query Parameters
locale
string
Enum: "en" "ru"
Example: locale=en

Locale for translations (defaults to partner's locale)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Get pricelist

SKU prices and stock status

Authorizations:
BearerAuth
query Parameters
locale
string
Enum: "en" "ru"
Example: locale=en

Locale for translations (defaults to partner's locale)

cursor
string
per_page
integer <= 200
Default: 100
category_id
integer
type
string
Enum: "voucher" "recharge_fixed" "esim"

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Lock a price

Locks the current price for a SKU for a short time, returning a quote_id you can pass to POST /orders (as quote_id) to guarantee the order is charged exactly this price, even if it changes before you place the order.

  • The quote is single-use: once used by an order, it cannot be reused.
  • The quote expires quickly (a few tens of seconds — see expires_at in the response). Request a fresh quote if it expires before you order.
  • Using a quote is optional. POST /orders without quote_id still works exactly as before, priced at whatever is current at that moment.
  • For custom-denomination products, pass the same fields.amount you intend to order with — the locked price is only valid for that amount.
Authorizations:
BearerAuth
Request Body schema: application/json
required
sku_id
required
string <uuid>
fields
required
object

Same fields you would send in POST /orders item.fields (e.g. amount for custom-denomination products).

Responses

Request samples

Content type
application/json
Example
{
  • "sku_id": "019bc0dd-8562-7173-afd9-a5cc534fafb7",
  • "fields": {
    }
}

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "data": {
    }
}

Get categories

Available categories with attributes

Authorizations:
BearerAuth
query Parameters
locale
string
Enum: "en" "ru"
Example: locale=en

Locale for translations (defaults to partner's locale)

target
string
Enum: "product" "sku"

Filter attributes by target

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ]
}

Orders

Order management

List orders

Get order history with filters

Authorizations:
BearerAuth
query Parameters
cursor
string
per_page
integer <= 100
Default: 50
status
string
Enum: "created" "processing" "completed" "cancelled" "failed" "partially_completed"
external_id
string

Search by your order ID

date_from
string <date-time>
Example: date_from=2025-01-01T00:00:00Z
date_to
string <date-time>
Example: date_to=2025-01-31T23:59:59Z

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": [
    ],
  • "meta": {
    }
}

Create order

Create new order. Requires HMAC-SHA256 signature for S2S authentication.

Authentication Requirements

  • ✅ X-Timestamp header is required
  • ✅ X-Signature header is required
  • ✅ Authorization: Bearer {s2s_token} is required

Signature Calculation

message   = timestamp + sku_id + external_id
signature = HMAC-SHA256(message, partner_secret)

Where timestamp is the value from X-Timestamp header (Unix integer), sku_id is item.sku_id from request body, external_id is external_id from request body.

Example:

timestamp   = "1768478058"
sku_id      = "019bc0dd-8562-7173-afd9-a5cc534fafb7"
external_id = "ORD-12345"
message     = "1768478058019bc0dd-8562-7173-afd9-a5cc534fafb7ORD-12345"
signature   = hmac_sha256(message, partner_secret)

Important Notes

  • Timestamp tolerance: ±5 minutes from server time
  • Secret location: Get partner_secret from your partner settings (not the API token!)
  • external_id uniqueness: Must be unique across all your orders
  • Balance check: Ensure sufficient balance (including overdraft if enabled)
  • Price consistency: prices can change between fetching the pricelist and placing an order. Pass quote_id (from POST /catalog/quote) to guarantee the order is charged exactly the price you saw.
Authorizations:
BearerAuth
header Parameters
X-Timestamp
required
integer
Example: 1768478058

Unix timestamp (tolerance ±5 minutes)

X-Signature
required
string
Example: 13fbd7a9a501ea39aeec861a27158dfa00c491aa657798adac8ed9b2066a6fa2

HMAC-SHA256 signature (hex)

Request Body schema: application/json
required
external_id
required
string

Your unique order identifier

required
object
metadata
object or null

Custom metadata for your records

quote_id
string or null <uuid>

Optional. quote_id from POST /catalog/quote to guarantee this order is charged exactly that price, regardless of any pricing change since the quote was fetched. Single-use; expires quickly. Omit to price the order at whatever is current, as before.

Responses

Request samples

Content type
application/json
Example
{
  • "external_id": "ORD-12345",
  • "item": {
    }
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Order created successfully",
  • "data": {
    }
}

Get order details

Get order by UUID

Authorizations:
BearerAuth
path Parameters
uuid
required
string <uuid>
Example: 7898e683-4e56-44a3-9782-eca3f758a844

Order UUID

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Services

Post-purchase service management (eSIM, subscriptions, etc.)

Top-up eSIM

Add a new data package to an existing eSIM by creating a top-up order.

This endpoint creates a regular order that recharges an existing eSIM instead of creating a new one.

Authentication Requirements

  • ✅ X-Timestamp header is required
  • ✅ X-Signature header is required
  • ✅ Authorization: Bearer {s2s_token} is required

Signature Calculation

IMPORTANT: Top-up signature uses ICCID instead of SKU ID.

message   = timestamp + iccid + external_id
signature = HMAC-SHA256(message, partner_secret)

Where:

  • timestamp is the value from X-Timestamp header (Unix integer)
  • iccid is the ICCID from URL path
  • external_id is from request body

Example:

timestamp   = "1768478058"
iccid       = "8944422711108338982"
external_id = "topup-12345"
message     = "17684780588944422711108338982topup-12345"
signature   = hmac_sha256(message, partner_secret)

Important Notes

  • eSIM must have can_renew: true status (check via /services/esim/{iccid}/status)
  • external_id must be unique across all your orders
  • Balance is charged immediately when order is created
  • Returns the same order format as /orders endpoint
  • If sku_uuid is not provided, uses the same SKU as original eSIM purchase
Authorizations:
BearerAuth
path Parameters
iccid
required
string
Example: 8944422711108338982

eSIM ICCID to top-up

header Parameters
X-Timestamp
required
integer
Example: 1768478058

Unix timestamp (tolerance ±5 minutes)

X-Signature
required
string
Example: 13fbd7a9a501ea39aeec861a27158dfa00c491aa657798adac8ed9b2066a6fa2

HMAC-SHA256 signature (hex, lowercase)

Request Body schema: application/json
required
external_id
required
string

Your unique order identifier

sku_uuid
string <uuid>

SKU UUID for the data package to add. Optional - if not provided, uses the same SKU as the original eSIM purchase.

Responses

Request samples

Content type
application/json
{
  • "external_id": "topup-12345",
  • "sku_uuid": "029bc0dd-8562-7173-afd9-a5cc534fafb8"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "Top-up order created successfully",
  • "data": {
    }
}

Get eSIM status

Get current status, data balance, and details for an eSIM by ICCID.

Authorizations:
BearerAuth
path Parameters
iccid
required
string
Example: 8944422711108338982

eSIM ICCID (unique identifier)

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "data": {
    }
}

Webhooks

Outgoing webhooks sent to your server when order statuses change.

Setup

Configure your webhook URL in partner settings. The system will send HTTP POST requests to that URL on order events.

Signature Verification

Every webhook request includes two headers for authenticity verification:

  • X-Timestamp — Unix timestamp (seconds)
  • X-Signature — HMAC-SHA256 signature

Signature calculation:

message   = timestamp + event + idempotency_key
signature = HMAC-SHA256(message, partner_secret)

Where event and idempotency_key are top-level fields from the webhook JSON body. Timestamp tolerance is ±5 minutes.

Idempotency

Each webhook includes a unique idempotency_key (UUID). Use it to safely handle duplicate deliveries — the same event may be retried up to 3 times with exponential backoff (10s, 100s) if your server doesn't return HTTP 2xx.

Response Requirements

Your endpoint must return HTTP 2xx within 10 seconds. Non-2xx responses or timeouts are treated as failures and trigger retries.

Order status changed Webhook

Sent when an order reaches status: completed, failed or partially_completed.

Request Body schema: application/json
required
event
string
Value: "order.status_changed"
timestamp
string <date-time>

ISO 8601 timestamp of when the event occurred

idempotency_key
string <uuid>

Unique key for this delivery — use to safely deduplicate retries

object

Responses

Request samples

Content type
application/json
Example
{
  • "event": "order.status_changed",
  • "timestamp": "2026-01-15T12:58:23+00:00",
  • "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  • "data": {
    }
}

Order refunded Webhook

Sent when an order is refunded (fully or partially).

The order status does not change on refund — check the refund block. For fully refunded items delivery_data is revoked and no longer returned by the API; the codes must not be used or resold.

Request Body schema: application/json
required
event
string
Value: "order.refunded"
timestamp
string <date-time>

ISO 8601 timestamp of when the event occurred

idempotency_key
string <uuid>

Unique key for this delivery — use to safely deduplicate retries

object

Responses

Request samples

Content type
application/json
{
  • "event": "order.refunded",
  • "timestamp": "2026-01-20T10:15:00+00:00",
  • "idempotency_key": "880e8400-e29b-41d4-a716-446655440003",
  • "data": {
    }
}