API phantomflow
REST API для приёма платежей, выплат и вывода баланса в USDT. Запросы и ответы передаются в JSON.
https://api.phantomflow.org/v1
Авторизация
Создайте ключ в кабинете и передавайте его в заголовке. Ключ показывается один раз. Храните его на сервере и не отправляйте в браузер.
Authorization: Bearer pf_live_•••• # боевой режим
Authorization: Bearer pf_test_•••• # песочница
| Право ключа | Что разрешает |
|---|---|
payments | Создание и отмена платежей |
payouts | Создание выплат |
settlements | Вывод баланса. Для боевого ключа нужно подтвердить пароль |
Общие правила
Суммы
Передавайте сумму строкой, например "1500.50". Допускается до 4 знаков после точки.
Идемпотентность
Заголовок Idempotency-Key защищает от дублей. Повтор с тем же ключом в течение 24 часов вернёт исходный ответ и заголовок Idempotent-Replayed: true. Тот же ключ с другими параметрами вернёт 409. Для POST /v1/settlements заголовок обязателен.
Лимиты
До 100 запросов в секунду на аккаунт. При превышении придёт 429 и заголовок Retry-After.
Статусы
| Статус | Значение |
|---|---|
pending | Ожидает оплаты |
processing | Оплата или выплата проверяется |
succeeded | Операция выполнена |
failed | Операция не прошла |
expired | Время на оплату истекло |
canceled | Операция отменена |
Финальный статус в редких случаях может измениться после разбирательства. Об этом придёт новый вебхук.
Ошибки
{
"error": {
"type": "invalid_request",
"code": "invalid_parameter",
"message": "Must be an uppercase currency code.",
"param": "currency"
}
}
| HTTP | code | Что делать |
|---|---|---|
| 400 | invalid_parameter | Исправьте поле из param |
| 401 | invalid_credentials | Проверьте ключ |
| 402 | insufficient_funds | Пополните баланс |
| 403 | insufficient_scope | Используйте ключ с нужным правом |
| 403 | address_not_allowed | Кошелёк не подтверждён для аккаунта |
| 409 | idempotency_conflict | Используйте новый ключ идемпотентности |
| 409 | duplicate_reference | Этот reference уже использован |
| 422 | no_capacity | Нет маршрута на эту сумму, повторите позже или смените сумму |
| 422 | method_unavailable | Метод или валюта не подключены |
| 429 | rate_limited | Повторите после Retry-After |
| 504 | outcome_unknown | Результат неизвестен. Повторите запрос с тем же Idempotency-Key |
Платежи
/v1/paymentsСоздаёт платёж и возвращает реквизиты и ссылку на страницу оплаты.
curl https://api.phantomflow.org/v1/payments \
-H "Authorization: Bearer $PF_KEY" \
-H "Idempotency-Key: order-4821" \
-H "Content-Type: application/json" \
-d '{
"amount": "12500",
"currency": "RUB",
"method": "sbp",
"reference": "order-4821",
"return_url": "https://shop.example/thanks",
"customer": { "id": "user_17", "ip": "198.51.100.7" }
}'
| Поле | Описание |
|---|---|
amount* | Сумма |
currency* | Валюта, например RUB |
method* | sbp, card, account, qr, mobile или upi |
bank | Код банка из /v1/banks |
geo | Код страны реквизита |
reference | Ваш уникальный номер заказа |
return_url | Куда вернуть клиента |
callback_url | Адрес вебхука только для этого платежа |
ttl_seconds | Время жизни, от 60 до 604800 секунд |
customer | Данные клиента для антифрода |
{
"id": "pay_8hq2xvd91kf3",
"object": "payment",
"livemode": true,
"status": "pending",
"amount": "12500",
"final_amount": "12500.0000",
"currency": "RUB",
"method": "sbp",
"bank": "sberbank",
"reference": "order-4821",
"checkout_url": "https://pay.phantomflow.org/pay/pay_8hq2xvd91kf3",
"payment_details": {
"type": "phone",
"phone": "+79990001122",
"bank_name": "Сбербанк",
"holder_name": "Иван И."
},
"failure_code": null,
"expires_at": "2026-11-18T12:30:00Z",
"created_at": "2026-11-18T12:00:00Z",
"updated_at": "2026-11-18T12:00:00Z"
}
Сумма к оплате может отличаться от запрошенной. Показывайте клиенту final_amount, если поле заполнено.
/v1/payments/{id}Возвращает актуальный статус платежа.
/v1/paymentsСписок от новых к старым. Параметры: limit до 100, cursor из next_cursor, status.
/v1/payments/{id}/cancelОтменяет платёж, который клиент ещё не оплатил.
Выплаты
/v1/payouts{
"amount": "1000",
"currency": "RUB",
"method": "card",
"bank": "sberbank",
"reference": "payout-77",
"destination": {
"card_number": "2200000000000000",
"holder_name": "Иван Иванов"
}
}
| method | Поля destination |
|---|---|
card | card_number, holder_name |
sbp | phone, holder_name, а банк в поле bank |
upi | vpa, holder_name |
ifsc | account_number, ifsc, holder_name |
/v1/payouts/{id}/v1/payoutsБаланс и вывод
/v1/balance{
"object": "balance",
"livemode": true,
"balances": [
{ "currency": "USDT", "available": "9924.1533", "reserved": "136.2357" }
]
}
/v1/settlementsСоздаёт вывод USDT в сети TRC-20 на кошелёк, подтверждённый для аккаунта. Нужны право settlements и заголовок Idempotency-Key.
{ "amount": "100.00", "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8" }
Если пришёл код settlement_outcome_unknown, не создавайте новый вывод и обратитесь в поддержку.
/v1/settlements/{id}/v1/settlementsСправочники
/v1/methods?currency=RUB&amount=1000&kind=paymentМетоды для суммы и валюты. Ответ подсказывает варианты, но не резервирует реквизит.
/v1/banks?country=RUSКоды банков для поля bank.
Вебхуки
Адрес настраивается в кабинете. Там же один раз показывается секрет подписи.
| Событие | Когда приходит |
|---|---|
payment.succeeded | Платёж зачислен |
payment.failed | Платёж не прошёл |
payment.expired | Время на оплату истекло |
payment.canceled | Платёж отменён |
payout.succeeded | Выплата выполнена |
payout.failed, payout.expired, payout.canceled | Выплата не выполнена |
settlement.completed | Вывод в USDT выполнен |
settlement.failed | Вывод отменён или не прошёл |
{
"id": "evt_k2m9x4q7hd1c",
"type": "payment.succeeded",
"created_at": "2026-11-18T12:04:00Z",
"livemode": true,
"data": { "id": "pay_8hq2xvd91kf3", "object": "payment", "status": "succeeded" }
}
Проверка подписи
Заголовок PF-Signature имеет вид t=1762441200,v1=…. Посчитайте HMAC-SHA256 от строки t.тело и сравните с v1. Считайте подпись от исходных байтов тела.
import crypto from "node:crypto";
function verify(rawBody, header, secret) {
const [t, v1] = header.split(",").map((part) => part.split("=")[1]);
const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const fresh = Math.abs(Date.now() / 1000 - Number(t)) < 300;
return fresh && v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}
Повторы
Ответьте кодом 2xx за 10 секунд. Иначе повторим через 1 минуту, 5 минут, 30 минут, 2 часа и 12 часов. Событие может прийти повторно, поэтому учитывайте заголовок PF-Event-Id.
Песочница
С ключом pf_test_ деньги не двигаются. Сумма с окончанием .01 вернёт no_capacity.
/v1/sandbox/orders/{id}{ "status": "succeeded" }
Меняет статус тестового платежа, выплаты или вывода и отправляет вебхук.