Сервис CASHOFF позволяет совершать платежи в рублях через ряд провайдеров (банков для физических и юридических лиц). Работает эта возможность поверх функциональности импорта данных и требует для работы существующий авторизованный профиль. Совершение платежа состоит из следующих шагов:
- Добавление профиля в систему
- Обновление авторизации и списка продуктов
- Выполнение запроса на создание платежа POST /profiles/{profile_id}/payments/rub/add
- Выполнение запроса на подтверждение платежа POST /profiles/{profile_id}/payments/rub/{payment_id}/confirm
- (опционально) Отслеживание статуса платежа
Обновление авторизации и списка продуктов
Первым делом для совершения платежа необходимо авторизовать профиль, а так же загрузить по нему список продуктов. Совершать рублевые платежи возможно только по продуктам, у которых признак available_ops.payment_rub равен true. Этот атрибут по умолчанию не заполняется при обновлении данных, его нужно запросить явно через атрибут шага импорта продуктов payment_rub:
{
"accounts": {
"payment_rub": true
}
}
(подробнее о настройке шагов обновления можно прочитать в разделе Импорт данных из внешних провайдеров)
Признак сбрасывается, если обновить продукты без payment_rub=true, по этому последнее запрошенное обновление должно быть с payment_rub.
Создание платежа
Платеж создается запросом POST /profiles/{profile_id}/payments/rub/add, в котором нужно указать идентификатор продукта account_id, с которого совершается перевод, а так же атрибут doc с реквизитами платежа. Данный запрос создаст объект платежа в CASHOFF, а так же запустит создание платежа в провайдере в фоновом режиме. Список платежей по профилю можно получить запросом GET /profiles/{profile_id}/payments/rub (или конкретный GET /profiles/{profile_id}/payments/rub/{payment_id})
Результат заведения платежа в системе провайдера придет через нотификацию profile.rub_payment.add (на которую нужно подписаться):
{
"event": "profile.rub_payment.add",
"data": {
"result": "confirm_required",
"confirm": {
"message": "Введите код подтверждения операции"
},
"payment": {
"created": "2019-12-24T12:32:14Z",
"changed": "2019-12-24T12:32:14Z",
"id": 12,
"ext_id": "38c443c6ac424d3e8ae4261620d505b3",
"account_id": 31880,
"status": "at_confirmation"
},
"profile": {
"created": "2019-12-23T14:41:06Z",
"changed": "2019-12-24T12:32:14Z",
"id": 8675,
"user_id": 6604,
"provider": {
"id": 153,
"key": "sber-sme",
"name": "Сбербанк Бизнес Онлайн",
"type": "bank_sme",
"logo": "https://cashoff.ru/static/media/institutions_logo/sber_36.svg"
}
"session": {
"key": "ae2a33e3c9ae4de8bf0dea0c4f930785",
"status": "ok"
},
"status": "ok",
"update_done_at": "2019-12-24T12:32:14Z",
"update_started_at": "2019-12-23T14:42:39Z"
}
}
}
Исход процедуры содержится в поле result, так же в нотификации будет указан объект профиля и платежа. Таблица исходов и предполагаемых действий:
| Код исхода | Описание | Дальнейшие действия |
|---|---|---|
| accepted | платеж проверен и принят банком | На этом заведение платежа завершается, подтверждение не требуется |
| confirm_required | платеж проверен, но требует подтверждения | Требуется выполнить следующий шаг, подтверждение платежа. |
| denied | платеж не принят | Платеж с заданными реквизитами и продуктом не принят. Нужно внести изменения и создать новый. |
| profile_error | общая ошибка работы с профилем | Общая ошибка работы с провайдером. Аналогична ошибке импорта данных |
| not_authorized | профиль не авторизован | Профиль не авторизован, необходимо авторизоваться (запустить обновление профиля с update_stages=["auth"] |
В случае успеха в ответе может придти значение комиссии в атрибуте commission.
Подтверждение платежа
Подтверждение платежа необходимо, если создание завершилось статусом confirm_required (подтверждение будет требоваться в абсолютом большинстве банков). Для подтверждения платежа необходимо выполнить запрос POST /profiles/{profile_id}/payments/rub/{payment_id}/confirm с кодом подтверждения, который клиент получит от банка (sms/карточка с ключами/генератор кодов). Как и в случае с созданием, подтверждение будет выполнено в фоновом режиме, а результат будет доставлен нотификацией profile.rub_payment.confirm (на которую то же нужно подписаться). Формат нотификации аналогичен созданию, как и исходы операции (за минусом того, что статуса confirm_required не будет, т.к. платеж уже в этом статусе).
Отслеживание статуса заведенных платежей
CASHOFF может отслеживать статус проведения заведенных платежей. Для этого надо в update_stages обновления добавить шаг payments: это приведет к тому, что по всем заведенным в CASHOFF платежам (кроме тех, что в финальном статусе) будет обновлен статус из провайдера. Далее статус можно прочитать в информации по платежу (GET /profiles/{profile_id}/payments/rub / GET /profiles/{profile_id}/payments/rub/{payment_id}).