5. Сценарии работы с API

Далее рассмотрим типовые примеры использования API с пояснениями.

5.1 Одноэтапные платежи

Одноэтапная оплата подходит тем ТСП, веб-сайты которых не подразумевают резервирование товара. Например, благотворительные пожертвования, подарочные сертификаты, фиксированная плата за услуги, продажа товара с неограниченным запасом на складе.

ТСП вызывает JS-API или create_payment_form и передаёт: 1.1. сумму платежа
1.2. описание товара (услуги)
1.3. ID проекта ТСП в системе Миксплат
и т.д.
Плательщик переходит на платёжную форму, выбирает способ оплаты и совершает платёж.
Миксплат отправляет на URL Обработчика ТСП уведомление payment_status о финальном статусе платежа (статус success или failure).
Плательщик переходит на url_success или url_failure в зависимости от успешности/неуспешности платежа.

5.2 Двухэтапные платежи

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

ТСП вызывает JS-API или create_payment_form с параметром payment_scheme=double и передаёт: 1.1. сумму платежа
1.2. описание товара (услуги)
1.3. ID проекта ТСП в системе Миксплат
и т.д.
Плательщик переходит на платёжную форму, выбирает способ оплаты и начинает платёж.
В этот момент средства резервируются, но не списываются.
Миксплат отправляет на URL обработчика ТСП уведомление payment_status о предавторизации (статус pending).
Плательщику показывается финальный экран платёжной формы "Оплата выполнена".
Плательщик переходит на url_success или url_failure в зависимости от успешности предавторизации.
В течение 5 дней ТСП подтверждает платёж с помощью метода confirm_payment.
Если этого не сделать, платёж будет отменён автоматически.
Миксплат отправляет на URL обработчика ТСП уведомление payment_status о финальном статусе платежа (статус success или failure).

5.3 Подписки

Если ваш сервис работает по модели подписки (например, онлайн кинотеатр, подписка на прессу, подписка на консультационные услуги, периодические пожертвования и т.д.), то в ЛК есть возможность настройки бесплатного ознакомительного периода, регулярности списания и других параметров.

Взаимодействие для первого платежа в режиме подписки построено идентично сценарию одноэтапной оплаты, описанному в 3.1 с тем дополнением, что в уведомлении payment_status будет параметр recurrent_id, по которому отдельные платежи могут быть связаны в группу.

После успешного первого платежа Миксплат инициирует повторные платежи согласно расписанию, заданному в настройках сервиса, и отправляет на URL обработчика ТСП уведомления payment_status о статусах платежей по подписке, передавая при этом параметр recurrent_id.

5.4 Рекуррентные платежи

С помощью рекуррентных платежей ТСП можете совершать безакцептные списания после того, как плательщик оплатит первый установочный платёж. Рекуррентные платежи отличаются от подписок тем, что их расписание и суммы не преднастроены заранее на стороне Миксплат, а инициируются со стороны ТСП.

Примеры применения рекуррентных платежей: быстрая оплата в ТСП по кнопке "оплатить" без ввода данных плательщика, автопополнение баланса в системе ТСП при снижении до значения близкого к нулю, нерегулярные подписки и т.д.

ТСП вызывает JS-API или create_payment_form с параметром recurrent_payment=1 и передаёт: 1.1. сумму платежа
1.2. описание товара (услуги)
1.3. ID проекта ТСП в системе Миксплат
и т.д. 2.Плательщик переходит на платёжную форму, выбирает способ оплаты и совершает платёж. В этот момент выполняется первый (установочный) платёж. Последующие платежи могут быть произведены только если первый платёж успешен. Сумма первого платежа может быть нулевой, если он используется только для привязки карты.
Миксплат отправляет на URL обработчика ТСП уведомление payment_status об успешности оплаты (status=success), а также параметр recurrent_id, по которому ТСП будет в дальнейшем запрашивать проведение рекуррентных платежей.
Плательщику показывается финальный экран платёжной формы "Оплата выполнена".
Плательщик переходит на сайт ТСП на url_success или url_failure в зависимости от успешности платежа.
ТСП может в произвольный момент времени инициировать повторные платёжи на произвольные суммы с помощью метода create_recurrent_payment, передавая параметр recurrent_id и сумму (amount) рекуррентного платежа. В ответ на запрос будет возвращён уникальный payment_id, по которому ТСП будут передаваться статусы очередного рекуррентного платежа.
Миксплат отправляет на URL обработчика ТСП уведомление payment_status о статусе успешности/неуспешности очередного платежа.

5.5 Тестовые платежи

Для тестирования платежей следует использовать специальные тестовые номера банковских карт и мобильных телефонов. Номера активны только в режиме тестирования (test=1). Сумма платежа должна быть в диапазоне от 1₽ до 15000₽ (значение amount от 100 до 1500000).

