#API

API Filebird — интерфейс для передачи заказов из вашей системы в торговый канал Filebird и получения результата оплаты.

#Что делает API

• принимает заказ из вашей системы
• инициирует оплату на стороне Filebird
• отправляет server-to-server уведомление о результате
• позволяет отобразить статус заказа на вашей стороне

#Базовый сценарий

1. Вы формируете заказ (x_invoice_num)
2. Передаёте параметры операции в Filebird
3. Покупатель переходит к оплате
4. Filebird отправляет callback с результатом
5. Вы сохраняете статус и показываете его пользователю

#Важно

• оплату принимает Filebird
• вы не обрабатываете платёж на своей стороне
• финальный статус определяется только через callback

#Базовый сценарий интеграции

#Последовательность действий

1. Партнёр формирует заказ на своей стороне и присваивает ему уникальный x_invoice_num.
2. Партнёр формирует параметры торговой операции и подпись x_fp_hash.
3. Web-ресурс партнёра перенаправляет покупателя в Filebird через HTML form POST.
4. Покупатель переходит на платёжную страницу, предоставленную Filebird, и выполняет оплату с использованием платёжной инфраструктуры банка или платёжного провайдера.
5. Filebird отправляет server-to-server уведомление на x_relay_url.
6. Партнёр валидирует callback и фиксирует итоговый статус операции.
7. Покупатель возвращается на web-ресурс партнёра.
8. Web-ресурс партнёра показывает покупателю уже сохранённый статус заказа.

#Архитектурные принципы

#Источник истины

Финальный статус торговой операции определяется только через server-to-server уведомление.

Возврат покупателя не должен использоваться как источник финального статуса.

#Stateless-модель

Интеграция должна строиться как stateless-контур. Ключом торговой операции на стороне партнёра является x_invoice_num.

#Основные сущности

#Торговая операция

Совокупность действий по заказу, оплате и фиксации результата в системе Filebird.

#Платёжная сессия

Технический набор параметров, который передаётся в момент перехода покупателя к оплате.

#x_invoice_num

Уникальный идентификатор заказа на стороне партнёра.

Используется для:

• связи redirect → callback → return;
• поиска торговой операции;
• сопоставления результата оплаты с заказом партнёра;
• идемпотентной обработки уведомлений.

x_invoice_num не следует смешивать с x_fp_sequence:

• x_invoice_num идентифицирует заказ;
• x_fp_sequence используется как технический параметр подписи.

#x_fp_sequence

Технический идентификатор сделки, назначаемый web-ресурсом партнёра.

Может совпадать с номером счёта, но не обязан совпадать с x_invoice_num. Допустимо использовать иное уникальное значение, применяемое при формировании подписи запроса.

#x_fp_timestamp

Временная метка в формате Unix timestamp (UTC, количество секунд с 1 января 1970 года), используемая при формировании подписи запроса.

#Статус торговой операции

Состояние заказа в интеграции партнёра после обработки server-to-server уведомления.

#Типы данных

#Безопасность

#При запуске торговой операции

Рекомендуется:

• использовать только HTTPS;
• формировать подпись x_fp_hash;
• передавать уникальный x_invoice_num;
• передавать корректно нормализованную сумму;
• не формировать торговую операцию на стороне браузера без серверной подписи.

#При обработке callback

Рекомендуется:

• проверять IP-адрес источника уведомления;
• проверять существование заказа по x_invoice_num;
• сверять сумму операции после нормализации;
• проверять подпись callback;
• учитывать повторную отправку уведомления;
• возвращать провайдеру короткий и однозначный ответ после успешной обработки.

#Инициация торговой операции

Инициация оплаты выполняется через передачу параметров торговой операции в момент перехода покупателя к оплате.

#Формат интеграции

• Протокол: HTTPS
• Метод: POST
• Формат: HTML form POST
• Endpoint: определяется параметрами подключения торгового канала

#Типовой пример HTML form POST

