ScarabPay | API для мерчантов

Начало

Быстрый старт

Три шага до первого оплаченного счёта.

1
Создайте проект
Добавьте сайт или Telegram-бота в разделе «Приём платежей», подтвердите его, затем во вкладке «Разработчикам» создайте ключ.
2
Создайте счёт
Вызовите POST /invoices с суммой и номером заказа и отправьте клиента на checkout_url.
3
Обработайте вебхук
Проверьте подпись и выдайте заказ при получении invoice.paid.

curl -X POST https://scarabpay.com/pay/api/v1/invoices \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "20.00",
    "order_id": "order-1001",
    "description": "Gold plan",
    "customer_ref": "tg:55123",
    "return_url": "https://your-site.com/thanks"
  }'

$ch = curl_init('https://scarabpay.com/pay/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SCARABPAY_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => '20.00',
        'order_id' => 'order-1001',
        'description' => 'Gold plan',
    ]),
]);
$invoice = json_decode(curl_exec($ch), true)['data'];
header('Location: ' . $invoice['checkout_url']);

const res = await fetch("https://scarabpay.com/pay/api/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.SCARABPAY_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "20.00", order_id: "order-1001" }),
});
const { data } = await res.json();
// redirect the customer to data.checkout_url

import os, requests

r = requests.post(
    "https://scarabpay.com/pay/api/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['SCARABPAY_KEY']}"},
    json={"amount": "20.00", "order_id": "order-1001", "customer_ref": "tg:55123"},
    timeout=15,
)
invoice = r.json()["data"]
# Telegram bot: send invoice["checkout_url"] as a URL button

Авторизация

Передавайте секретный ключ в заголовке Authorization в каждом запросе. Ключ показывается один раз при создании — храните его только на сервере.

Authorization: Bearer sk_live_••••••••••••••••••••••••••••••••••••••••
Content-Type: application/json

sk_live_

Боевой ключ: реальные платежи, зачисляются на баланс ScarabPay.

sk_test_

Тестовый ключ: тестовые счета, ничего не списывается и не зачисляется.

Никогда не размещайте ключ в мобильном приложении, коде браузера или публичном репозитории. При утечке отзовите ключ во вкладке «Разработчикам» и создайте новый.

Песочница

Используйте ключ sk_test_, чтобы разрабатывать и тестировать без движения денег. Тестовые счета открывают ту же страницу оплаты с плашкой «тест».

Отметьте счёт оплаченным через POST /invoices/{id}/simulate — режим "full" или "partial".
Вебхуки отправляются как обычно, с "sandbox": true в теле.
Постоянные адреса доступны только в боевом режиме.

Соглашения

Запросы и ответы — JSON. Передавайте Content-Type: application/json.
Суммы — строки в USD с двумя знаками. Количество монет — строки без лишних нулей.
Время — ISO 8601 с часовым поясом.
Успешные ответы оборачивают объект в "data". Списки добавляют "meta" с page, pages и total; используйте ?page= и ?per_page= (до 100).
order_id делает повтор создания безопасным: тот же order_id вернёт тот же счёт (200), а не создаст новый (201).

Ошибки

Ошибки возвращают статус не 2xx и JSON со стабильным code, по которому можно ветвиться.

Статус	Код	Значение
401	`unauthorized`	Ключ отсутствует, неверен или отозван.
403	`forbidden`	Проект не активен (не подтверждён или приостановлен).
404	`not_found`	Счёт не найден в этом проекте и режиме.
409	`limit_reached`	Достигнут лимит вашего уровня.
409	`invoice_not_payable`	Счёт больше нельзя изменить (оплачен, истёк или отменён).
422	`validation_failed`	Неверное поле; подробности в `"fields"`.
422	`method_not_allowed`	Выбранный способ оплаты не включён для проекта.
429	`rate_limited`	Слишком много запросов. Подождите и повторите.
502	`provider_error`	Временная ошибка провайдера. Повторите с тем же `order_id`.
503	`coin_unavailable`	Монета временно недоступна; предложите другой способ.

422

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid request.",
    "fields": { "order_id": ["The order id field is required."] }
  }
}

Лимиты запросов

Каждый API-ключ может отправлять до 60 запросов в минуту. После множества неудачных попыток с одного IP этот IP блокируется на 10 минут.

При 429 подождите несколько секунд и повторите. Не опрашивайте счета в цикле — используйте вебхуки.

Ресурсы

Счета

Один счёт на заказ. Клиент выбирает монету на странице оплаты (или вы задаёте её заранее) и платит точную сумму. Неоплаченный счёт истекает через 30 минут.

Создать счёт

POST/invoices

Возвращает 201 с новым счётом или 200 с существующим, если order_id уже использовался.

