Bearer token — recommended for both versions

Bearer-токен — рекомендуется для обеих версий

API credentials travel in the Authorization header, never in the URL. The separator is the first dot — the secret itself may contain dots. Works with REST v2 and with the legacy endpoint; with Bearer the settings parameter becomes optional and lang / currency are passed as ordinary query parameters.

API-креденшелы передаются в заголовке Authorization, а не в URL. Разделитель — первая точка: сам секрет может содержать точки. Работает и для REST v2, и для legacy-эндпоинта; при Bearer параметр settings становится необязательным, а lang / currency передаются обычными query-параметрами.

curl https://api.pay.net.az/api/v2/products \
  -H "Authorization: Bearer <api_key>.<api_secret>"

Credentials are issued by a KeyForge administrator and support an IP whitelist and an expiry date. The secret is shown once; if lost, it can only be rotated.

Креденшелы выдаёт администратор KeyForge; поддерживаются IP-whitelist и срок действия. Секрет показывается один раз, при утере его можно только заменить.

Legacy API v1 — query credentials

Legacy API v1 — креденшелы в query

Still supported for backward compatibility: a settings query parameter containing a JSON object with your partner login and password (validated with bcrypt). Be aware that such URLs end up in web server logs, proxy history and Referer headers — prefer the Bearer header above.

По-прежнему поддерживается для обратной совместимости: query-параметр settings с JSON-объектом, содержащим login и password партнёра (проверяются через bcrypt). Учтите, что такие URL оседают в логах веб-сервера, в истории прокси и в заголовке Referer — предпочтительнее Bearer выше.

GET /public/json/web.service.2024.php
  ?action=1
  &settings={"login":"your_login","password":"your_password","lang":"en"}

REST API v2

Uses JWT Bearer tokens. Obtain a token via the login endpoint, then include it in every request header.

Используются JWT Bearer токены. Получите токен через эндпоинт авторизации, затем передавайте его в заголовке запроса.

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Legacy API v1

Returns a JSON object with code and message. Code "0" means success. Any other code indicates an error.

Возвращает JSON с полями code и message. Код "0" — успех. Любой другой код — ошибка.

{
  "code": "0-3",
  "message": "PARTNER_INACTIVE"
}

Common Error Codes (prefix 0-X)

Общие коды ошибок (префикс 0-X)

REST API v2

Uses standard HTTP status codes with a JSON body containing success boolean and error message.

Использует стандартные HTTP коды с JSON-ответом, содержащим success (boolean) и error (сообщение).

{
  "success": false,
  "error": "Unauthorized: Invalid or expired token"
}

Request Format

Формат запроса

GET /public/json/web.service.2024.php
    ?action={1-7}
    &settings={"login":"...","password":"...","lang":"en","currency":"AZN"}
    &data={url_encoded_json}

GET  Action 1 — Get Products Получить продукты

Returns the catalog of available products accessible to the partner. Products are filtered by partner's access permissions.

Возвращает каталог доступных продуктов для партнёра. Продукты фильтруются по правам доступа партнёра.

curl -G "https://admin.pay.net.az/public/json/web.service.2024.php" \
  --data-urlencode "action=1" \
  --data-urlencode 'settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD","lang":"en"}' \
  --data-urlencode "lang=en"

{
  "code": "0",
  "message": "SUCCESS",
  "data": [
    {
      "productId": "42",
      "productName": "Xbox Game Pass Ultimate 1 Month",
      "imageUrl": "https://admin.pay.net.az/uploads/products/xbox-gp.png",
      "thumbnailUrl": "https://admin.pay.net.az/uploads/products/thumb/xbox-gp.png"
    },
    {
      "productId": "58",
      "productName": "Steam Wallet $50",
      "imageUrl": "https://admin.pay.net.az/uploads/products/steam-50.png",
      "thumbnailUrl": null
    }
  ]
}

GET  Action 2 — Get Packages Получить пакеты

Returns available packages for a specific product, with prices in the requested currency.

Возвращает доступные пакеты для конкретного продукта с ценами в запрошенной валюте.

curl -G "https://admin.pay.net.az/public/json/web.service.2024.php" \
  --data-urlencode "action=2" \
  --data-urlencode 'settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD","lang":"en"}' \
  --data-urlencode 'data={"product":"42"}' \
  --data-urlencode "currency=AZN"

{
  "code": "0",
  "message": "SUCCESS",
  "data": [
    {
      "packageId": "101",
      "packageName": "Xbox Game Pass Ultimate 1 Month (TR)",
      "packagePrice": "25.50",
      "currency": "AZN"
    }
  ]
}

GET  Action 3 — Reserve Key Зарезервировать ключ

Reserves a digital key from a package. The key is locked for 10 minutes. Must be confirmed (Action 4) or cancelled (Action 5) within this time.

