ym88659208ym87991671
SmartPay API | Документация для разработчиков
Documentation Powered by Redocly

SmartPay API (1.02)

Скачать OpenAPI-спецификацию:Скачать

Независимо от способа создания смартапа (через Code, Graph, webhook и т. д.), для подключения приема платежей вы можете использовать методы SmartPay API.

Авторизация

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

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

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

Платежи

Операции связанные с формированием и оплатой счетов.

Получить список счетов клиента

get/invoices

Получить список счетов

QUERY-ПАРАМЕТРЫ
partner_client_id (object) or user_uid (object) or encrypted_sub_id (object) or partner_client_sub_id (object)

Идентификатор пользователя, заполняется только если передается токен партнера, для фильтрации по пользователю. Если передается токен клиента, то данные автоматически фильтруются по пользователю

date_from
string <date>
Example: date_from=2020-04-29

Начальная дата создания счета

date_to
string <date>
Example: date_to=2020-08-31

Конечная дата создания счета

invoice_status
string
Example: invoice_status=created,executed

Список статусов счетов, которые нужно отдать в выборке. Если отсутствует, то отдаются только счета со статусом confirmed и paid. Возможные значения all,created,executed,cancelled,paid,confirmed,reversed,refunded

amount_from
integer
Example: amount_from=12345

Сумма счета с, в копейках

amount_to
integer
Example: amount_to=112345

Сумма счета по, в копейках

masked_pan
string
Example: masked_pan=0429

4 последних цифры номера карты

order_num
string
Example: order_num=AGR-445611

Номер заказа в системе магазина, для клиента

page
integer
Example: page=1

Results page you want to retrieve (0..N)

size
integer
Example: size=20

Number of records per page.

Ответы

Пример ответа

Content type
application/json
{}

Создание счета на оплату

post/invoices

Создайте счет на оплату.

Схема запроса: application/json
partner_client_id (object) or user_uid (object) or encrypted_sub_id (object) or partner_client_sub_id (object)
ptype
integer
Enum: 0 1

Тип оплаты счета:

  • 0 — одностадийная оплата.
  • 1 — двухстадийная оплата.

Если параметр не указан, формируется одностадийная оплата.

object

Информация о создаваемом счете

Ответы

Пример запроса

Content type
application/json
{
  • "user_id": {
    },
  • "ptype": 0,
  • "invoice": {
    }
}

Пример ответа

Content type
application/json
{
  • "invoice_id": 1234567890,
  • "error": {
    }
}

Получение данных по счету

get/invoices/{invoice_id}

Получите данные по invoice_id. Возможен поиск счета по паре service_id+order_id, если invoice_id неизвестен. Для этого нужно указать invoice_id = 0, а в запросе — service_id и order_id.

PATH-ПАРАМЕТРЫ
invoice_id
required
string
Example: 1234567890

ID счета

QUERY-ПАРАМЕТРЫ
service_id
string
Example: service_id=1234

ID сервиса для поиска. Обычно используется в паре с параметром order_id

order_id
string
Example: order_id=d290f1ee-6c54-4b01-90e6-d701748f0852

Идентификатор заказа, переданный при создании счета

inv_status
string
Example: inv_status=executed

Статус счета для начала отслеживания изменений.

Если при вызове запроса счет найден, статус равен значению этого параметра, то ответ отдается только при смене статуса или по таймауту. Используется в "long polling" запросах для отслеживания факта проведения оплаты

wait
integer
Example: wait=50

Время в секундах, которое источник запроса будет ожидать до смены статуса счета. Используется в "long polling" запросах для отслеживания факта проведения оплаты.

device_platform_type
string
Example: device_platform_type=iOS

Наименование операционной системы устройства

device_platform_version
string
Example: device_platform_version=13.6.1

Версия операционной системы устройства

device_model
string
Example: device_model=iPhone 7

Модель устройства

device_manufacturer
string
Example: device_manufacturer=Apple

Производитель устройства

device_id
string
Example: device_id=83c3f257-46d8-41fe-951b-f79d04e288c2

Серийный номер устройства

surface
string
Example: surface=SBOL

Поверхность

surface_version
string
Example: surface_version=11.5.0

Версия ПО

Ответы

Пример ответа

Content type
application/json
{
  • "error": {
    },
  • "invoice_id": 1234567890,
  • "invoice_date": "2020-04-29T08:18:03+03",
  • "invoice_status": "created",
  • "invoice": {
    },
  • "image": "https://developers.sber.ru/docs/img/fork-page/assistant-salute-grey.png",
  • "payment_info": {},
  • "payment_methods": {
    }
}

Запуск оплаты счета

post/invoices/{invoice_id}

Запустите оплату счета, указав платежный инструмент и дополнительные данные для оплаты.

PATH-ПАРАМЕТРЫ
invoice_id
required
string
Example: 1234567890

ID счета

Схема запроса: application/json

Информация о платежном инструменте

partner_client_id (object) or user_uid (object) or encrypted_sub_id (object) or partner_client_sub_id (object)
Array of objects (operation) [ items ]
object (device)

Информация об устройстве

return_url
string

URL, на который требуется переадресовать пользователя в случае успешной оплаты.

Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). Указывается либо return_url, либо return_deeplink

fail_url
string

URL, на который требуется переадресовать пользователя в случае неуспешной оплаты.

Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru).

return_deeplink
string

Deeplink, на который требуется переадресовать пользователя после успешной оплаты через мобильное приложение.

Указывается либо return_url, либо return_deeplink

Ответы

Пример запроса

Content type
application/json
{
  • "user_id": {
    },
  • "operations": [
    ],
  • "device_info": {
    },
  • "return_url": "string",
  • "fail_url": "string",
  • "return_deeplink": "string"
}

Пример ответа

Content type
application/json
{}

