ym88659208ym87991671
API SmartPay | Документация SmartMarket
Skip to main content

API SmartPay

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

  1. Создание счета.
  2. Проведение платежа.
  3. Получение статуса.
  4. Подтверждение оплаты.
  5. Отмена счеты.
  6. Возврат платежа: полный и частичный.

Авторизация

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

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

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

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

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

Пример тела запроса:

{
"user_id": {
"partner_client_id": "43u111539f0q"
},
"ptype": 0,
"invoice": {
"purchaser": {
"email": "qq@dd.eof",
"phone": "9123456789",
"contact": "email"
},
"delivery_info": {
"address": {
"country": "RU",
"city": "Москва",
"address": "ул. Вавилова, 19, офис 1"
},
"delivery_type": "courier",
"description": "Перезвонить за 1,5 часа"
},
"invoice_params": [
{
"key": "packageName",
"value": "com.MashaAndTheBear.HairSalon"
}
],
"order": {
"order_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"order_number": "145",
"order_date": "2020-04-29T08:17:03+03",
"service_id": "223",
"amount": 11836,
"currency": "RUB",
"purpose": "Покупка в игре «Маша и Медведь, салон красоты Чародейка».",
"description": "Покупка внутриигрового контента в игре «Маша и Медведь, салон красоты Чародейка».",
"language": "ru-RU",
"expiration_date": "2022-05-20T10:07:44.337Z",
"tax_system": 0,
"order_bundle": [
{
"position_id": 1,
"name": "Кучка из 100 кристаллов для использования при нырянии",
"item_params": [
{
"key": "packageName",
"value": "com.MashaAndTheBear.HairSalon"
}
],
"quantity": {
"value": 1.05,
"measure": "кг."
},
"item_amount": 11836,
"currency": "RUB",
"item_code": "com.MashaAndTheBear.HairSalon.crystal100",
"item_price": 11836,
"discount_type": "percent",
"discount_value": 5.25,
"interest_type": "agentPercent",
"interest_value": 15.105,
"tax_type": 6,
"tax_sum": 2367,
"image": "https://i-love-png.com/images/grim-reaper-icon.png"
}
]
}
}
}

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

{
"error": {
"user_message": "",
"error_description": "",
"error_code": "0"
},
"invoice_id": "1234567890"
}

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

Для оплаты счета используйте запрос POST /invoices/{invoice_id}.

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

{
"user_id": {
"partner_client_id": "43u111539f0q"
},
"operations": [
{
"operation": "payment",
"code": "sbrf_spasibo",
"value": "19800"
}
],
"device_info": {
"device_platform_type": "iOS",
"device_platform_version": "13.6.1",
"device_model": "iPhone 7",
"device_manufacturer": "Apple",
"device_id": "83c3f257-46d8-41fe-951b-f79d04e288c2",
"surface": "SBOL",
"surface_version": "11.5.0"
},
"return_url": "string",
"fail_url": "string",
"return_deeplink": "string"
}

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

{
"error": {
"user_message": "",
"error_description": "",
"error_code": "0"
},
"form_url": "https://3dsec.sberbank.ru/payment/merchants/test/payment_ru.html?mdOrder=70906e55-7114-41d6-8332-4609dc6590f4",
"deeplink": "sberbankonline://connect?addcard",
"product": {
"provider": "applestore",
"product_code": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"quantity": 1.5,
"user_uid": {
"user_uid": "d43f2eb6-f299-439b-8a3b-43b114531f0d"
},
"params": [
{
"key": "packageName",
"value": "com.MashaAndTheBear.HairSalon"
}
],
"inapp_type": "consumable"
}
}

При завершении оплаты приходит сообщение PAY_DIALOG_FINISHED, которое позволяет определить статус счета. Сообщение можно получить независимо от типа платежа — одностадийный или двухстадийный.

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

После создания счета вы можете проверить, успешно ли прошел платеж. Для этого используйте следующий запрос: GET /invoices/{invoice_id}.

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

curl -X GET "https://smartmarket.online.sberbank.ru/smartpay/v1/invoices/ad454ffg-6c54-4b01-90e6-d701748f0851?inv_status=executed&wait=50" -H "accept: application/json"

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