Резервирует цифровой ключ из пакета. Ключ блокируется на 10 минут. Необходимо подтвердить (Action 4) или отменить (Action 5) в течение этого времени.

curl -G "https://admin.pay.net.az/public/json/web.service.2024.php" \
  --data-urlencode "action=3" \
  --data-urlencode 'settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD","lang":"en"}' \
  --data-urlencode 'data={"package":"101"}' \
  --data-urlencode "currency=AZN"

{
  "code": "0",
  "message": "SUCCESS",
  "data": {
    "keyId": "8847",
    "keyText": "XXXX-YYYY-ZZZZ-WWWW",
    "serialNumber": "SN-12345",
    "price": "25.50",
    "currency": "AZN"
  }
}

GET  Action 4 — Confirm Sale Подтвердить продажу

Confirms the purchase of a previously reserved key. Creates an order record and marks the key as sold. The package auto-deactivates if this was the last key.

Подтверждает покупку зарезервированного ключа. Создаёт запись заказа и помечает ключ как проданный. Пакет автоматически деактивируется если это был последний ключ.

curl -G "https://admin.pay.net.az/public/json/web.service.2024.php" \
  --data-urlencode "action=4" \
  --data-urlencode 'settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD","lang":"en"}' \
  --data-urlencode 'data={"key":"8847","order":"PAY-2026-001","currency":"AZN"}'

{
  "code": "0",
  "message": "SUCCESS"
}

GET  Action 5 — Cancel Reservation Отменить резервацию

Cancels a previously reserved key, returning it to the available pool.

Отменяет резервацию ключа, возвращая его в доступные.

curl -G "https://admin.pay.net.az/public/json/web.service.2024.php" \
  --data-urlencode "action=5" \
  --data-urlencode 'settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD","lang":"en"}' \
  --data-urlencode 'data={"key":"8847"}'

{
  "code": "0",
  "message": "SUCCESS"
}

GET  Action 6 — Direct Purchase (One-Step) Прямая покупка (один шаг)

Combines reservation and confirmation in a single call. Optionally sends the key to the customer via email with activation instructions. Auto-deactivates the package when the last key is sold.

Объединяет резервацию и подтверждение в одном вызове. Опционально отправляет ключ клиенту по email с инструкцией активации. Автоматически деактивирует пакет при продаже последнего ключа.

curl -G "https://admin.pay.net.az/public/json/web.service.2024.php" \
  --data-urlencode "action=6" \
  --data-urlencode 'settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD","lang":"en"}' \
  --data-urlencode 'data={"package":"101","order":"PAY-2026-002","email":"customer@example.com","lang":"en"}' \
  --data-urlencode "currency=AZN"

{
  "code": "0",
  "message": "SUCCESS",
  "data": {
    "keyId": "8848",
    "keyText": "AAAA-BBBB-CCCC-DDDD",
    "serialNumber": "SN-67890"
  }
}

GET  Action 7 — Get Order Status Статус заказа

Look up the current status of a previously-created order by your own client_order_id. Use this to detect refunds / cancellations that happened on the KeyForge side after the original sale.

Получение актуального статуса ранее созданного заказа по вашему client_order_id. Используйте, чтобы узнать про возвраты / отмены, выполненные на стороне KeyForge уже после выдачи ключа.

curl -G "https://admin.pay.net.az/public/json/web.service.2024.php" \
  --data-urlencode "action=7" \
  --data-urlencode 'settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD"}' \
  --data-urlencode 'data={"order":"PAY-2026-002"}'

{
  "code": "0",
  "message": "SUCCESS",
  "data": {
    "orderId": "ORD-2026-45031507",
    "clientOrderId": "PAY-2026-002",
    "status": "confirmed",
    "amount": "7.00",
    "currency": "AZN",
    "keyId": "7251",
    "keyText": "DBVC-26RE-2X1P-46B3",
    "serialNumber": "SN-67890",
    "createdAt": "2026-04-23T11:50:31.525Z",
    "updatedAt": "2026-04-23T11:50:31.525Z"
  }
}

{
  "code": "0",
  "message": "SUCCESS",
  "data": {
    "orderId": "ORD-2026-45031507",
    "clientOrderId": "PAY-2026-002",
    "status": "cancelled",
    "amount": "7.00",
    "currency": "AZN",
    "updatedAt": "2026-04-23T12:10:05.118Z"
  }
}

Standard Flow (Two-Step)

Стандартный поток (два шага)

For payment terminals that need to show the price before charging the customer.

Для платёжных терминалов, которым нужно показать цену до списания средств.

Express Flow (One-Step)

Экспресс-поток (один шаг)

For online stores where payment is already completed.

Для интернет-магазинов, где оплата уже произведена.

Why v2

