FOXFLOW API / V1

Одна интеграция.
Приём по СБП.

Создавайте счета в рублях, получайте QR-код и проверяйте оплату через API FOXFLOW. Запросы выполняются с сервера вашего сайта.

Подключение

В кабинете откройте «Мерчанты → Документация API» и создайте ключ нужного магазина. Он отображается один раз. Ключ привязан к мерчанту; отдельный идентификатор магазина в платёжном запросе не требуется.

Адрес нашего API:

https://foxflow.cc/api/v1

Передавайте ключ в заголовке Authorization: Bearer lmn_live_…. Храните его на сервере. Не помещайте ключ в HTML, клиентский JavaScript, URL или логи. Для замены создайте новый ключ, обновите интеграцию и отзовите старый в кабинете. До трёх активных ключей.

Создать счёт

POST /invoices · Content-Type: application/json

const response = await fetch('https://foxflow.cc/api/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.FOXFLOW_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': savedPaymentAttemptKey
  },
  body: JSON.stringify({ amount: '100.00', currency: 'RUB' })
});
const result = await response.json();
if (!response.ok) throw new Error('Запрос FOXFLOW не завершён');
// Сохраните result.invoice.id в своём заказе.

Сумма — строка от 1 до 1 000 000 рублей, максимум два знака после точки. Только RUB; лишние поля отклоняются. Ключ идемпотентности — 16–80 латинских букв, цифр, дефисов или подчёркиваний. Сохраните его в базе до отправки вместе с заказом и суммой.

Создание возвращает 201; повтор того же запроса — 200 и replayed: true. Создание счёта не означает оплату. При тайм-ауте не создавайте новый ключ: повторите с прежним либо проверьте историю.

Поля invoice

Поле	Значение
`id`	UUID счёта FOXFLOW
`amount_minor`	Копейки: 10000 = 100 ₽
`currency`	RUB
`phase`	ready, creating или unknown
`status`	pending, paid, cancelled, expired или failed
`created_at`	Unix-время, секунды
`payment_url`	Платёжная ссылка СБП
`qr_image`	PNG как data URI или null

Ссылка и QR доступны для готового счёта. Показывайте изображение через <img>, не вставляйте ответ как HTML. У исторических счетов реквизиты могут быть пустыми. API возвращает JSON и не требует перехода в сторонний кабинет.

Проверка оплаты

GET /invoices/ID возвращает { invoice: { ... } }. GET /invoices — последние 20 счетов этого мерчанта в поле invoices. Все запросы требуют Bearer-ключ.

Опрашивайте статус с backend. Подтверждайте заказ только при phase=ready и status=paid, сверяя ID, валюту и сумму с собственной базой. Запишите оплату и выдачу товара однократно в транзакции. QR, возврат покупателя на сайт и сообщение из браузера не подтверждают оплату.

Лимиты на мерчанта: 5 операций записи и 60 чтений в минуту, общие для его ключей. Планируйте опрос всех ожидающих счетов в пределах лимита. Webhook сейчас не отправляется.

Ошибки и повторы

400 — неверные параметры.
401 — отсутствующий, неверный либо отозванный ключ.
404 — счёт не найден или принадлежит другому мерчанту.
409 — запрос выполняется, требует сверки либо ключ использован с другой суммой.
413 / 415 — тело больше 4 КиБ или неверный Content-Type.
429 — ограничение частоты; учитывайте Retry-After, если он присутствует.
502 / 503 — нет подтверждённого результата. Не создавайте заменяющий счёт с новым ключом.

При unknown или зависшем creating обратитесь в поддержку FOXFLOW для сверки. До выяснения результата новые создания могут быть заблокированы. Ошибка содержит detail либо error; сохраните заголовок X-Request-Id для поддержки. Не записывайте секреты и платёжные реквизиты в логи.

Защита интеграции

HTTPS с проверкой сертификата, изоляция мерчантов, отзыв ключей, ограничение запросов и идемпотентность. Каждый ключ открывает доступ только к своему магазину. Служебные данные обработки платежа не передаются клиенту. Интеграция выполняется через ваш backend; браузерные запросы с секретным ключом не поддерживаются.

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