Обзор
Этот раздел описывает, как Yume общается с внешними платёжными шлюзами при оплате подписок компаний. Единственный подключённый шлюз — Клиент FreedomPay. Клиент FreedomPay — это тонкая обёртка над HTTP-API платёжной системы. Он умеет:- создавать обычный платёж (оплата подписки с платёжной формой и фискальным чеком);
- проводить рекуррентное списание по сохранённой (токенизированной) карте;
- управлять картами пользователя (привязка, список, удаление);
- запрашивать статус платежа и выполнять сервисные операции над ним — отмену, возврат средств и списание ранее заблокированной суммы.
Клиент FreedomPay существует в одном экземпляре на весь процесс. Он создаётся при загрузке модуля из настроек платёжных шлюзов (ветка «freedom») и переиспользуется всеми частями системы. Отдельного экземпляра на компанию нет — идентификатор мерчанта и секреты общие для всей платформы.
Настройки клиента
При создании клиент забирает из конфигурации набор параметров и хранит их на всё время работы процесса.Как формируется запрос и подпись
Каждый вызов проходит через две общие процедуры.Отправка запроса
Полный адрес собирается как «адрес шлюза» + имя операции. Тело запроса формируется из объекта данных: он превращается в набор пар «поле-значение», причём выбрасываются только незаданные поля (те, у которых значение отсутствует). Поля с реальным значением, включая ноль и пустую строку, в шлюз уходят. Тело отправляется методом POST в формате JSON. Ответ шлюза приходит в XML; система разбирает его и возвращает содержимое корневого узла ответа в виде обычного словаря.Создание подписи
Каждый запрос подписывается MD5-подписью, чтобы шлюз мог проверить его подлинность. Подпись строится по строгому правилу:- Строка начинается с имени операции (для веб-платежей это имя серверного скрипта, например файл инициации платежа; для карточных операций — короткое имя действия: привязка, список, удаление, оплата, прямое списание и т. п.).
- Затем к строке по очереди добавляются значения всех полей запроса, отсортированных по алфавиту имён, кроме самого поля подписи. При этом пропускаются все «пустые» значения (ноль, пустая строка, незаданное поле); значения-перечисления берутся в их «сыром» виде (например, код валюты или число «1»/«0» для флагов).
- В конце добавляется секретный ключ мерчанта.
- От получившейся строки берётся MD5-хеш — это и есть подпись.
Порядок значений в подписи определяется алфавитным порядком имён полей, а не порядком их объявления. Каждое значение отделяется точкой с запятой. Именно поэтому в каждом запросе присутствует случайная «соль» — она гарантирует уникальность подписи даже для одинаковых по смыслу запросов.
Проверка входящей подписи
Тем же правилом проверяются входящие колбэки шлюза. Клиент умеет собрать ожидаемую подпись по присланным полям и сравнить её с полем подписи в запросе — сравнение выполняется способом, устойчивым к побайтовому подбору. Колбэк с неверной подписью отклоняется до любых изменений данных.Обычный платёж (оплата подписки)
Инициация платежа создаёт полноценную платёжную операцию с формой оплаты и фискальным чеком. На вход принимаются идентификатор заказа (инвойса), сумма, валюта (по умолчанию тенге), описание (по умолчанию «Subscription»), адреса callback-ов и итоговых редиректов, email плательщика и список позиций чека. Что происходит при вызове:- Валюта по умолчанию — тенге; поддерживаются также доллар США, евро и киргизский сом.
- Позиции чека превращаются в состав фискального чека: для каждой позиции берутся наименование, количество и цена, а тип налога жёстко проставляется нулевым. Весь список сериализуется в текст.
- Адреса проверки и результата склеиваются из базового URL сайта и переданных путей. Адреса успеха и ошибки уходят как есть.
- Параметры формы задаются фиксированно: включены Apple Pay и Google Pay, включена возможность сохранить карту, показ деталей и показ телефона, а показ поля email выключен.
- Метод обращения к шлюзу — POST.
Рекуррентное списание по сохранённой карте
Для автосписаний (продление подписки без участия пользователя) используется отдельная цепочка из трёх шагов.1
Инициация платежа по сохранённой карте
На вход идут идентификатор пользователя, идентификатор заказа, сумма, токен сохранённой карты, адреса callback-ов и редиректов, позиции чека и контакты плательщика. Описание фиксируется как «Subscription». Адреса проверки и результата так же склеиваются с базовым URL сайта. Запрос уходит на карточную операцию инициации; в ответе шлюз возвращает данные созданного платежа (включая его идентификатор).
2
Подтверждение оплаты по карте
По полученному идентификатору платежа вызывается операция подтверждения. Это второй шаг сценария, когда платёж уже создан и его нужно провести.
3
Прямое списание по карте
Альтернатива/дополнение к подтверждению — операция прямого списания по идентификатору платежа. Оба метода принимают только идентификатор мерчанта и идентификатор платежа и различаются именем действия в подписи. На практике для рекуррентных списаний вызывается именно прямое списание.
Ключевое отличие рекуррентного списания от обычного платежа — вместо платёжной формы используется ранее сохранённый токен карты, поэтому от пользователя не требуется никаких действий. Именно этот механизм лежит в основе автопродления подписок.
Управление картами
Привязка карты
Привязка добавляет карту в хранилище шлюза для последующих рекуррентных списаний. На вход идут идентификатор пользователя, ссылка callback (склеивается с базовым URL сайта) и ссылка возврата пользователя. Здесь заложен механизм отката между версиями API: сначала система пытается использовать новый метод привязки. Если шлюз не вернул статус «ok», она автоматически переформировывает подпись под старый метод и повторяет запрос через него. Пользователю это незаметно.Порядок такой: сначала пробуется современный вариант привязки, и только при неуспешном статусе происходит откат на устаревший. Успешный ответ нового метода возвращается сразу, без обращения к старому.
Список карт и удаление
- Список карт возвращает сохранённые карты пользователя по его идентификатору.
- Удаление карты убирает карту из хранилища по идентификатору пользователя и токену карты.
Сервисные операции над платежом
Помимо создания платежей клиент умеет управлять уже существующими операциями по их идентификатору.Схемы данных запросов
Все объекты запросов FreedomPay построены поверх общей базы — Базовых полей подписи, которые добавляют в любой запрос случайную соль и саму подпись.Позиции чека передаются в шлюз не как структурированный JSON, а как текстовое представление списка объектов. Тип налога в каждой позиции всегда проставляется нулевым, независимо от входных данных.
Справочники значений
Как это используется
Обычный платёж и рекуррентное списание по карте — это два входа в оплату подписки: первый показывает пользователю платёжную форму, второй списывает деньги молча по сохранённой карте. Результат оплаты приходит обратно в систему через вебхук результата, который уже относится к слою инвойсов и подписок и здесь не рассматривается. Сервисные операции (статус, отмена, возврат, клиринг) используются для сопровождения жизненного цикла платежа после его создания.Связанные страницы
Глоссарий: Платёжные шлюзы
Полный перечень полей клиентов и объектов запросов платёжных шлюзов.
Компании и биллинг (подписки, платежи)
Обзорный раздел про компании, их подписки и денежные потоки.
Создание компании и её адрес
Модель компании и её домены, генерация новой компании с дефолтными данными и регистрация владельца.
Инвойсы и платежи
Счета, их позиции и ошибки, расчёт суммы и обработка ответа от платёжной системы результата оплаты.
Карты и автосписания
Сохранённые платёжные карты компании и их привязка к автоматическим списаниям.
Лимиты и тарификация
Лимиты плана по ресурсам, их цены по периодам и пересчёт фактического потребления.
Онбординг, новости и статистика
Шаги онбординга компании, лента новостей и снапшоты системной статистики.