Описание протокола

Мы используем двухстадийный протокол, в котором перед проведением платежа сначала происходит запрос на подтверждение, а затем само проведение транзакции. Это особенно актуально для магазинов и складов, которым необходимо следить за наличием товара. В зависимости от сервиса, который вы подключаете, а так же от специфики вашего бизнеса, определённые запросы и уведомления могут быть настроены по вашему желанию (например, пополнение счёта благотворительного фонда не нуждается в подтверждении проведения платежа, и этот запрос может быть отключен). В дальнейшем в документации мы будем описывать стандартный двухстадийный протокол.

Технические особенности протокола

  • Данные передаются по протоколу HTTPS.
  • Используемая кодировка - UTF-8.
  • Параметры запросов кодируются согласно спецификации RFC 3986.
  • Формат валют - ISO 4217.

Схема взаимодействия мерчанта с системой

Схема взаимодействия при инициализации платежа с мерчантом:

Схема взаимодействия при инициализации платежа с мерчантом

Схема взаимодействия при покупке с витрины:

Схема взаимодействия при покупке с витрины

Что необходимо сделать?

Для запуска необходимо инициализировать платеж одним из способов.
На стороне мерчанта необходимо реализовать платежное приложение, которое будет обрабатывать асинхронные запросы: «check», «pay» и «cancel» - запросы на потверждение, уведомления об успешности/неуспешности платежа. URL данного приложения необходимо предоставить менеджеру. Желательно иметь два URL - для тестовой среды и боевой.
Для упрощения подключения в описаниях запросов приведены примеры, а так же можно использовать класс с реализованными методами формирования подписи и ответов.

Шаги протокола

Шаг 1. Инициирование оплаты(например, через платёжную форму)

Инициировать платёж может

  • плательщик, производя оплату товаров или услуг на платёжной форме или отправляя смс на короткий номер
  • мерчант, выставив клиенту инвойс (счет на полату) или послав запрос к API
  • PlatBox, если у плательщика есть активная подписка на сервис мерчанта.

Описание работы с платёжной формой тут.

Шаг 2. PlatBox отправляет мерчанту запрос на подтверждение платежа и ожидает ответ.

PlatBox присылает мерчанту запрос check. Мерчант проверяет, сможет ли он выдать товар/услугу.
Если мерчант отвечает ok, то далее переходим к Шагу 3.
Если мерчант отвечает ошибкой, то платёж не инициируется.
Описание запроса check тут.

Шаг 3. PlatBox проводит платёж, отправляет результат мерчанту и ожидает ответ.

PlatBox пробует провести платёж. По результатам платежа отправляется запрос pay, если платёж успешен, или cancel, если запрос неуспешен (например, недостаточно средств). В ответ ожидает статус ok. Если статус иной, то успешный платёж пойдёт на отмену (если провайдер поддерживает отмену). Если ответа не было получено - включается политика переоповещения. Описание запроса pay/cancel.