Запрос check

С проверки и резервирования платежа начинается взаимодействие мерчанта с процессингом PlatBox. В процессе обработки этого запроса мерчант должен осуществить следующие действия:

  1. Подтвердить подпись процессинга PlatBox, чтобы удостоверить подлинность сообщения.
  2. Проверить наличие и актуальность учётной записи пользователя, инициировавшего платёж.
  3. Проверить доступность товаров и услуг, представленных в заказе пользователя.
  4. Удостовериться в правильности указания суммы и валюты платежа.
  5. Зарезервировать идентификатор транзакции в своей системе.

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

Приведём иллюстрацию того, что следует ожидать мерчанту на примере запроса на резервирование платежа пользователем player31337 в регионе 4 в пользу персонажа с ником Jane Doe, которые захотел заказ с номером 314542341:


    {
        "action": "check",
        "platbox_tx_id": "42",
        "platbox_tx_created_at": "2014-10-12T00:13:37Z",
        "product": "legend_of_zelda",
        "payment" : {
            "amount": 10000,
            "currency": "RUB",
            "exponent": 2
        },
        "account": {
            "id": "player31337",
            "location": 4,
            "additional": "Jane Doe"
        },
        "order": "314542341",
        "merchant_extra": {
            "proc_code": 564
        },
        "payer": {
            "id": "**********"
        }
    }

Поле в сообщении Обязательность Комментарий
action Да Тип запроса, в данном случае «check».
platbox_tx_id Да Идентификатор транзакции в процессинге PlatBox.
platbox_tx_created_at Да Время начала транзакции в процессинге PlatBox, в формате ISO 8601, UTC.
product Да Название продукта, который предоставляет мерчант, в процессинге PlatBox.
payment Да Детальная информация о сумме платежа.
> amount Да Сумма платежа в минорных единицах валюты, например, в копейках.
> currency Да Трёхсимвольный код валюты платежа, по стандарту ISO 4217.
> exponent Да Показатель десятичной степени числа минорных денежных единиц в одной мажорной денежной единице, в частности равен 2 (100 = 102) для рублей.
account Да Данные учётной записи пользователя, который приобретает некоторые товары или услуги.
> id Да Идентификатор учётной записи пользователя (например, номер телефона).
> location Нет Идентификатор региона расположения учётной записи. Может использоваться, если мерчант поддерживает несколько географически распределённых и при этом независимых экземпляров системы.
> additional Нет Любые дополнительные данные, необходимые для однозначной идентификации пользователя.
order Да Заказ пользователя, набор товаров или услуг, которые он хочет приобрести. То, что прислали в поле order во время открытия формы оплаты.
merchant_extra Нет Объект, содержащий произвольные данные, которые были согласованы с мерчантом в процессе подключения к процессингу PlatBox.
payer Нет Объект, содержащий данные плательщика, передача включается по договоренности.
> id Нет Идентификатор плательщика.

Примечание: символ > означает вложенность в JSON.

Необходимо понимать, что поле «order» может формироваться как на стороне, например, витрины на сайте PlatBox, как в приведённом выше примере, так и на стороне системы мерчанта (после чего происходит передача данных этого поля в сервис витрины платёжных методов PlatBox). В последнем случае, ничто не препятствует мерчанту передавать в этом поле произвольные JSON-объекты или просто текст с номером заказа:


    {
        "order": {
            "type": "order_id",
            "order_id": 9001
        }
    }

В ответ процессинг PlatBox, в случае успешного резервирования, ожидает следующий ответ:


    {
        "status": "ok",
        "merchant_tx_id": "1001",
        "merchant_tx_extra": {
        "pin_code": "17RT42"
        }
    }

Поле в сообщении Комментарий
status Результат операции, может содержать либо "ok", либо "error".
merchant_tx_id Идентификатор транзакции в системе мерчанта.
merchant_tx_extra Объект с любой дополнительной информацией по данной транзакции, который будет передан в последующих запросах к системе мерчанта.

А в случае неуспеха:


    {
        "status": "error",
        "code": 1001,
        "description": "Учётная запись не найдена"
    }

Поле с описанием ошибки необязательное и может содержать любую пояснительную информацию о случившейся проблеме. Настоятельно рекомендуется к заполнению, потому как может помочь при разборе инцидентов.

Список кодов ошибок в свою очередь фиксированный:

Код ошибки Описание
400 Неверный формат сообщения.
401 Некорректная подпись запроса.
406 Неверные данные запроса.
1000 Общая техническая ошибка.
1001 Учётная запись пользователя не найдена или заблокирована.
1002 Неверная валюта платежа.
1003 Неверная сумма платежа.
1005 Запрашиваемые товары или услуги недоступны/выбранный продукт не найден/неверные данные заказа пользователя.
2000 Платёж с указанным идентификатором уже зарезервирован.
2001 Платёж с указанным идентификатором уже проведен.
2002 Платёж с указанным идентификатором уже отменён.