Для платежей с мобильного:

Номер телефона	Статус платежа (status)	Расширенный статус платежа (status_extended)
79150000000	Успешный (success)	Успешный (success_success)
79030000000	Неуспешный (failure)	Недостаточно средств (failure_no_money)
79260000000	Случайный	Случайный

Для банковских карт:

Номер карты	Статус платежа (status)	Расширенный статус платежа (status_extended)
4242424242424242	Успешный (success)	Успешный (success_success)
5555555555554444	Неуспешный (failure)	Недостаточно средств (failure_no_money)
2201382000000013	Случайный	Случайный

CVV — любые 3 цифры. Срок действия карты — любой.

Пока включен режим тестирования, данные реальных карт приведут к ошибке платежа.

Не забудьте установить test=0 при переходе в рабочий режим.

5.6 API-запросы от ТСП к Миксплат

Запросы от ТСП к Миксплат осуществляются методом POST по протоколу HTTPS. Параметры запроса передаются в виде JSON словаря в теле запроса. Все строки передаются в кодировке UTF-8.

Параметр запроса считается незаданным в двух случаях:

Он отсутствует в JSON словаре
Он присутствует в JSON словаре, но его значение равно null

В большинстве случаев длительность выполнения запроса к Миксплат не превышает 1 секунды, но в отдельных случаях запрос может выполняться до 20 секунд. Удостоверьтесь, что в вашей HTTP библиотеке установлен таймаут ожидания ответа не менее 20 секунд.

Ответ от Миксплат представляет собой JSON словарь, в котором присутствует параметр result (string), который определяет успешность выполнения запроса (см. раздел 6.3). Все строки передаются в кодировке UTF-8.

При успешном выполнении запроса result="ok", в ответе содержатся дополнительные параметры, описанные в разделах документации для соответствующих запросов.

Обратите внимание, что result="ok" означает успешность HTTPS-запроса, а не статус платежа (он определяется параметром status).

Пример успешного ответа Миксплат

{
    "result" : "ok",
    "param1" : "value1",
    "param2" : "value2",
    "param3" : "value3",
    ...
    "paramN" : "valueN"
}

При неуспешном выполнении запроса result!="ok" в ответе присутствует только один дополнительный параметр error_description (string), в котором содержится текстовое описание возникшей ошибки.

Пример неуспешного ответа Миксплат

{
    "result"  : "error_payment_not_found",
    "error_description" : "Payment 123 not found"
}

5.7 Уведомления от Миксплат к ТСП

Миксплат отправляет уведомления со следующих IP адресов:

185.77.233.27
185.77.233.29

Уведомления от Миксплат к ТСП осуществляются POST запросом на URL обработчика ТСП, указанный в настройках проекта в ЛК.

Параметры уведомления передаются в виде JSON словаря в теле запроса. Все строки передаются в кодировке UTF-8.

Миксплат ожидает ответа от ТСП в течение 40 секунд.

В ответ на уведомление от Миксплат ТСП должен передать JSON словарь с параметрами ответа. В ответе обязательно присутствует параметр result (string), который передаёт результат обработки уведомления на стороне ТСП (см. 6.4). Также в ответе могут передаваться дополнительные параметры, описанные в разделах документации для соответствующих уведомлений. Все строки передаются в кодировке UTF-8.

Обратите внимание, что ТСП следует всегда выдавать result="ok", что означает успешность HTTPS-запроса к ТСП, а не статус платежа.

Пример успешного ответа ТСП

{
    "result" : "ok",
    "param1" : "value1",
    "param2" : "value2",
    "param3" : "value3",
    ...
    "paramN" : "valueN"
}

Если HTTP код ответа отличен от 200 или возвращён некорректный JSON, то это считается неудачной попыткой уведомления.

В случае, если попытка уведомления была неудачной, то будут совершены повторные попытки (всего 10 попыток) передачи статусов на URL Обработчика ТСП с постепенно увеличивающимися интервалами между ними:

2	+5 секунд
3	+5 секунд
4	+5 секунд
5	+10 секунд
6	+10 секунд
7	+10 секунд
8	+5 минут
9	+1 час
10	+12 часов

После 10-й попытки вызова Обработчика ТСП останавливаются, но вы всегда можете получить статус платежа посредством метода get_payment_status.

5.1 Одноэтапные платежи​

5.2 Двухэтапные платежи​

5.3 Подписки​

5.4 Рекуррентные платежи​

5.5 Тестовые платежи​

5.6 API-запросы от ТСП к Миксплат​

5.7 Уведомления от Миксплат к ТСП​