{
"error": {
"user_message": "",
"error_description": "",
"error_code": "0"
},
"invoice_id": "1234567890",
"invoice_date": "2020-04-29T08:18:03+03",
"invoice_status": "created",
"invoice": {
"purchaser": {
"email": "qq@dd.eof",
"phone": "9123456789",
"contact": "email"
},
"delivery_info": {
"address": {
"country": "RU",
"city": "Москва",
"address": "ул. Вавилова, 19, офис 1"
},
"delivery_type": "courier",
"description": "Перезвонить за 1,5 часа"
},
"invoice_params": [
{
"key": "packageName",
"value": "com.MashaAndTheBear.HairSalon"
}
],
"order": {
"order_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"order_number": "145",
"order_date": "2020-04-29T08:17:03+03",
"service_id": "223",
"amount": 11836,
"currency": "RUB",
"purpose": "Покупка в игре «Маша и Медведь, салон красоты Чародейка».",
"description": "Покупка внутриигрового контента в игре «Маша и Медведь, салон красоты Чародейка».",
"language": "ru-RU",
"expiration_date": "2022-05-20T12:55:16.118Z",
"tax_system": 0,
"trade_name": "Romashka",
"visual_name": "Покупка/продление подписки",
"org_name": "ООО Ромашка",
"org_inn": "1234567890",
"visual_amount": "1 500,45 ₽",
"order_bundle": [
{
"position_id": 1,
"name": "Кучка из 100 кристаллов для использования при нырянии",
"item_params": [
{
"key": "packageName",
"value": "com.MashaAndTheBear.HairSalon"
}
],
"quantity": {
"value": 1.05,
"measure": "кг."
},
"item_amount": 11836,
"currency": "RUB",
"item_code": "com.MashaAndTheBear.HairSalon.crystal100",
"item_price": 11836,
"discount_type": "percent",
"discount_value": 5.25,
"interest_type": "agentPercent",
"interest_value": 15.105,
"tax_type": 6,
"tax_sum": 2367,
"image": "https://i-love-png.com/images/grim-reaper-icon.png"
}
]
}
},
"image": "https://i-love-png.com/images/grim-reaper-icon.png",
"payment_info": {
"payment_date": "2022-05-20T12:55:16.118Z",
"payment_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
"payment_params": {
"key": "googlePurchaseToken",
"value": "ameinkbophchljaejnocadib.AO-J1Oyrh3GSPGrLocZlW4UXiilTv_fMDz8Wpjadky8-26BhzBPMiwtoKql706e3ntW2BQNdl9WSiBjsjLebCcz3BhFyM7FVxDnOB1TFeeA0SHnco9j8G_OZVxghv7bwXWLgWsaUUGfw"
},
"device_info": {
"device_platform_type": "iOS",
"device_platform_version": "13.6.1",
"device_model": "iPhone 7",
"device_manufacturer": "Apple",
"device_id": "83c3f257-46d8-41fe-951b-f79d04e288c2",
"surface": "SBOL",
"surface_version": "11.5.0"
},
"loyalty_info": {
"service_code": "sbrf_spasibo",
"service_name": "Сбербанк Спасибо",
"change_rate": 1,
"payment_bonus": 19800,
"award_bonus": 21850,
"image": "https://i-love-png.com/images/grim-reaper-icon.png"
},
"card_id": "ad454ffg-6c54-4b01-90e6-d701748f0851",
"name": "Главная",
"paysys_code": "RBS-shortname",
"masked_pan": "**1111",
"expiry_date": "201912",
"cardholder": "Ivan Petrov",
"payment_system": "Visa",
"payment_system_image": "https://smartmarkettestift.online.sberbank.ru/icons/logo_visa.png",
"image": "https://smartmarkettestift.online.sberbank.ru/icons/sberbank_mastercard_league_legends.jpeg",
"paysys": "Эквайринг Сбербанка",
"paysys_image": "https://www.sberbank.ru/common/img/uploaded/redirected/s_m_business/acquiring/assets/images/intro@2x.png",
"payment_way": "Sber Pay",
"payment_way_code": "SberPay",
"payment_way_logo": "https://cdn1.telegram.one/i/f7640dada78306b1c993e04001b8738d/828b1eb30921659e22e53a9edc92c4c4/24e01830d213d75deb99c22b9cd91ddd",
"bank_info": {
"bank_name": "ПАО Сбербанк",
"bank_country_code": "RU",
"bank_country_name": "Россия",
"bank_image": "https://emoji.slack-edge.com/TKK9DHNCV/sber/ad2df81a6cd9812d.png"
}
},
"payment_methods": {
"user_message": "Для подключения подписки сохраните банковскую карту в мобильном приложении СалютАпп",
"methods": [
{
"method": "QR",
"action": "Оплатить по QR-коду"
}
]
}
}

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

