SberPay — Прием платежей в интернет-магазине по API ЮKassa

Docs

Подключить ЮKassa

SberPay

Особенности

Тип способа оплаты в API: sberbank
Сценарий подтверждения: Redirect, External, Mobile application и QR-код
Срок оплаты: 1 час
Холдирование: 7 дней
Код в реестре: SB
Возврат: да, частичный и полный
Срок возврата: моментально
Автоплатежи: да
Лимиты: минимальный размер платежа — 1 рубль, максимальный — 1 млн рублей

Сценарии интеграции

Готовые решения:

Самостоятельная интеграция:

Оплата с перенаправлением на страницу ЮKassa
Оплата с подтверждением через пуш-уведомление или смс
Оплата с перенаправлением в приложение банка (для мобильных устройств)
Оплата с перенаправлением в приложение банка (для десктопа)

Оплата с перенаправлением на страницу ЮKassa

В этом сценарии после создания платежа вы перенаправляете пользователя на страницу ЮKassa. На этой странице пользователь сканирует QR-код для перехода в мобильное приложение банка или вводит номер телефона, привязанный к СберБанку Онлайн, для получения пуша или смс.

Шаг 1. Создайте платеж , в объекте payment_method_data передайте тип sberbank, а в объекте confirmation передайте тип redirect и адрес страницы на вашей стороне, на которую пользователь вернется после оплаты (в параметре return_url).

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

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sberbank"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Заказ №72"
      }'

Шаг 2. Перенаправьте пользователя на страницу ЮKassa (ссылка на нее придет в параметре confirmation_url). На этой странице пользователь введет данные карты и подтвердит платеж.

Пример созданного объекта платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"pending",
   "paid":false,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "confirmation":{
      "type":"redirect",
      "confirmation_url":"https://yoomoney.ru/api-pages/v2/payment-confirm/epl?orderId=23d93cac-000f-5000-8000-126628f15141"
   },
   "created_at":"2018-07-18T10:51:18.139Z",
   "description":"Заказ №72",
   "metadata":{
      "order_id":"72"
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":false,
   "test":false
}

Если оплата через SberPay не прошла (например, не хватило денег), ЮKassa отобразит пользователю сообщение об ошибке и предложит попробовать оплатить еще раз.

Шаг 3. Дождитесь успешного завершения платежа: подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .

Пример успешного платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"succeeded",
   "paid":true,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "captured_at":"2021-04-12T13:59:33.681Z",
   "created_at":"2021-04-12T13:49:33.026Z",
   "income_amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "payment_method":{
      "type":"sberbank",
      "id":"22e12f66-000f-5000-8000-18db351245c7",
      "saved":false,
      "card":{
         "first6":"555555",
         "last4":"4444",
         "expiry_year":"2022",
         "expiry_month":"07",
         "card_type":"MasterCard"
         }
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":true,
   "refunded_amount":{
      "value":"0.00",
      "currency":"RUB"
   },
   "test":false,
   "authorization_details":{
     "rrn":"10000000000",
     "auth_code":"000000",
     "three_d_secure":{
       "applied":false
     }
   }
}

Шаг 4. Когда пользователь вернется на return_url, отобразите результат проведения платежа (успех или неудача) в зависимости от статуса платежа.

Оплата с подтверждением через пуш-уведомление или смс

В этом сценарии вы запрашиваете у пользователя номер телефона, который привязан к СберБанку Онлайн, и сообщаете пользователю, что на этот номер поступит пуш-уведомление или смс. Пользователь переходит по пуш-уведомлению или отвечает на смс для подтверждения платежа.

Шаг 1. Создайте платеж , в объекте payment_method_data передайте тип sberbank и телефон пользователя, привязанный к СберБанку Онлайн, а в объекте confirmation передайте тип external.

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

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sberbank",
          "phone": "79000000000"
        },
        "confirmation": {
          "type": "external",
        },
        "description": "Заказ №72"
      }'

Пример созданного объекта платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"pending",
   "paid":false,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
      "confirmation":{
      "type":"external"
   },
   "created_at":"2018-07-18T10:51:18.139Z",
   "description":"Заказ №72",
   "metadata":{
      "order_id":"72"
   },
   "payment_method":{
      "type":"sberbank",
      "phone":"79000000000"
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":false,
   "test":false
}

Шаг 2. Сообщите пользователю, что ему необходимо подтвердить оплату.

Пример успешного платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"succeeded",
   "paid":true,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "captured_at":"2021-04-12T14:03:20.155Z",
   "created_at":"2021-04-12T14:02:39.550Z",
   "income_amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "payment_method":{
      "type":"sberbank",
      "id":"22e12f66-000f-5000-8000-18db351245c7",
      "saved":false,
      "card":{
         "first6":"555555",
         "last4":"4444",
         "expiry_year":"2022",
         "expiry_month":"07",
         "card_type":"MasterCard"
         }
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":true,
   "refunded_amount":{
      "value":"0.00",
      "currency":"RUB"
   },
   "test":false,
   "authorization_details":{
     "rrn":"10000000000",
     "auth_code":"000000",
     "three_d_secure":{
       "applied":false
     }
   }
}