<form method="post" action="https://provider.example/payment">
  <input type="hidden" name="x_login" value="demo-channel" />
  <input type="hidden" name="x_amount" value="10.00" />
  <input type="hidden" name="x_currency_code" value="RUB" />
  <input type="hidden" name="x_invoice_num" value="shop1-20260403101530-1234" />
  <input type="hidden" name="x_fp_sequence" value="123456789" />
  <input type="hidden" name="x_fp_timestamp" value="1712131200" />
  <input type="hidden" name="x_fp_hash" value="0123456789abcdef0123456789abcdef" />
  <input type="hidden" name="x_relay_response" value="TRUE" />
  <input type="hidden" name="x_relay_url" value="https://clientsite.example/callback" />
  <input type="hidden" name="x_receipt_link_url" value="https://clientsite.example/success?invoice_num=shop1-20260403101530-1234" />
  <input type="hidden" name="x_cancel_url" value="https://clientsite.example/fail?invoice_num=shop1-20260403101530-1234" />

  <input type="hidden" name="x_line_item" value="item1<|>Product 1<|>Main item<|>1<|>10.00<|>N" />
  <input type="hidden" name="x_email" value="buyer@example.com" />
  <input type="hidden" name="x_first_name" value="Ivan" />
  <input type="hidden" name="x_last_name" value="Petrov" />
  <input type="hidden" name="x_address" value="Lenina 1" />
  <input type="hidden" name="x_country" value="RU" />
  <input type="hidden" name="x_phone" value="+79990000000" />
  <input type="hidden" name="x_zip" value="101000" />

  <button type="submit">Оплатить</button>
</form>

#Параметры торговой операции

#Обязательные параметры

#Необязательные параметры

Ниже перечислены поля, которые поддерживаются в подтверждённом интеграционном контуре и могут передаваться дополнительно.

#Данные покупателя

#Платёжный адрес покупателя

#URL возврата

Дополнительные поля вне перечисленного набора могут поддерживаться торговым каналом, но не входят в данный подтверждённый контур торговой операции.

#Состав корзины: x_line_item

Поле x_line_item передаёт сведения о корзине в момент запуска торговой операции.

Эти данные используются Filebird для:

• формирования состава торговой операции;
• отражения товарных позиций;
• формирования кассового чека и фискальных документов в рамках торговой модели.

Партнёр не осуществляет фискализацию.

#Формат элемента

item_id<|>item_name<|>item_description<|>qty<|>unit_price<|>taxable

Где:

• item_id — идентификатор позиции;
• item_name — наименование позиции;
• item_description — описание позиции;
• qty — количество;
• unit_price — цена за единицу;
• taxable — признак налогообложения.

#Поле taxable

Рекомендуемые значения:

• Y
• N

Интерфейс также может принимать эквивалентные значения:

• TRUE
• FALSE
• T
• F
• YES
• NO
• 1
• 0

#Передача нескольких позиций

Каждая позиция корзины передаётся отдельным параметром x_line_item.

Пример:

x_line_item=item1<|>golf balls<|><|>2<|>18.95<|>Y
x_line_item=item2<|>golf bag<|>Wilson golf carry bag, red<|>1<|>39.99<|>Y
x_line_item=item3<|>book<|>Golf for Dummies<|>1<|>21.99<|>Y

#HTML пример нескольких позиций

<input type="hidden" name="x_line_item" value="item1<|>golf balls<|><|>2<|>18.95<|>Y" />
<input type="hidden" name="x_line_item" value="item2<|>golf bag<|>Wilson golf carry bag, red<|>1<|>39.99<|>Y" />
<input type="hidden" name="x_line_item" value="item3<|>book<|>Golf for Dummies<|>1<|>21.99<|>Y" />

#Подпись запроса: x_fp_hash

Подпись x_fp_hash формируется на стороне партнёра перед переходом к оплате.

#Строка для подписи

x_login ^ x_fp_sequence ^ x_fp_timestamp ^ x_amount ^ x_currency_code

#Алгоритм

• алгоритм: HMAC-MD5
• секрет: ключ торгового канала

#Пример исходной строки

demo-channel^123456789^1712131200^10.00^RUB

#Пример генерации подписи на PHP

<?php

$login = 'demo-channel';
$sequence = '123456789';
$timestamp = '1712131200';
$amount = '10.00';
$currency = 'RUB';
$secret = 'test-secret';

$data = $login . '^' . $sequence . '^' . $timestamp . '^' . $amount . '^' . $currency;
$hash = hash_hmac('md5', $data, $secret);

echo $hash;

#Практические требования

• сумма должна быть нормализована до формата, используемого в подписи;
• строка должна собираться строго в заданном порядке;
• секретный ключ не должен попадать на клиентскую сторону;
• подпись должна вычисляться сервером партнёра.

#Redirect и callback