Для успешного завершения двухстадийного платежа по счету используйте запрос PUT /invoices/{invoice_id}.

Параметры запроса будут зависеть от того, на полную или не полную сумму делается подтверждение.

Параметры для полной суммы:

Если необходимо завершить покупку на полную сумму, достаточно передать в качестве path-параметра значение для invoice_id.

Параметры для неполной суммы:

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

Пример запроса для неполной суммы:

{
"invoice": {
"order": {
"amount": 11836,
"currency": "RUB",
"order_bundle": [
{
"position_id": 1,
"name": "Кучка из 100 кристаллов для использования при нырянии",
"item_params": [
{
"key": "packageName",
"value": "com.MashaAndTheBear.HairSalon"
}
],
"quantity": {
"value": 1.05,
"measure": "кг."
},
"item_amount": 11836,
"currency": "RUB",
"item_code": "com.MashaAndTheBear.HairSalon.crystal100",
"item_price": 11836,
"discount_type": "percent",
"discount_value": 5.25,
"interest_type": "agentPercent",
"interest_value": 15.105,
"tax_type": 6,
"tax_sum": 2367,
"image": "https://i-love-png.com/images/grim-reaper-icon.png"
}
]
}
}
}

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

{
"error": {
"error_code": "0",
"user_message": "Оплата проведена",
"error_description": ""
}
}

Отмена счета

Для отмены счета используйте запрос DELETE /invoices/{invoice_id}.

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

{
"invoice_id": "1234567890",
"author": ""
}

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

{
"error": {
"error_code": "0",
"user_message": "Отмена выполнена",
"error_description": ""
}
}

Полный возврат платежа

Для возврата средств на полную сумму используйте запрос PATCH /invoices/{invoice_id}.

Для возврата на полную сумму необходимо передать параметр invoice_id в качестве path-параметра.

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

{
"invoice_id": "1234567890",
"author": ""
}

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

{
"error": {
"error_code": "0",
"user_message": "Возврат выполнен",
"error_description": ""
}
}

Частичный возврат платежа

Для оформления частичного возврата суммы используйте запрос PATCH /invoices/{invoice_id}. Возврат можно сделать только из статуса confirmed. В рамках одной операции частичные возвраты можно делать неограниченное количество раз. Главное условие — возвращаемый товар должен совпадать по составу и количеству с товаром из корзины.

Для частичного возврата необходимо передать invoice_id в качестве path-параметра и корзину возвращаемых товаров в теле запроса.

Пример тела запроса:

{
"invoice": {
"order": {
"current_amount": 20038,
"refund_amount": 11836,
"currency": "RUB",
"order_bundle": [
{
"position_id": 1,
"name": "Кучка из 100 кристаллов для использования при нырянии",
"quantity": {
"value": 1.05,
"measure": "кг."
},
"item_amount": 11836,
"item_code": "com.MashaAndTheBear.HairSalon.crystal100"
}
]
}
}
}

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

{
"error": {
"error_code": "0",
"user_message": "Возврат выполнен",
"error_description": ""
}
}

Коды ответа

В ответ на каждый запрос могут возвращаться следующие коды:

Код ответа
Описание
200
Запрос обработан успешно
400
Один из параметров в запросе передан в некорректном формате, либо формат запроса некорректный
403
Внутренняя ошибка работы сервиса. Обратитесь в поддержку для устранения неполадки
Обновлено 15 июля 2022

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

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