API docs by Redocly

Partner S2S API (1.1.0)

Download OpenAPI specification:

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

Authentication

All requests require Bearer token:

Authorization: Bearer {your-s2s-token}

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

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

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