SberPay — Payment acceptance via the YooMoney API

SberPay

Specifics

Payment method type in the API: sberbank
Confirmation scenario: Redirect, External, Mobile application, and QR code
Payment term: 1 hour
Holding: 5 days
Code in reports: SB
Refund: yes, full and partial
Refund processing time: instantly
Recurring payments: available
Limits: the minimum payment amount is 1 ruble, and the maximum amount is 700,000 rubles (you can raise the limit by contacting the manager), there are additional restrictions

Integration scenarios

Ready-made solutions:

Manual integration:

Payment via SberPay on YooMoney’s ready-made page
Payment with confirmation via push notification or text messages
Payment with redirection to the bank app (for mobile devices)
Payment with redirection to the bank app (for desktops)

Payment via SberPay on YooMoney’s ready-made page

In this scenario, you redirect the user to the YooMoney page after the payment is created. On this page, the user scans the QR code to open bank's mobile app and enters the phone number linked to SberBank Online to receive a push notification or text message.

Step 1. Create a payment , send the sberbank type in the payment_method_data object, and in the confirmation object send the redirect type and the URL of the page on your side where users will be redirected after the payment (in the return_url parameter).

Example of request

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <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": "Order No. 72"
      }'

Step 2. Redirect the user to the YooMoney’s page (you will receive the URL in the confirmation_url parameter). On this page, the user will enter the bank card details and confirm the payment.

Example of a created payment object

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":"Order No. 72",
   "metadata":{
      "order_id":"72"
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":false,
   "test":false
}

If a payment via SberPay doesn't go through (for example, if there wasn't enough money), YooMoney will display an error message to the user and prompt them to try again.

Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .

Example of a successful payment

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
     }
   }
}

Step 4. After the user returns to return_url, display the results of payment processing (success or failure) depending on the payment status.

Payments with confirmation via push notifications or text messages

In this scenario, you request user's phone number linked to SberBank Online and inform the user that they're going to receive a push notification or text message to this number. To confirm the payment, the user needs to tap on the push notification or respond to the text message.

Step 1. Create a payment with the sberbank type as well as the user’s phone number, linked to the SberBank Online account, in the payment_method_data object, and the external type in the confirmation object.

Example of request

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <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": "Order No. 72"
      }'

Example of a created payment object

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":"Order No. 72",
   "metadata":{
      "order_id":"72"
   },
   "payment_method":{
      "type":"sberbank",
      "phone":"79000000000"
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":false,
   "test":false
}

Step 2. Inform the user that they need to confirm the payment.

Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .

Example of a successful payment

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
     }
   }
}

Step 4. Display the results of payment processing (success or failure) depending on the payment status.

Payment with redirection to the bank app (for mobile devices)

We recommend using it only for accepting payments via mobile devices (via the mobile app or mobile web version).

In this scenario, you redirect the user to the SberBank mobile app via a deeplink after the payment. They confirm the payment in this app.

Step 1. Create a payment , send the sberbank type in the payment_method_data object, the mobile_application type in the confirmation object, and the deep link to your app or the link to your store’s page (for payments via mobile web) in the return_url parameter.

Example of request

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <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": "Order No. 72"
      }'

Example of a created payment object

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":"Order No. 72",
   "metadata":{
      "order_id":"72"
   },
   "recipient":{
      "account_id":"100500",
      "gateway_id":"100700"
   },
   "refundable":false,
   "test":false
}

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

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

Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .

Example of a successful payment

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":"Order No. 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
     }
   }
}

Step 4. After the user returns to return_url, display the results of payment processing (success or failure) depending on the payment status.

Payment with redirection to the bank app (for desktops)

We recommend using it only for the desktop version of the website. Use the Mobile application scenario for the mobile version.

In this scenario, your actions depend on which version of your website is used for the payment:

If the payment is made via the desktop version of the website, you generate a QR code, which the user scans in the SberBank app.
If the payment is made via the mobile version, you redirect the user to the SberBank mobile app via a deeplink.

In the SberBank app, the user confirms the payment and sees if it's successful or not.

Step 1. Create a payment , send the sberbank type in the payment_method_data object, the qr type in the confirmation object.

Example of request

cURL
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "sberbank"
        },
        "confirmation": {
          "type": "qr"
        },
        "description": "Order No. 72"
      }'

Step 2. YooMoney will send you a URL in confirmation_data. Generate a QR code using any available tool and display it to the user. For the mobile version or the app, redirect the user to this URL (for example, when they tap the Pay button) and inform the user that they need to return to your store’s page after paying.

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

Example of a created payment object

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":"Order No. 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
}

Step 3. Wait for the payment to be successfully completed: you will receive a notification from YooMoney, or you can send periodic requests for payment information .

Example of a successful payment

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":"Order No. 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
     }
   }
}

Step 4. Display the results of payment processing (success or failure) depending on the payment status.

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

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

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

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

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

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

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

Step 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)
            }
        }

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

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

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

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

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

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

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

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

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

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

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

Step 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
}