Шаг 4. Отобразите пользователю результат проведения платежа (успех или неудача) в зависимости от статуса платежа.

Оплата с перенаправлением в приложение банка (для мобильных устройств)

Только для приема платежей на мобильных устройствах (из мобильного приложения или с мобильной версии сайта).

По этому сценарию после создания платежа вы перенаправляете пользователя по диплинку в мобильное приложение СберБанка. В этом приложении пользователь подтверждает платеж.

Шаг 1. Создайте платеж , в объекте payment_method_data передайте тип sberbank, в объекте confirmation передайте тип mobile_application, а в параметре return_url — диплинк в ваше приложение (при платеже из мобильного приложения) или ссылку на страницу вашего магазина (при платеже из мобильной версии сайта).

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

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sberbank"
        },
        "confirmation": {
          "type": "mobile_application",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Заказ №72"
      }'

Пример созданного объекта платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"pending",
   "paid":false,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "payment_method":{
      "type":"sberbank"
   },
   "confirmation":{
      "type":"mobile_application",
      "confirmation_url":"sberpay://invoicing/v2?bankInvoiceId=8745798516524623ae94a4e98c5b1f3d&operationType=App2App"
   },
   "created_at":"2018-07-18T10:51:18.139Z",
   "description":"Заказ №72",
   "metadata":{
      "order_id":"72"
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":false,
   "test":false
}

Шаг 2. Перенаправьте пользователя в мобильное приложение СберБанк Онлайн, используя диплинк, который вернется в параметре confirmation_url. Пользователь авторизуется в приложении и сразу перейдет к оплате.

Подробнее о перенаправлении в приложение банка при оплате с мобильного устройства

Пример успешного платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"succeeded",
   "paid":true,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "captured_at":"2021-04-13T09:27:09.960Z",
   "created_at":"2021-04-13T09:25:13.087Z",
   "description":"Заказ №72",
   "income_amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "payment_method":{
      "type":"sberbank",
      "id":"22e12f66-000f-5000-8000-18db351245c7",
      "saved":false,
      "card":{
         "first6":"555555",
         "last4":"4444",
         "expiry_year":"2022",
         "expiry_month":"07",
         "card_type":"MasterCard"
         }
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":true,
   "refunded_amount":{
      "value":"0.00",
      "currency":"RUB"
   },
   "test":false,
   "authorization_details":{
     "rrn":"10000000000",
     "auth_code":"000000",
     "three_d_secure":{
       "applied":false
     }
   }
}

Оплата с перенаправлением в приложение банка (для десктопа)

Рекомендуется использовать только для полной версии сайта, а для мобильной использовать сценарий Mobile application.

В этом сценарии ваши действия различаются в зависимости от того, из какой версии вашего сайта пользователь проводит платеж:

При оплате из полной версии сайта вы генерируете QR-код, который сканирует пользователь в приложении СберБанка.
При оплате из мобильной версии вы перенаправляете пользователя по диплинку в мобильное приложение СберБанка.

В приложении СберБанка пользователь подтверждает платеж и видит, как прошла оплата (успех или неудача).

Шаг 1. Создайте платеж, в объекте payment_method_data передайте тип sberbank, в объекте confirmation — тип qr.

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

cURL
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sberbank"
        },
        "confirmation": {
          "type": "qr"
        },
        "description": "Заказ №72"
      }'

Шаг 2. В параметре confirmation_data ЮKassa передаст URL. Сгенерируйте QR-код с помощью любого доступного инструмента и отобразите его пользователю. В мобильной версии сайта перенаправьте пользователя по этому URL (например, при нажатии на кнопку Оплатить) и сообщите, что после оплаты ему необходимо вернуться на страницу вашего магазина.

Подробнее о перенаправлении в приложение банка при оплате с мобильного устройства

Пример созданного объекта платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"pending",
   "paid":false,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
      "confirmation":{
      "type":"qr",
      "confirmation_data": "sberpay://invoicing/v2?bankInvoiceId=successPaymentInApp2433394341762973&operationType=Web2App"
   },
   "created_at":"2021-04-12T13:03:20.155Z",
   "description":"Заказ №72",
   "metadata":{
      "order_id":"72"
   },
   "payment_method":{
      "type":"sberbank",
      "id": "22e12f66-000f-5000-8000-18db351245c7",
      "saved": false
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":false,
   "test":false
}

Шаг 3. Дождитесь успешного завершения платежа: подождите, когда придет уведомление от ЮKassa, или периодически отправляйте запросы, чтобы получить информацию о платеже .

Пример успешного платежа