Поле	Описание
`amount` string · обязательно	Сумма в USD, от 1 до 100000.
`order_id` string · обязательно	Ваш уникальный номер заказа. Буквы, цифры и _ - : ., до 100 символов.
`description` string · необязательно	Показывается клиенту на странице оплаты.
`customer_ref` string · необязательно	ID клиента у вас, например `tg:55123`.
`customer_email` string · необязательно	Email клиента для квитанций.
`return_url` url · необязательно	Куда ведёт кнопка «Вернуться в магазин» после оплаты.
`method` string · необязательно	Заранее выбрать монету и пропустить выбор, например `usdt_trc20`. См. `/currencies`.
`metadata` object · необязательно	До 20 пар ключ/значение для ваших нужд.

curl -X POST https://scarabpay.com/pay/api/v1/invoices \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "20.00",
    "order_id": "order-1001",
    "description": "Gold plan",
    "customer_ref": "tg:55123",
    "return_url": "https://your-site.com/thanks"
  }'

$ch = curl_init('https://scarabpay.com/pay/api/v1/invoices');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('SCARABPAY_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'amount' => '20.00',
        'order_id' => 'order-1001',
        'description' => 'Gold plan',
    ]),
]);
$invoice = json_decode(curl_exec($ch), true)['data'];
header('Location: ' . $invoice['checkout_url']);

const res = await fetch("https://scarabpay.com/pay/api/v1/invoices", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.SCARABPAY_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ amount: "20.00", order_id: "order-1001" }),
});
const { data } = await res.json();
// redirect the customer to data.checkout_url

import os, requests

r = requests.post(
    "https://scarabpay.com/pay/api/v1/invoices",
    headers={"Authorization": f"Bearer {os.environ['SCARABPAY_KEY']}"},
    json={"amount": "20.00", "order_id": "order-1001", "customer_ref": "tg:55123"},
    timeout=15,
)
invoice = r.json()["data"]
# Telegram bot: send invoice["checkout_url"] as a URL button

Ответ

{
  "data": {
    "id": "inv_8f2k1m0q7x3c9v5b4n6z",
    "order_id": "order-1001",
    "status": "pending",
    "amount": "20.00",
    "currency": "USD",
    "paid_amount": "0.00",
    "description": "Gold plan",
    "customer_ref": "tg:55123",
    "method": null,
    "coin": null,
    "network": null,
    "address": null,
    "coin_amount": null,
    "checkout_url": "https://scarabpay.com/pay/i/inv_8f2k1m0q7x3c9v5b4n6z",
    "sandbox": false,
    "expires_at": "2026-10-19T12:30:00+00:00",
    "paid_at": null,
    "created_at": "2026-10-19T12:00:00+00:00"
  }
}

Получить счёт

GET/invoices/{id|order_id}

Поиск по id счёта (inv_…) или по вашему order_id.

curl -X GET https://scarabpay.com/pay/api/v1/invoices/order-1001 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": { "id": "inv_8f2k…", "status": "paid", "paid_amount": "20.00", "…": "…" }
}

Список счетов

GET/invoices

Сначала новые. Фильтры ?status= и ?order_id=.

curl -X GET https://scarabpay.com/pay/api/v1/invoices?status=paid&per_page=25 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": [
    { "id": "inv_8f2k…", "status": "paid", "…": "…" }
  ],
  "meta": { "page": 1, "pages": 1, "total": 1 }
}

Отменить счёт

POST/invoices/{id}/cancel

Останавливает ожидающий счёт. Уже поступившие платежи обрабатываются.

curl -X POST https://scarabpay.com/pay/api/v1/invoices/inv_8f2k…/cancel \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": { "id": "inv_8f2k…", "status": "cancelled", "…": "…" }
}

Симулировать оплату

POST/invoices/{id}/simulatesandbox

Только песочница. "full" оплачивает счёт, "partial" делает его недоплаченным.

Поле	Описание
`mode` string · необязательно	`"full"` (по умолчанию) или `"partial"`.

curl -X POST https://scarabpay.com/pay/api/v1/invoices/inv_8f2k…/simulate \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "full"}'

Ответ

{
  "data": { "id": "inv_8f2k…", "status": "paid", "sandbox": true, "…": "…" }
}

Постоянные адреса

Постоянный адрес пополнения для каждого клиента — удобно для пополнения баланса в ботах. Каждый депозит создаёт платёж и вебхук deposit.received.

Получить или создать адрес

POST/static-addresseslive

Возвращает 201 для нового адреса и 200, если у клиента уже есть адрес для этого способа.

Поле	Описание
`customer_ref` string · обязательно	ID клиента. Буквы, цифры и _ - : . @.
`method` string · обязательно	Монета и сеть, например `usdt_trc20`.

