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"
  }
}
HTTPcodeЧто делать
400invalid_parameterИсправьте поле из param
401invalid_credentialsПроверьте ключ
402insufficient_fundsПополните баланс
403insufficient_scopeИспользуйте ключ с нужным правом
403address_not_allowedКошелёк не подтверждён для аккаунта
409idempotency_conflictИспользуйте новый ключ идемпотентности
409duplicate_referenceЭтот reference уже использован
422no_capacityНет маршрута на эту сумму, повторите позже или смените сумму
422method_unavailableМетод или валюта не подключены
429rate_limitedПовторите после Retry-After
504outcome_unknownРезультат неизвестен. Повторите запрос с тем же Idempotency-Key

Платежи

POST/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, если поле заполнено.

GET/v1/payments/{id}

Возвращает актуальный статус платежа.

GET/v1/payments

Список от новых к старым. Параметры: limit до 100, cursor из next_cursor, status.

POST/v1/payments/{id}/cancel

Отменяет платёж, который клиент ещё не оплатил.

Выплаты

POST/v1/payouts
{
  "amount": "1000",
  "currency": "RUB",
  "method": "card",
  "bank": "sberbank",
  "reference": "payout-77",
  "destination": {
    "card_number": "2200000000000000",
    "holder_name": "Иван Иванов"
  }
}
methodПоля destination
cardcard_number, holder_name
sbpphone, holder_name, а банк в поле bank
upivpa, holder_name
ifscaccount_number, ifsc, holder_name
GET/v1/payouts/{id}
GET/v1/payouts

Баланс и вывод

GET/v1/balance
{
  "object": "balance",
  "livemode": true,
  "balances": [
    { "currency": "USDT", "available": "9924.1533", "reserved": "136.2357" }
  ]
}
POST/v1/settlements

Создаёт вывод USDT в сети TRC-20 на кошелёк, подтверждённый для аккаунта. Нужны право settlements и заголовок Idempotency-Key.

{ "amount": "100.00", "address": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8" }

Если пришёл код settlement_outcome_unknown, не создавайте новый вывод и обратитесь в поддержку.

GET/v1/settlements/{id}
GET/v1/settlements

Справочники

GET/v1/methods?currency=RUB&amount=1000&kind=payment

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

GET/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.

POST/v1/sandbox/orders/{id}
{ "status": "succeeded" }

Меняет статус тестового платежа, выплаты или вывода и отправляет вебхук.