Для смартапов, созданных через SmartApp API, доступно подключение одностадийных и двухстадийных платежей.
Перед подключением
Получение токена
В заголовке каждого запроса необходимо передавать токен API Key в следующем формате:
- Тип токена: Bearer
- Имя заголовка: Authorization
Подробнее о получении параметров авторизации в разделе Проект SmartPay.
URL для запросов
Все запросы необходимо отправлять на следующий URL:
https://smartpay.devices.sberbank.ru/smartpay/v1/
Создание счета
Для создания счета на проведение платежа используйте запрос POST /invoices.
Проведение платежа
Если вы подключаете сценарий через webhook, то для проведения платежей вы можете использовать следующие команды:
POLICY_RUN_APP— запрос на проведение платежа.POST /invoices/{invoice_id}– запрос на оплаты счета.PAY_DIALOG_FINISHED— событие о завершении платежа.
Вызов платежного сценария
Для вызова платежного сценария и проведения оплаты используйте сообщение POLICY_RUN_APP, сформированное следующим образом:
Пример вызова:
{
"command": "POLICY_RUN_APP",
"nodes": {
"server_action": {
"app_info": {
"systemName": "payment_app"
},
"parameters": {
"invoice_id": "3000",
"app_info": {
"projectId": "0da9a4a0-cb52-4490-afce-4f535c9d1eb5"
}
}
}
}
}
В параметре projectId укажите идентификатор вашего смартапа в Studio. В параметре invoice_id укажите идентификатор счета.
Формат результата оплаты
В результате оплаты, ассистент вернет сообщение PAY_DIALOG_FINISHED, которое позволяет определить статус счета. Событие можно получить независимо от типа платежа — одностадийный или двухстадийный.
В событии передается response_code с кодом ответа. Этот код является информационным и говорит о наиболее вероятном состоянии оплаты. После получения кода ответа нужно отправить запрос на проверку статуса счета, затем можно принимать решение о формировании ответа клиенту и дальнейших шагах. В случае одностадийного платежа процесс оплаты завершается после получения этого стауса. Возможные значения response_code:
- 0 — успешная оплата;
- 1 — неожиданная ошибка;
- 2 — пользователь закрыл смартап. При получении этого кода необходимо дополнительно отправить запрос на проверку статуса платежа, чтобы отобразить результат пользователю;
- 3 — невозможно начать оплату, так как отображается другой сценарий оплаты;
- 4 — время оплаты счета истекло;
- 5 — оплата отклонена бэкендом;
- 6 — состояние оплаты неизвестно;
- 7 — оплата для данной поверхности недоступна.
Чтобы принять решение о формировании заказа необходимо дополнительно отправить запрос на проверку статуса счета, т.к. получение события PAY_DIALOG_FINISHED не означает, что счет перешел в финальный статус.
Пример сообщения:
"payload": {
...
"server_action": {
"action_id": "PAY_DIALOG_FINISHED",
"parameters": {
"payment_response":
{
"response_code": 0,
"invoice_id": "***ID****"
}
"app_info":
{
"projectId": "**",
"systemName": "**"
}
}
}
}
...
}
Получение статуса
После создания счета вы можете проверить успешно ли прошел платеж по счету, не отменил ли пользователь заказ и т. д. Для этого используйте запрос на получение статуса счета GET /invoices/{invoice_id}.
Подтверждение платежа
Для успешного завершения двухстадийного платежа по счету используйте запрос PUT /invoices/{invoice_id}.
Отмена счета
Для отмены счета на оплату и возврата средств используйте запрос DELETE /invoices/{invoice_id}.