JSON
{
   "id":"22e12f66-000f-5000-8000-18db351245c7",
   "status":"succeeded",
   "paid":true,
   "amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "captured_at":"2021-04-12T14:03:20.155Z",
   "created_at":"2021-04-12T14:02:39.550Z",
   "description":"Заказ №72",
   "income_amount":{
      "value":"2.00",
      "currency":"RUB"
   },
   "payment_method":{
      "type":"sberbank",
      "id":"22e12f66-000f-5000-8000-18db351245c7",
      "saved":false,
      "card":{
         "first6":"555555",
         "last4":"4444",
         "expiry_year":"2024",
         "expiry_month":"07",
         "card_type":"MasterCard"
         }
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":true,
   "refunded_amount":{
      "value":"0.00",
      "currency":"RUB"
   },
   "test":false,
   "authorization_details":{
     "rrn":"10000000000",
     "auth_code":"000000",
     "three_d_secure":{
       "applied":false
     }
   }
}

Особенности перенаправления пользователя в приложение банка

Для тех, кто принимает платежи в своем мобильном приложении на iOS и Android и использует сценарии с перенаправлением в приложение банка.

ЮKassa в сценариях с перенаправлением в приложение банка возвращает в объекте платежа диплинк. По этому диплинку вам нужно перенаправить пользователя в приложение банка для подтверждения оплаты. У СберБанка есть несколько приложений — СберБанк Онлайн и СБОЛ. Для подтверждения платежа подойдет любое, но в какое из них нужно перенаправить пользователя, заранее неизвестно. Чтобы пользователь точно смог попасть в приложение банка и подтвердить оплату, вам нужно доработать ваше приложение. Для этого воспользуйтесь инструкциями:

Доработка приложения на iOS
Доработка приложения на Android

Доработка приложения на iOS

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

Настройка запуска банковских приложений

Шаг 1. Настройте обработку всех редиректов в приложения СберБанк Онлайн и СБОЛ (схемы sberpay и sbolpay соответственно). Редиректы по этим схемам нужно обрабатывать через системный API.

Пример обработки редиректов

Swift
func webView(
            _ webView: WKWebView,
            decidePolicyFor navigationAction: WKNavigationAction,
            preferences: WKWebpagePreferences,
            decisionHandler: @escaping (WKNavigationActionPolicy, WKWebpagePreferences) -> Void
        ) {
            if let url = navigationAction.request.url,
               let host = url.scheme,
               host.hasPrefix("sberpay") || host.hasPrefix("sbolpay") {
                if UIApplication.shared.canOpenURL(url) {
                    UIApplication.shared.open(url)
                }
                decisionHandler(.cancel, preferences)
            } else {
                decisionHandler(.allow, preferences)
            }
        }

Шаг 2. Добавьте в конфигурационный файл Info.plist схемы sberpay и sbolpay, чтобы ваше приложение могло запускать приложения СберБанка:

Пример файла Info.plist

XML
<key>LSApplicationQueriesSchemes</key>
<array>
    <string>sberpay</string>
    <string>sbolpay</string>
</array>

Перенаправление пользователя в несколько банковских приложений

В приложении на iOS перенаправляйте пользователя и в СберБанк Онлайн, и в СБОЛ. Это можно сделать следующим образом:

Шаг 1. Из объекта платежа , который вернет ЮKassa, получите диплинк в приложение СберБанк Онлайн. Схема этого диплинка — sberpay.

Пример диплинка в приложение СберБанк Онлайн

JSON
sberpay://invoicing/v2?bankInvoiceId=successPaymentInApp2433394341762973&operationType=Web2App

Шаг 2. Сформируйте новый диплинк в приложение СБОЛ: измените схему на sbolpay.

Пример диплинка в приложение СБОЛ

JSON
sbolpay://invoicing/v2?bankInvoiceId=successPaymentInApp2433394341762973&operationType=Web2App

Шаг 3. Перенаправьте пользователя в приложение СберБанк Онлайн по диплинку, который ЮKassa прислала в объекте платежа (схема sberpay). Затем перенаправьте пользователя в приложение СБОЛ по новому диплинку (схема sbolpay).

Если на устройстве пользователя установлено несколько приложений для доступа к мобильному банку, то откроется либо СберБанк Онлайн, либо СБОЛ.

Доработка приложения на Android

Вам нужно настроить обработку редиректов для подтверждения платежа. Для этого переопределите метод shouldOverrideUrlLoading следующим образом. При проведении платежа проверяйте url на наличие схем для редиректа в приложение СберБанк Онлайн и СБОЛ (схемы sberpay и sbolpay соответственно). Если url содержит нужную схему, проверьте, что на устройстве можно запустить такой диплинк. Если можно, то вызовите метод startActivity для запуска приложения СберБанка.

Пример переопределения метода shouldOverrideUrlLoading

Java
override fun shouldOverrideUrlLoading(view: WebView, url: String): Boolean {
    if (url.contains("sberpay") || url.contains("sbolpay")) {
        val intent = Intent(Intent.ACTION_VIEW).setData(Uri.parse(url))
        if (intent.resolveActivity(requireActivity().packageManager) != null) {
            startActivity(intent)
        } else {
            view.loadUrl(url)
        }
    } else {
        view.loadUrl(url)
    }
    return true
}

Что почитать еще

Основы проведения платежей Неуспешные платежи Отправка чеков в налоговую