curl -X POST https://scarabpay.com/pay/api/v1/static-addresses \
  -H "Authorization: Bearer $SCARABPAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_ref": "tg:55123", "method": "usdt_trc20"}'

Ответ

{
  "data": {
    "customer_ref": "tg:55123",
    "network": "TRX",
    "address": "TQ5n3mGq…",
    "memo": null,
    "total_received": "0.00",
    "last_deposit_at": null,
    "created_at": "2026-10-19T12:00:00+00:00"
  }
}

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

GET/static-addresses

Активные адреса, фильтр ?customer_ref=.

curl -X GET https://scarabpay.com/pay/api/v1/static-addresses?customer_ref=tg:55123 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": [
    { "customer_ref": "tg:55123", "network": "TRX", "address": "TQ5n3mGq…", "…": "…" }
  ],
  "meta": { "page": 1, "pages": 1, "total": 1 }
}

Платежи

Список платежей

GET/payments

Все платежи в сети с комиссией и суммой зачисления. Фильтр ?customer_ref=.

curl -X GET https://scarabpay.com/pay/api/v1/payments?customer_ref=tg:55123 \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": [
    { "id": "pay_42", "invoice_id": "inv_8f2k…", "order_id": "order-1001", "customer_ref": "tg:55123", "coin": "USDT", "network": "TRX", "coin_amount": "20", "amount": "20.00", "fee": "0.20", "net": "19.80", "tx_hash": "a1b2…", "status": "credited", "created_at": "2026-10-19T12:04:10+00:00" }
  ],
  "meta": { "page": 1, "pages": 1, "total": 1 }
}

Аккаунт

Информация о проекте

GET/me

Проект ключа, режим и комиссия.

curl -X GET https://scarabpay.com/pay/api/v1/me \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": {
    "project": "mp_…",
    "name": "My store",
    "type": "website",
    "target": "https://your-site.com",
    "status": "active",
    "environment": "live",
    "fee_percent": 1
  }
}

Доступные способы

GET/currencies

Монеты и сети, которые можно передать в "method".

curl -X GET https://scarabpay.com/pay/api/v1/currencies \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": [
    { "method": "usdt_trc20", "coin": "USDT", "network": "TRX", "label": "USDT (TRC20)" },
    { "method": "btc", "coin": "BTC", "network": "BTC", "label": "Bitcoin" }
  ]
}

Баланс

GET/balance

Доступный баланс ScarabPay в USD.

curl -X GET https://scarabpay.com/pay/api/v1/balance \
  -H "Authorization: Bearer $SCARABPAY_KEY"

Ответ

{
  "data": { "currency": "USD", "available": "125.40" }
}

Вебхуки

Доставка

Укажите URL вебхука и скопируйте секрет подписи во вкладке «Разработчикам». Мы отправляем JSON-событие POST-запросом при каждом изменении. Ответьте любым 2xx в течение 10 секунд.

Заголовки	Описание
`X-ScarabPay-Event`	Название события.
`X-ScarabPay-Delivery`	Уникальный id события. Используйте для отсева дублей.
`X-ScarabPay-Signature`	Метка времени и подпись HMAC-SHA256. `t=<unix>,v1=<hex>`

Запрос

POST /scarabpay-webhook HTTP/1.1
Host: your-site.com
Content-Type: application/json
X-ScarabPay-Event: invoice.paid
X-ScarabPay-Delivery: evt_3b7d0f1c9e5a2b8d4f6a1c0e
X-ScarabPay-Signature: t=1760875450,v1=5f8a…c21e

{
  "id": "evt_3b7d0f1c9e5a2b8d4f6a1c0e",
  "event": "invoice.paid",
  "project": "mp_…",
  "sandbox": false,
  "created_at": "2026-10-19T12:04:10+00:00",
  "data": { "id": "inv_8f2k…", "order_id": "order-1001", "status": "paid", "paid_amount": "20.00", "…": "…" }
}

События

Событие	Когда
`invoice.paid`	Счёт полностью оплачен. Выдайте заказ.
`invoice.underpaid`	Клиент заплатил меньше суммы.
`invoice.expired`	Счёт истёк без оплаты.
`invoice.late`	Платёж поступил после истечения счёта.
`invoice.updated`	Другое обновление платежа по счёту (например, платёж на проверке).
`deposit.received`	Поступил депозит на постоянный адрес.
`address.idle`	На постоянный адрес давно не было депозитов.
`address.unbound`	Постоянный адрес отвязан от клиента.
`payout.sent`	Выплата с вашего баланса отправлена.
`project.suspended`	Ваш проект приостановлен.
`ping`	Тестовое событие с кнопки «Отправить тест».

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

