> ## Documentation Index > Fetch the complete documentation index at: https://docs.yume.cloud/llms.txt > Use this file to discover all available pages before exploring further. # Платёжные шлюзы > Клиент FreedomPay для оплаты подписок: подпись запроса, обычный платёж и рекуррентное списание по карте, управление картами и сервисные операции. Полный перечень полей — в [глоссарии](/ru/logic/company-billing/gateways-glossary). ## Обзор Этот раздел описывает, как Yume общается с внешними платёжными шлюзами при оплате подписок компаний. Единственный подключённый шлюз — **Клиент FreedomPay**. Клиент FreedomPay — это тонкая обёртка над HTTP-API платёжной системы. Он умеет: * создавать обычный платёж (оплата подписки с платёжной формой и фискальным чеком); * проводить рекуррентное списание по сохранённой (токенизированной) карте; * управлять картами пользователя (привязка, список, удаление); * запрашивать статус платежа и выполнять сервисные операции над ним — отмену, возврат средств и списание ранее заблокированной суммы. Клиент FreedomPay существует в одном экземпляре на весь процесс. Он создаётся при загрузке модуля из настроек платёжных шлюзов (ветка «freedom») и переиспользуется всеми частями системы. Отдельного экземпляра на компанию нет — идентификатор мерчанта и секреты общие для всей платформы. ## Настройки клиента При создании клиент забирает из конфигурации набор параметров и хранит их на всё время работы процесса. | Поле | Тип | Назначение | | ----------------------- | ----- | ----------------------------------------------------------------------------------------------------------------- | | Адрес шлюза | текст | Базовый URL API FreedomPay, к которому добавляется имя конкретной операции | | Идентификатор мерчанта | текст | ID магазина в FreedomPay; подставляется в каждый запрос и в путь карточных операций | | Секретный ключ мерчанта | текст | Используется при вычислении подписи каждого запроса | | Секретный ключ выплат | текст | Отдельный секрет для операций выплат (хранится, но в текущих методах не задействован) | | Тестовый режим | флаг | Включается, только если в настройках указана единица; в любом другом случае режим выключен (поле остаётся пустым) | | Базовый URL сайта | текст | Префикс, который добавляется к адресам callback-ов проверки и результата перед отправкой в шлюз | Тестовый режим считается включённым строго при числовом значении «1». Любое другое значение (в том числе строка «1», ноль, пустое значение) трактуется как выключенный режим — поле просто не попадёт в запрос. ## Как формируется запрос и подпись Каждый вызов проходит через две общие процедуры. ### Отправка запроса Полный адрес собирается как «адрес шлюза» + имя операции. Тело запроса формируется из объекта данных: он превращается в набор пар «поле-значение», причём выбрасываются **только незаданные поля** (те, у которых значение отсутствует). Поля с реальным значением, включая ноль и пустую строку, в шлюз уходят. Тело отправляется методом POST в формате JSON. Ответ шлюза приходит в XML; система разбирает его и возвращает содержимое корневого узла ответа в виде обычного словаря. ### Создание подписи Каждый запрос подписывается MD5-подписью, чтобы шлюз мог проверить его подлинность. Подпись строится по строгому правилу: 1. Строка начинается с **имени операции** (для веб-платежей это имя серверного скрипта, например файл инициации платежа; для карточных операций — короткое имя действия: привязка, список, удаление, оплата, прямое списание и т. п.). 2. Затем к строке по очереди добавляются значения всех полей запроса, **отсортированных по алфавиту имён**, кроме самого поля подписи. При этом пропускаются все «пустые» значения (ноль, пустая строка, незаданное поле); значения-перечисления берутся в их «сыром» виде (например, код валюты или число «1»/«0» для флагов). 3. В конце добавляется секретный ключ мерчанта. 4. От получившейся строки берётся MD5-хеш — это и есть подпись. Порядок значений в подписи определяется алфавитным порядком имён полей, а не порядком их объявления. Каждое значение отделяется точкой с запятой. Именно поэтому в каждом запросе присутствует случайная «соль» — она гарантирует уникальность подписи даже для одинаковых по смыслу запросов. ### Проверка входящей подписи Тем же правилом проверяются **входящие** колбэки шлюза. Клиент умеет собрать ожидаемую подпись по присланным полям и сравнить её с полем подписи в запросе — сравнение выполняется способом, устойчивым к побайтовому подбору. Колбэк с неверной подписью отклоняется до любых изменений данных. Имя операции для входящего колбэка определяется адресом, на который шлюз его прислал. Для адреса, заканчивающегося слешем, FreedomPay подставляет в подпись **пустое имя** вместо последнего сегмента пути. Поэтому обработчик результата платежа перебирает варианты имени и найденным подписывает ответ. Обработчик, который жёстко задаёт имя операции, на адресе со слешем отклонит **все** легитимные колбэки. ## Обычный платёж (оплата подписки) Инициация платежа создаёт полноценную платёжную операцию с формой оплаты и фискальным чеком. На вход принимаются идентификатор заказа (инвойса), сумма, валюта (по умолчанию тенге), описание (по умолчанию «Subscription»), адреса callback-ов и итоговых редиректов, email плательщика и список позиций чека. Что происходит при вызове: * **Валюта** по умолчанию — тенге; поддерживаются также доллар США, евро и киргизский сом. * **Позиции чека** превращаются в состав фискального чека: для каждой позиции берутся наименование, количество и цена, а тип налога жёстко проставляется нулевым. Весь список сериализуется в текст. * **Адреса проверки и результата** склеиваются из базового URL сайта и переданных путей. Адреса успеха и ошибки уходят как есть. * **Параметры формы** задаются фиксированно: включены Apple Pay и Google Pay, включена возможность сохранить карту, показ деталей и показ телефона, а показ поля email выключен. * Метод обращения к шлюзу — POST. После сборки данных вычисляется подпись, и запрос уходит в шлюз. В ответ приходит разобранный XML — как правило, со ссылкой на платёжную форму либо с ошибкой. Адреса проверки и результата собираются простым сложением базового URL сайта и переданного пути. Если путь не передан (по умолчанию он не задан), сложение с незаданным значением вызовет ошибку и вызов прервётся. Эти два адреса нужно передавать всегда. ## Рекуррентное списание по сохранённой карте Для автосписаний (продление подписки без участия пользователя) используется отдельная цепочка из трёх шагов. На вход идут идентификатор пользователя, идентификатор заказа, сумма, токен сохранённой карты, адреса callback-ов и редиректов, позиции чека и контакты плательщика. Описание фиксируется как «Subscription». Адреса проверки и результата так же склеиваются с базовым URL сайта. Запрос уходит на карточную операцию инициации; в ответе шлюз возвращает данные созданного платежа (включая его идентификатор). По полученному идентификатору платежа вызывается операция подтверждения. Это второй шаг сценария, когда платёж уже создан и его нужно провести. Альтернатива/дополнение к подтверждению — операция прямого списания по идентификатору платежа. Оба метода принимают только идентификатор мерчанта и идентификатор платежа и различаются именем действия в подписи. На практике для рекуррентных списаний вызывается именно прямое списание. Ключевое отличие рекуррентного списания от обычного платежа — вместо платёжной формы используется ранее сохранённый токен карты, поэтому от пользователя не требуется никаких действий. Именно этот механизм лежит в основе автопродления подписок. ## Управление картами ### Привязка карты Привязка добавляет карту в хранилище шлюза для последующих рекуррентных списаний. На вход идут идентификатор пользователя, ссылка callback (склеивается с базовым URL сайта) и ссылка возврата пользователя. Здесь заложен механизм отката между версиями API: сначала система пытается использовать новый метод привязки. Если шлюз не вернул статус «ok», она автоматически переформировывает подпись под старый метод и повторяет запрос через него. Пользователю это незаметно. Порядок такой: сначала пробуется современный вариант привязки, и только при неуспешном статусе происходит откат на устаревший. Успешный ответ нового метода возвращается сразу, без обращения к старому. ### Список карт и удаление * **Список карт** возвращает сохранённые карты пользователя по его идентификатору. * **Удаление карты** убирает карту из хранилища по идентификатору пользователя и токену карты. ## Сервисные операции над платежом Помимо создания платежей клиент умеет управлять уже существующими операциями по их идентификатору. | Операция | Что делает | Особенность | | ------------------------------ | ----------------------------------------------------------------- | ----------------------------------------------------------------------- | | Статус платежа | Запрашивает текущее состояние платежа | Обращается к сервисному скрипту статуса | | Отмена платежа | Отменяет незавершённый платёж | Принимает только идентификатор платежа | | Возврат платежа | Возвращает средства плательщику | Сумма «0» означает полный возврат, иначе — частичный на указанную сумму | | Списание заблокированной суммы | Проводит клиринг ранее авторизованного (заблокированного) платежа | Сумма «0» означает полное списание, иначе — частичное | И для возврата, и для списания сумма по умолчанию равна нулю, что трактуется шлюзом как «вся сумма». Чтобы выполнить частичную операцию, нужно явно передать сумму. ## Схемы данных запросов Все объекты запросов FreedomPay построены поверх общей базы — **Базовых полей подписи**, которые добавляют в любой запрос случайную соль и саму подпись. | Объект запроса | Для чего | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Данные инициации платежа | Полный набор параметров обычного платежа: идентификация, сумма и валюта, описание, позиции чека, адреса callback-ов и редиректов, контакты плательщика, параметры формы и настройки рекуррента | | Данные прямого платежа по карте | Параметры рекуррентного списания по токену карты: пользователь, сумма, заказ, токен, контакты, позиции чека | | Данные прямого списания | Идентификатор мерчанта и идентификатор платежа для прямого списания | | Данные карты (привязка/список) | Пользователь, мерчант и (для привязки) ссылки callback и возврата | | Данные удаления карты | Пользователь, мерчант и токен удаляемой карты | | Данные операции по платежу | Мерчант и идентификатор платежа — общий объект для статуса, отмены и подтверждения оплаты по карте | | Данные возврата платежа | Дополнительно несёт сумму возврата | | Данные клиринга платежа | Дополнительно несёт сумму клиринга | | Позиция чека | Отдельная позиция фискального чека: наименование, количество, тип налога, цена | Позиции чека передаются в шлюз не как структурированный JSON, а как текстовое представление списка объектов. Тип налога в каждой позиции всегда проставляется нулевым, независимо от входных данных. ### Справочники значений | Справочник | Значения | | -------------------- | --------------------------------------------- | | Валюта платежа | Тенге, доллар США, евро, киргизский сом | | Флаг включения опции | Включено / выключено (передаётся как «1»/«0») | | Язык формы оплаты | Русский, английский | | HTTP-метод callback | GET, POST, XML | | Статус ответа шлюза | Успешно / ошибка | ## Как это используется Обычный платёж и рекуррентное списание по карте — это два входа в оплату подписки: первый показывает пользователю платёжную форму, второй списывает деньги молча по сохранённой карте. Результат оплаты приходит обратно в систему через вебхук результата, который уже относится к слою инвойсов и подписок и здесь не рассматривается. Сервисные операции (статус, отмена, возврат, клиринг) используются для сопровождения жизненного цикла платежа после его создания. ## Связанные страницы Полный перечень полей клиентов и объектов запросов платёжных шлюзов. Обзорный раздел про компании, их подписки и денежные потоки. Модель компании и её домены, генерация новой компании с дефолтными данными и регистрация владельца. Счета, их позиции и ошибки, расчёт суммы и обработка ответа от платёжной системы результата оплаты. Сохранённые платёжные карты компании и их привязка к автоматическим списаниям. Лимиты плана по ресурсам, их цены по периодам и пересчёт фактического потребления. Шаги онбординга компании, лента новостей и снапшоты системной статистики.