FlipPay API

Принимайте платежи (СБП, карты, криптовалюта, международные) через единый REST API. Плательщик оплачивает на нашей брендированной странице — вам нужно лишь создать платёж и обработать уведомление о статусе.

Введение

• • Все запросы — JSON по протоколу HTTPS.
• • Суммы — в рублях, строкой с двумя знаками: "1000.50". Отдаём тоже строкой, чтобы не терять копейку на float.
• • Поле metadata — произвольный JSON (напр. tg_id): вернём его как есть в статусе и в каждом вебхуке.
• • Базовый URL:

https://flippay.pro

Авторизация

В каждый запрос добавьте два заголовка. Ключи доступны в кабинете: Настройки → Интеграция и API. Секретный ключ показывается один раз; перевыпуск отключает старый.

X-Api-Key: pk_2f9c1ab34de5f6a7b8c9d0e1
X-Api-Secret: sk_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b
Content-Type: application/json

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

1. Получите API-ключи в кабинете (Настройки → Интеграция и API).
2. Создайте платёж запросом POST /api/v1/payments.
3. Перенаправьте плательщика на pay_url из ответа.
4. Получите уведомление о статусе на ваш Callback URL (или опрашивайте статус).
5. Проверьте подпись X-Signature и выдайте товар/услугу.

POST https://flippay.pro/api/v1/payments

Создаёт платёж и возвращает ссылку на нашу страницу оплаты. Идемпотентность: повторный запрос с тем же order_id вернёт существующий платёж, дубль не создаётся.

Параметры

Запрос

# создание платежа на 1500 ₽ по СБП
curl -X POST https://flippay.pro/api/v1/payments \
  -H "X-Api-Key: pk_2f9c1ab34de5f6a7b8c9d0e1" \
  -H "X-Api-Secret: sk_8a7b6c5d4e3f2a1b0c9d8e7f6a5b4c3d2e1f0a9b" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "ORDER-12345",
    "amount": "1500.00",
    "payment_method": 2,
    "description": "Заказ №12345",
    "success_url": "https://shop.ru/orders/12345/ok",
    "fail_url": "https://shop.ru/orders/12345/fail",
    "metadata": { "tg_id": 123456789 }
  }'

Ответ 200 OK

{
  "order_id": "ORDER-12345",
  "status": "pending",
  "amount": "1500.00",
  "currency": "RUB",
  "pay_url": "https://flippay.pro/pay/m12_a1b2c3d4e5f6",
  "metadata": { "tg_id": 123456789 }
}

GET https://flippay.pro/api/v1/payments/{order_id}

Резервный способ узнать статус, если не используете webhook (или для сверки).

curl https://flippay.pro/api/v1/payments/ORDER-12345 \
  -H "X-Api-Key: pk_…" -H "X-Api-Secret: sk_…"

{
  "order_id": "ORDER-12345",
  "status": "success",
  "amount": "1500.00",
  "currency": "RUB",
  "pay_url": "https://flippay.pro/pay/m12_a1b2c3d4e5f6",
  "metadata": { "tg_id": 123456789 }
}

Webhook (уведомления)

Укажите Callback URL в кабинете (Настройки → Уведомления). При смене статуса платежа мы отправим POST на ваш адрес с JSON-телом и заголовком X-Signature.

• • Только HTTPS, публичный домен, валидный SSL.
• • Отвечайте 200 OK в течение 60 секунд.
• • Ретраи: до 7 попыток с экспоненциальным бэкоффом (1м → 5м → 30м → 2ч → 6ч → 12ч).
• • Отправляется при переходе платежа в success, failed или refunded (статус pending вебхуком не шлётся).
• • Из-за ретраев одно и то же уведомление может прийти несколько раз — обрабатывайте идемпотентно (например, по паре order_id + status).
• • Всегда сверяйте сумму и статус с вашим заказом; доверяйте только запросам с верной подписью.

Тело запроса

{
  "event": "payment.updated",
  "order_id": "ORDER-12345",
  "status": "success",
  "amount": "1500.00",
  "currency": "RUB",
  "metadata": { "tg_id": 123456789 }
}

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

Заголовок X-Signature = HMAC-SHA256 от сырого тела запроса (hex), ключ — ваш webhook_secret из кабинета: Настройки → Уведомления. Сравнивайте константно (constant-time). Если подпись не совпала — игнорируйте запрос.

import hmac, hashlib

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

# FastAPI / Flask: берите ИМЕННО сырое тело запроса (request body bytes)

$raw = file_get_contents('php://input');
$sig = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
$expected = hash_hmac('sha256', $raw, $secret);
if (hash_equals($expected, $sig)) { /* ок */ }

const crypto = require('crypto');

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret)
    .update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Методы оплаты

Значение поля payment_method при создании платежа. Доступные вам методы настраивает менеджер.

Статусы платежа

Коды ошибок

При ошибке возвращается соответствующий HTTP-код и тело JSON с полем detail:

{ "detail": "invalid credentials" }

Тестирование

• • Отдельной песочницы (sandbox) нет — интеграция тестируется на боевых ключах.
• • Проверяйте сценарий на минимальных суммах, затем переходите к реальным.
• • Для приёма вебхуков нужен публичный HTTPS-endpoint; на этапе разработки удобно поднять туннель (ngrok / cloudflared) и указать его как Callback URL.
• • Если вебхук не дошёл — статус всегда можно получить запросом GET статуса.