Вычислите HMAC-SHA256 от "t.body" секретом вебхука и сравните с v1 за постоянное время. Используйте сырое тело как есть и отклоняйте метки старше 5 минут.

$secret = getenv('SCARABPAY_WEBHOOK_SECRET');
$body = file_get_contents('php://input');           // raw body
parse_str(str_replace(',', '&', $_SERVER['HTTP_X_SCARABPAY_SIGNATURE'] ?? ''), $sig);

$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, $secret);
if (abs(time() - (int) ($sig['t'] ?? 0)) > 300 || ! hash_equals($expected, $sig['v1'] ?? '')) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
if ($event['event'] === 'invoice.paid') {
    // deliver order $event['data']['order_id'] (once per X-ScarabPay-Delivery)
}
http_response_code(200);

import crypto from "node:crypto";
import express from "express";

const app = express();
app.post("/scarabpay-webhook", express.raw({ type: "application/json" }), (req, res) => {
  const sig = Object.fromEntries((req.get("X-ScarabPay-Signature") || "").split(",").map(p => p.split("=")));
  const expected = crypto.createHmac("sha256", process.env.SCARABPAY_WEBHOOK_SECRET)
    .update(`${sig.t}.`).update(req.body).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(sig.t)) < 300;
  const ok = fresh && sig.v1?.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig.v1));
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  if (event.event === "invoice.paid") { /* deliver event.data.order_id */ }
  res.sendStatus(200);
});

import hmac, hashlib, os, time

def verify(sig_header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in sig_header.split(",") if "=" in p)
    secret = os.environ["SCARABPAY_WEBHOOK_SECRET"].encode()
    expected = hmac.new(secret, parts.get("t", "").encode() + b"." + body, hashlib.sha256).hexdigest()
    fresh = abs(time.time() - int(parts.get("t", 0))) < 300
    return fresh and hmac.compare_digest(expected, parts.get("v1", ""))

# FastAPI / aiohttp: pass request.headers["X-ScarabPay-Signature"] and the raw body bytes

Повторы

Если сервер не ответил 2xx, мы повторяем до 8 раз: через 1 мин, 5 мин, 15 мин, 1 ч, 3 ч, 6 ч и 12 ч. Любое событие можно переотправить из журнала доставок.

#1+0
#2+1m
#3+5m
#4+15m
#5+1h
#6+3h
#7+6h
#8+12h

Обработчик должен быть идемпотентным: одно событие может прийти несколько раз. Сохраняйте X-ScarabPay-Delivery и пропускайте повторы.

Справочник

Объекты

Счёт

`id`	ID счёта, начинается с inv_.
`order_id`	Ваш уникальный номер заказа. Буквы, цифры и _ - : ., до 100 символов.
`status`	См. статусы счёта.
`amount · paid_amount`	Получено в USD на данный момент.
`method · coin · network`	Выбранная монета и сеть, null до выбора.
`address · coin_amount`	Адрес и точное количество монет к оплате.
`checkout_url`	Страница оплаты. Отправьте клиента сюда.
`sandbox`	true для тестовых счетов.
`expires_at · paid_at · created_at`	Время в ISO 8601.

Платёж

`id`	ID платежа, начинается с pay_.
`invoice_id · order_id · customer_ref`	ID клиента у вас, например `tg:55123`.
`coin · network · coin_amount`	Выбранная монета и сеть, null до выбора.
`amount · fee · net`	Сумма в USD, наша комиссия и зачисление вам.
`tx_hash`	Хеш транзакции в блокчейне.
`status`	credited, held, review или sandbox.

Постоянный адрес

`customer_ref`	ID клиента у вас, например `tg:55123`.
`network · address`	Адрес и точное количество монет к оплате.
`memo`	Memo / тег, если сеть его требует (например TON).
`total_received`	Всего получено на адрес в USD.
`last_deposit_at · created_at`	Время в ISO 8601.

Статусы счёта

pending

Ожидает оплаты.

paid

Полностью оплачен и зачислен. Выдайте заказ.

underpaid

Поступило меньше суммы. Полученная часть зачислена.

expired

Время вышло без оплаты.

late

Оплачен после истечения. Платёж задерживается для проверки до зачисления.

cancelled

Отменён вами.

Принимайте криптоплатежи из своего кода

Быстрый старт

Авторизация

Песочница

Соглашения

Ошибки

Лимиты запросов

Счета

Создать счёт

Получить счёт

Список счетов

Отменить счёт

Симулировать оплату

Постоянные адреса

Получить или создать адрес

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

Платежи

Список платежей

Аккаунт

Информация о проекте

Доступные способы

Баланс

Доставка

События

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

Повторы

Объекты

Статусы счёта

Нужна помощь с интеграцией?