Интеграция использует два разных канала, которые нельзя смешивать.

#Redirect

Используется для пользовательского сценария и интерфейса оплаты.

#Callback

Используется для фиксации результата операции на стороне партнёра. Именно callback является источником истины.

#Server-to-server уведомление

После завершения обработки торговой операции Filebird отправляет POST-запрос на x_relay_url.

#Типовые параметры callback

#Интерпретация результата

До получения callback торговая операция обычно находится в статусе pending.

#Валидация callback

При обработке callback рекомендуется выполнять проверки в следующем порядке:

1. Проверить наличие x_invoice_num.
2. Найти заказ по x_invoice_num.
3. Если заказ уже находится в финальном статусе paid, вернуть успешный ответ без повторной обработки.
4. Проверить IP-адрес источника уведомления.
5. Если x_login передан в callback, сверить его с идентификатором торгового канала.
6. Сверить сумму операции после нормализации.
7. Проверить подпись x_MD5_Hash.
8. Сопоставить код результата со внутренним статусом.
9. Сохранить результат операции.
10. Вернуть подтверждение получения.

#Подпись callback

Подпись x_MD5_Hash проверяется по алгоритму MD5.

Строка для проверки составляется в формате:

secret_key + x_login + x_trans_id + x_amount

Где:

• secret_key — секретный ключ торгового канала;
• x_login — идентификатор торгового канала;
• x_trans_id — идентификатор операции в системе провайдера;
• x_amount — сумма операции в нормализованном формате.

#Важное замечание по x_login в callback

В составе server-to-server уведомления поле x_login может отсутствовать.

Если x_login передаётся, оно должно совпадать с идентификатором торгового канала. Если x_login не передаётся, проверка подписи выполняется с использованием идентификатора канала из параметров подключения.

#Идемпотентность callback

Server-to-server уведомление может быть отправлено повторно.

Если торговая операция уже переведена в финальный статус paid, повторный callback:

• не должен повторно изменять данные;
• не должен повторно запускать бизнес-логику;
• должен завершаться успешным ответом провайдеру.

#Типовой успешный ответ

HTTP 200
OK

#Возврат покупателя

После завершения оплаты покупатель возвращается на web-ресурс партнёра.

#Важно

• возврат выполняется через браузер покупателя;
• данные возврата не должны использоваться как источник финального статуса;
• return flow нужен для UX, но не для фиксации результата торговой операции.

#Рекомендуемый подход

• использовать одну техническую страницу возврата;
• передавать x_invoice_num или эквивалентный идентификатор заказа;
• считывать уже сохранённый статус из своей системы;
• показывать пользователю итоговый результат.

Если к моменту возврата callback ещё не обработан, страница может показывать промежуточный статус и выполнять повторное чтение состояния заказа на стороне партнёра.

#Типовые ошибки интеграции

#Quick Start

1. Получить параметры подключения торгового канала:

   • идентификатор канала;
   • endpoint для запуска торговой операции;
   • разрешённые IP-адреса callback;
   • секретный ключ.

2. На стороне web-ресурса партнёра сформировать заказ:

   • x_invoice_num;
   • сумму;
   • валюту;
   • состав корзины.

3. Сформировать технические поля подписи:

   • x_fp_sequence;
   • x_fp_timestamp.

4. Сгенерировать подпись x_fp_hash.

5. Сформировать HTML form POST и перенаправить покупателя в Filebird.

6. Реализовать endpoint для x_relay_url.

7. Принимать callback и валидировать:

   • IP;
   • заказ;
   • сумму;
   • подпись.

8. Сохранять статус операции идемпотентно.

9. На странице возврата показывать уже сохранённый статус заказа.

#Что понадобится для SDK

Для SDK на стороне партнёра должны быть стабильно реализованы:

• генерация x_fp_sequence;
• генерация x_fp_timestamp;
• генерация x_fp_hash;
• сборка HTML form POST;
• формирование параметров торговой операции;
• сериализация x_line_item;
• приём callback;
• валидация подписи callback;
• проверка IP и суммы;
• идемпотентное обновление статуса;
• маппинг результата операции во внутренний статус заказа.

#Параметры подключения

Партнёр получает от Filebird параметры подключения торгового канала:

• идентификатор торгового канала;
• адрес для запуска торговой операции;
• секретный ключ;
• разрешённые IP-адреса server-to-server уведомлений.