Подтверждение оплаты счета для двустадийного платежа

put/invoices/{invoice_id}

Инициатор присылает полное или частичное подтверждение для завершения оплаты счета при двухстадийной оплате. Счет должен находиться в состоянии 3 «Деньги временно заблокированы». По завершении счет переходит в состояние 0 «Оплачен»

PATH-ПАРАМЕТРЫ
invoice_id
required
string
Example: 1234567890

ID счета

Заголовки
author
string

Пользователь, который производит изменения

Схема запроса: application/json

Инфо о подтверждении/отмене счета

object

Информация о созданном счете

required
object (order_confirm)
amount
required
integer

Сумма счета без разделителя, в копейках. Например, 1 рубль передается в этом поле как 100.

Если в запросе указывается корзина товаров, то это поле должно быть равно сумме стоимости всех товаров в корзине sum(order_bundle.item_amount).

currency
required
string

Код валюты в формате ISO 4217.

Поддерживается только значение RUB

Array of objects (bundle_param) [ items ]

Описание корзины покупок для передачи в налоговую и формирования фискального чека.

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

Обязательно нужно указывать в счетах на оплату, иначе оплата не состоится

Ответы

Пример запроса

Content type
application/json
{
  • "invoice": {
    }
}

Пример ответа

Content type
application/json
{
  • "error": {
    }
}

Отмена оплаты счета при двустадийном платеже

del/invoices/{invoice_id}

Инициатор присылает запрос на отмену оплаты счета при двухстадийной оплате. Счет должен находиться в состоянии 3 «Деньги временно заблокированы». По завершении счет переходит в состояние 6 «Отменен»

PATH-ПАРАМЕТРЫ
invoice_id
required
string
Example: 1234567890

ID счета

Заголовки
author
string

Пользователь, который производит изменения

Ответы

Пример ответа

Content type
application/json
{
  • "error": {
    }
}

Полный или частичный возврат

patch/invoices/{invoice_id}

Инициатор присылает запрос на возврат, полный или частичный. Счет должен находиться в состоянии 0 «Оплачен». Запрос можно выполнять несколько раз, вплоть до полного возврата. Если произведен полный возврат, то счет переходит в состояние 7 «Возвращен»

PATH-ПАРАМЕТРЫ
invoice_id
required
string
Example: 1234567890

ID счета

Заголовки
author
string

Пользователь, который производит изменения

Схема запроса: application/json

Инфо об отмене счета. В частности, отменяемая сумма и корзина возврата

object

Корзина возврата

required
object (order_refund)

Данные заказа для возврата

current_amount
required
integer

Текущая сумма счета, в копейках, без разделителей.

Например, 123р.00коп. = 12300

refund_amount
required
integer

Сумма возврата, в копейках, без разделителей.

Например, 123р.00коп. = 12300

currency
string

Код валюты в формате ISO 4217.

Поддерживается только значение RUB

required
Array of objects (bundle_param_refund) [ items ]

Состав заказа (элементы корзины)

Ответы

Пример запроса

Content type
application/json
{
  • "invoice": {
    }
}

Пример ответа

Content type
application/json
{
  • "error": {
    }
}

Карты

Операции с карточными связками.

Получить список карт клиента

get/cards

Получить список связок для клиента.

QUERY-ПАРАМЕТРЫ
partner_client_id (object) or user_uid (object) or encrypted_sub_id (object) or partner_client_sub_id (object)

Идентификатор пользователя, заполняется только если передается токен партнера, для фильтрации по пользователю. Если передается токен клиента, то данные автоматически фильтруются по пользователю

Ответы

Пример ответа

Content type
application/json
{}

Добавить банковскую карту клиента

post/cards

Добавить связку для банковской карты. Затем эту связку можно использовать для безакцептной оплаты. По факту это создание счета на оплату, например, 1 руб. для проверки валидности карты, после подтверждения оплаты счет автоматически удаляется.

Схема запроса: application/json

return_urls

partner_client_id (object) or user_uid (object) or encrypted_sub_id (object) or partner_client_sub_id (object)
object (device)

Информация об устройстве

required
object (order_id)
code
string
Enum: "new" "app2sbol"

Код инструмента

return_url
string

URL, на который требуется переадресовать пользователя в случае успешной оплаты.

Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru). Указывается либо return_url, либо return_deeplink

fail_url
string

URL, на который требуется переадресовать пользователя в случае неуспешной оплаты.

Адрес должен быть указан полностью, включая используемый протокол (например, https://test.ru вместо test.ru).

return_deeplink
string

Deeplink, на который требуется переадресовать пользователя после успешной оплаты через мобильное приложение.

Указывается либо return_url, либо return_deeplink

Ответы

Пример запроса

Content type
application/json
{
  • "user_id": {
    },
  • "device_info": {
    },
  • "order_id": {
    },
  • "code": "app2sbol",
  • "return_url": "string",
  • "fail_url": "string",
  • "return_deeplink": "string"
}

Пример ответа

Content type
application/json
{}

Удалить банковскую карту

del/cards/{card_id}

Удалить карту.

PATH-ПАРАМЕТРЫ
card_id
required
string
Example: ad454ffg-6c54-4b01-90e6-d701748f0851

ID карты

QUERY-ПАРАМЕТРЫ
partner_client_id (object) or user_uid (object) or encrypted_sub_id (object) or partner_client_sub_id (object)

Идентификатор пользователя, заполняется только если передается токен партнера, для фильтрации по пользователю. Если передается токен клиента, то данные автоматически фильтруются по пользователю

Ответы

Пример ответа

Content type
application/json
{
  • "error": {
    }
}
ПАО Сбербанк использует cookie для персонализации сервисов и удобства пользователей.
Вы можете запретить сохранение cookie в настройках своего браузера.