Зачем v2

Legacy API passes login and password as query parameters. Such URLs end up in web server logs, proxy history and Referer headers. v2 removes that: the secret travels in the Authorization header only. Everything else — prices, reservations, idempotency — works exactly as in v1.

Legacy API передаёт login и password в query-строке. Такие URL оседают в логах веб-сервера, в истории прокси и в заголовке Referer. v2 это убирает: секрет уходит только в заголовке Authorization. Всё остальное — цены, брони, идемпотентность — работает ровно так же, как в v1.

Response Format

Формат ответа

{
  "data": [ ... ],
  "pagination": {
    "total": 148,
    "limit": 50,
    "offset": 0
  }
}

{
  "error": {
    "code": "OUT_OF_STOCK",
    "message": "There is no any free key for this package"
  }
}

Always branch on error.code, never on message — messages may be reworded, codes are part of the contract.

Ветвитесь по error.code, а не по message: формулировки могут меняться, коды — часть контракта.

Authentication Аутентификация

Every request carries API credentials in the Authorization header. The separator is the first dot — the secret itself may contain dots.

Каждый запрос несёт API-креденшелы в заголовке Authorization. Разделитель — первая точка: сам секрет может содержать точки.

curl https://api.pay.net.az/api/v2/products \
  -H "Authorization: Bearer 3f9a…c1.7d2e…b4"

Credentials are issued by a KeyForge administrator. The secret is shown once; if lost, it can only be rotated. Each credential supports an IP whitelist and an expiry date.

Креденшелы выдаёт администратор KeyForge. Секрет показывается один раз; при утере его можно только заменить (ротация). У каждой учётки поддерживаются IP-whitelist и срок действия.

Authentication errors

Ошибки аутентификации

Account Аккаунт

{
  "partner": {
    "id": 5,
    "login": "paynet",
    "name": "PayNet Processing",
    "tier": "gold",
    "sandbox": false
  },
  "currency": {
    "mode": "MULTI_CURRENCY",
    "default": "AZN",
    "allowed": ["AZN", "USD"],
    "active": "AZN"
  },
  "balance": {
    "mode": "postpaid",
    "amount": -120.50,
    "creditLimit": 5000,
    "currency": "AZN",
    "available": 4879.50
  }
}

Catalog Каталог

{
  "data": [
    {
      "id": 12,
      "name": "PlayStation Plus",
      "names": {
        "az": "PlayStation Plus",
        "ru": "PlayStation Plus",
        "en": "PlayStation Plus"
      },
      "imageUrl": "https://admin.pay.net.az/uploads/products/ps.jpg"
    }
  ]
}

{
  "data": [
    {
      "id": 104,
      "name": "PS Plus 3 месяца",
      "names": { "az": "…", "ru": "…", "en": "…" },
      "price": 25.00,
      "currency": "AZN",
      "available": 37
    }
  ]
}

Reservations Брони

{
  "packageId": 104,
  "orderId": "PAY-100500"
}

{
  "reservation": {
    "keyId": 50231,
    "keyText": "XXXX-YYYY-ZZZZ",
    "price": 25.00,
    "currency": "AZN",
    "expiresAt": "2026-07-31T15:42:00.000Z",
    "clientOrderId": "PAY-100500"
  }
}

{ "orderId": "PAY-100500" }

{
  "order": {
    "orderId": "PAY-100500",
    "clientOrderId": "PAY-100500",
    "status": "confirmed",
    "keyId": 50231,
    "keyText": "XXXX-YYYY-ZZZZ",
    "amount": 25.00,
    "currency": "AZN"
  }
}

Orders Заказы

{
  "packageId": 104,
  "orderId": "PAY-100501",
  "customerEmail": "buyer@example.com"
}

{
  "order": {
    "orderId": "ORD-2026-45120033",
    "clientOrderId": "PAY-100501",
    "status": "confirmed",
    "keyId": 50232,
    "keyText": "AAAA-BBBB-CCCC",
    "amount": 25.00,
    "currency": "AZN"
  }
}

Error codes Коды ошибок

Sandbox Песочница

Ask an administrator to switch your account into sandbox mode. Everything behaves as in production — same endpoints, same error codes, same idempotency — but keys are synthetic (SANDBOX-…), stock is untouched and nothing reaches revenue. Responses carry "sandbox": true.

Попросите администратора перевести вашу учётку в режим песочницы. Всё ведёт себя как в бою — те же эндпоинты, те же коды ошибок, та же идемпотентность, — но ключи синтетические (SANDBOX-…), склад не затрагивается и в выручку ничего не попадает. В ответах присутствует "sandbox": true.

Triggering failures on purpose

Управляемые отказы

You cannot make a live catalog run out of stock, yet error handling must be tested. Prefix your order number to force an outcome:

