ym88659208ym87991671
Прием платежей через SmartApp API | Документация для разработчиков
Skip to main content

Прием платежей через SmartApp API

note

Для смартапов, созданных через SmartApp API, доступно подключение одностадийных и двухстадийных платежей.

Перед подключением

Получение токена

В заголовке каждого запроса необходимо передавать токен API Key в следующем формате:

  • Тип токена: Bearer
  • Имя заголовка: Authorization

Подробнее о получении параметров авторизации в разделе Проект SmartPay.

URL для запросов

Все запросы необходимо отправлять на следующий URL:

https://smartmarket.online.sberbank.ru/smartpay/v1/

Создание счета

Для создания счета на проведение платежа используйте запрос POST /invoices.

Проведение платежа

Если вы подключаете сценарий через webhook, то для проведения платежей вы можете использовать следующие команды:

Вызов платежного сценария

Для вызова платежного сценария и проведения оплаты используйте сообщение 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 — оплата для данной поверхности недоступна.
note

Чтобы принять решение о формировании заказа необходимо дополнительно отправить запрос на проверку статуса счета, т.к. получение события 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}.

Обновлено 13 сентября 2022

Заметили ошибку?

Выделите текст и нажмите Ctrl + Enter, чтобы сообщить нам о ней