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

Обновлено 14 февраля 2025

SmartPay

SmartApp API

Для смартапов, созданных через 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}.