Заставить живой каталог «закончиться» невозможно, а обработку отказов проверять надо. Префикс в номере заказа задаёт исход:

The prefix only triggers at the start of the number, so a legitimate order such as ORDER-FAIL_SYSTEM-1 is unaffected.

Префикс срабатывает только в начале номера, поэтому легитимный заказ вида ORDER-FAIL_SYSTEM-1 ничего не ломает.

Migrating from Legacy v1 Переход с Legacy v1

If you cannot move off v1 yet, you can still drop credentials from the URL today: the legacy endpoint accepts the same Authorization: Bearer header, and then settings becomes optional.

Если перейти на v2 пока нельзя, убрать секреты из URL можно уже сегодня: legacy-эндпоинт принимает тот же заголовок Authorization: Bearer, и параметр settings становится необязательным.

When you include the email parameter in Action 6, KeyForge automatically sends a beautifully formatted email to the customer containing:

Когда вы включаете параметр email в Action 6, KeyForge автоматически отправляет красиво оформленное письмо клиенту, содержащее:

• Product name and image
• Название и изображение продукта
• Digital key (PIN code)
• Цифровой ключ (PIN-код)
• Serial number (if applicable)
• Серийный номер (если есть)
• Product-specific activation instructions
• Инструкции по активации для конкретного продукта
• Partner branding (logo, support email)
• Брендинг партнёра (логотип, email поддержки)

// Send key + email to customer in Russian
GET /public/json/web.service.2024.php
  ?action=6
  &settings={"login":"YOUR_LOGIN","password":"YOUR_PASSWORD","lang":"ru"}
  &data={"package":"101","order":"ORD-001","email":"user@mail.com","lang":"ru"}

Order webhooks

Вебхуки по заказам

An administrator registers your HTTPS endpoint and issues a signing secret. KeyForge then pushes events to you. This is the only way to learn about a refund or an expired reservation without calling action=7 in a loop.

Администратор регистрирует ваш HTTPS-эндпоинт и выдаёт секрет подписи. После этого KeyForge сам присылает события. Это единственный способ узнать о возврате или истёкшей брони, не опрашивая action=7 по кругу.

{
  "event_id": "8f14e45f-ea0f-4b2c-9c1a-1d2f3a4b5c6d",
  "event_type": "order.refunded",
  "created_at": "2026-07-31T13:45:12.345Z",
  "data": { "order_id": "PAY-100500", "amount": "25.00", "currency": "AZN" }
}

Verifying the signature

Проверка подписи

Header X-KeyForge-Signature: t=<timestamp>,v1=<hmac>. The HMAC-SHA256 is computed over the string "<timestamp>.<raw body>" using your secret. Compute it over the raw body, before JSON parsing: re-serialising changes the bytes and the signature will not match. Reject requests whose timestamp differs from now by more than a few minutes — that is what protects you from replay.

Заголовок X-KeyForge-Signature: t=<timestamp>,v1=<hmac>. HMAC-SHA256 считается от строки "<timestamp>.<сырое тело>" на вашем секрете. Считайте от СЫРОГО тела, до разбора JSON: повторная сериализация меняет байты, и подпись не сойдётся. Отвергайте запросы, у которых timestamp расходится с текущим временем больше чем на несколько минут — именно это защищает от переигрывания перехваченного запроса.

const crypto = require('crypto');

function verify(rawBody, header, secret, tolerance = 300) {
  const p = Object.fromEntries(header.split(',').map(x => x.split('=')));
  const ts = Number(p.t);
  if (!Number.isFinite(ts) || Math.abs(Date.now()/1000 - ts) > tolerance) return false;

  const expected = crypto.createHmac('sha256', secret)
    .update(`${ts}.${rawBody}`).digest('hex');

  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));
}

Delivery and retries

Доставка и повторы

Any 2xx counts as success. On any other response or a network error the delivery is retried: 1 min → 5 min → 15 min → 1 h → 6 h → 24 h. Delivery is at-least-once — the same event may arrive twice, so deduplicate by event_id. Answer 200 before heavy processing: if you hold the response longer than 10 seconds we treat it as a failure and retry.

Успех — любой 2xx. При другом ответе или сетевой ошибке доставка повторяется: 1 мин → 5 мин → 15 мин → 1 ч → 6 ч → 24 ч. Доставка at-least-once — одно и то же событие может прийти дважды, дедуплицируйте по event_id. Отвечайте 200 до тяжёлой обработки: если держите ответ дольше 10 секунд, мы считаем доставку неудачной и повторяем её.

Email delivery events

События доставки email

KeyForge tracks email delivery status internally. The following events are surfaced in the admin panel (Communications → Delivery log):

KeyForge отслеживает статус доставки email внутренне. Следующие события доступны в админ-панели (Коммуникации → Журнал отправок):