Skip to main content

SberPay

This scenario describes how to receive payments via SberPay. These payments, regular and recurring, do not require card details from customers. To select a recurring payment method, inform your manager in Bank 131 upon boarding.

More information including guidelines and the SDK can be found here.

You should confirm a payment within 20 minutes by sending session/confirm. Otherwise, the session terminates within 20 minutes with the canceled status.

Payment scenario​

  1. Create a separate session using the session/create method, or create a session with the payment using the session/init/payment method. Both methods should pass the required settings including the payment channel within the channel setting and URL to forward the customer to a Sber application within the return_url setting.

    The session/start/payment method is required to be sent after you created a separate session.

  2. Wait for a ready_to_confirm webhook from Bank 131 when Bank 131 is ready to process the payment and is waiting for your confirmation.
  3. Confirm your payment by sending a session/confirm request, or cancel the payment sending a session/cancel request.

    You can also use the sberpay/push method to additionally send PUSH or SMS notifications to customers (PUSH/SMS notification channel is set by Sber). Note that it is not recommended to use the sberpay/push method with channel = app. In this case, Bank 131 cannot guarantee a successful payment.

  4. For payments performed with channel = app or channel = mobile_web payment channels, Bank 131 will send you an action_required webhook containing a URL within redirect.url to forward the customer to a Sber mobile application.

    When channel = web, Bank 131 does not send a action_required webhook, so that you can skip steps 5 and 6 of this scenario.

  5. For iOS devices, forward the customer by the deeplink passed within the redirect.url parameter to a Sber mobile application. Use the algorithm below to select the proper mobile application to forward the customer:
    1. Open the btripsexpenses://sbolpay/... deeplink.
    2. Wait 50ms.
    3. Reload the page to hide a possible alert if the deeplink could not open properly.
    4. Redirect back to your page with the new request settings.
    5. Open the ios-app-smartonline://sbolpay/... deeplink.
    6. Wait 50ms.
    7. Reload the page to hide a possible alert if the deeplink could not open properly.
    8. Redirect back to your page with the new request settings.
    9. Open the sberpay://... deeplink.
    10. Wait 50ms.
    11. Reload the page to hide a possible alert if the deeplink could not open properly.
    12. Redirect back to your page with the new request settings.
    13. Open the sbolpay://... deeplink.
    14. Wait 50ms.
    15. Reload the page.
    16. Follow the deeplink to the Sber landing page.
  6. Wait until the customer approves or cancels the payment. After that, Sber takes the customer back to the URL or deeplink passed within the return_url parameter.
  7. Wait for a payment_finished webhook from Bank 131 with the transaction results. You can also send requests (no more than once in 5 seconds) to obtain the transaction status.

    If the customer cancels the transaction, the transaction status will renew only after 20 minutes, as soon as the customer's order expires.

  8. Pass the transaction status to the customer.

Payment channels​

The sets of parameters passed within the requests vary depending on the customer's channel of payment: mobile application app, mobile browser mobile_web, or desktop browser web. The value that defines the channel is passed with the session/create or session/init/payment methods within the payment_details.internet_banking.sber_pay.channel parameter.

app — mobile application​

  1. The phone parameter is optional. When it is passed, no PUSH or SMS notification will be sent to the customer.
  2. It is not recommended to use the sberpay/push method with channel = app. In this case, Bank 131 cannot guarantee a successful payment.
  3. The action_required webhook contains a URL in the redirect.url parameter to forward the customer to.
  4. Before forwarding the customer to the specified URL, it is required to select a proper deeplink to forward the customer to a Sber mobile application. See a code example.
  5. The return_url parameter contains a URL to take the customer back from the Sber mobile application.
Request example 
curl -X POST \
https://proxy.bank131.ru/api/v1/session/init/payment \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internet_banking",
    "internet_banking": {
      "type": "sber_pay",
      "sber_pay": {
        "phone": "71234567890",
        "channel": "app"
      }
    }
  },
  "amount_details": {
    "amount": 1000,
    "currency": "RUB"
  },
  "metadata": "app",
  "customer": {
    "reference": "user-ebf7-4815-af0a-b1f77e6de7e7"
  },
  "payment_options": {
    "return_url": "https://t.me/bank131"
  }
}'
Response example 
{
  "status": "ok",
  "session": {
    "id": "ps_12345",
    "status": "in_progress",
    "created_at": "2023-09-29T05:42:10.549869Z",
    "updated_at": "2023-09-29T05:42:10.948457Z",
    "acquiring_payments": [
      {
        "id": "pm_131",
        "status": "in_progress",
        "created_at": "2023-09-29T05:42:10.973559Z",
        "customer": {
          "reference": "user-ebf7-4815-af0a-b1f77e6de7e7"
        },
        "payment_details": {
          "type": "internet_banking",
          "internet_banking": {
            "type": "sber_pay",
            "sber_pay": {
              "phone": "71234567890",
              "channel": "app"
            }
          }
        },
        "amount_details": {
          "amount": 1000,
          "currency": "RUB"
        },
        "metadata": "order123",
        "payment_options": {
          "return_url": "https://t.me/bank131",
          "recurrent": false
        }
      }
    ]
  }
}

mobile_web — mobile browser​

  1. The phone parameter is optional. When available, no PUSH or SMS notification will be sent to the customer.
  2. To send PUSH or SMS notification, use the sberpay/push method.
  3. The action_required webhook contains a URL in the redirect.url parameter to forward the customer to.
  4. Before forwarding the customer to the specified URL, it is required to select a proper deeplink to forward the customer to a Sber mobile application. See a code example.
  5. The return_url field contains a URL to take the customer back from the Sber mobile application.
Request example 
curl -X POST \
https://proxy.bank131.ru/api/v1/session/init/payment \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internet_banking",
    "internet_banking": {
      "type": "sber_pay",
      "sber_pay": {
        "phone": "71234567890",
        "channel": "mobile_web"
      }
    }
  },
  "amount_details": {
    "amount": 1000,
    "currency": "RUB"
  },
  "metadata": "mobile_web",
  "customer": {
    "reference": "user-ebf7-4815-af0a-b1f77e6de7e7"
  },
  "payment_options": {
    "return_url": "https://t.me/bank131"
  }
}'
Response example 
{
  "status": "ok",
  "session": {
    "id": "ps_12345",
    "status": "in_progress",
    "created_at": "2023-09-29T05:42:10.549869Z",
    "updated_at": "2023-09-29T05:42:10.948457Z",
    "acquiring_payments": [
      {
        "id": "pm_131",
        "status": "in_progress",
        "created_at": "2023-09-29T05:42:10.973559Z",
        "customer": {
          "reference": "user-ebf7-4815-af0a-b1f77e6de7e7"
        },
        "payment_details": {
          "type": "internet_banking",
          "internet_banking": {
            "type": "sber_pay",
            "sber_pay": {
              "phone": "71234567890",
              "channel": "mobile_web"
            }
          }
        },
        "amount_details": {
          "amount": 1000,
          "currency": "RUB"
        },
        "metadata": "order123",
        "payment_options": {
          "return_url": "https://t.me/bank131",
          "recurrent": false
        }
      }
    ]
  }
}

web — desktop browser​

  1. The phone parameter is used to send PUSH or SMS notification and is mandatory. If absent, the payment will not be created.
  2. The action_required webhook is not sent.
  3. While the return_url parameter is mandatory, its the value is ignored as the customer is not redirected anywhere.
Request example 
curl -X POST \
https://proxy.bank131.ru/api/v1/session/init/payment \
-H 'Content-Type: application/json' \
-H 'X-PARTNER-PROJECT: your_project_name' \
-H 'X-PARTNER-SIGN: signature' \
-d '{
  "payment_details": {
    "type": "internet_banking",
    "internet_banking": {
      "type": "sber_pay",
      "sber_pay": {
        "phone": "71234567890",
        "channel": "web"
      }
    }
  },
  "amount_details": {
    "amount": 1000,
    "currency": "RUB"
  },
  "metadata": "web",
  "customer": {
    "reference": "user-ebf7-4815-af0a-b1f77e6de7e7"
  },
  "payment_options": {
    "return_url": "https://131.ru"
  }
}'
Response example 
{
  "status": "ok",
  "session": {
    "id": "ps_12345",
    "status": "in_progress",
    "created_at": "2023-09-29T05:42:10.549869Z",
    "updated_at": "2023-09-29T05:42:10.948457Z",
    "acquiring_payments": [
      {
        "id": "pm_131",
        "status": "in_progress",
        "created_at": "2023-09-29T05:42:10.973559Z",
        "customer": {
          "reference": "user-ebf7-4815-af0a-b1f77e6de7e7"
        },
        "payment_details": {
          "type": "internet_banking",
          "internet_banking": {
            "type": "sber_pay",
            "sber_pay": {
              "phone": "71234567890",
              "channel": "web"
            }
          }
        },
        "amount_details": {
          "amount": 1000,
          "currency": "RUB"
        },
        "metadata": "order123",
        "payment_options": {
          "return_url": "https://t.me/bank131",
          "recurrent": false
        }
      }
    ]
  }
}

Selecting a proper deeplink for Sber iOS mobile applications​

Code example​

const openBtripsexpenses = () => {
  window.location.href =
    "btripsexpenses://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb01";
};

const openIosAppSmartonline = () => {
    window.location.href =
      "ios-app-smartonline://sbolpay/invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0";
};

const openSberpay = () => {
  window.location.href =
    "sberpay://invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0";
};

const openSbolpay = () => {
  window.location.href =
    "sbolpay://invoicing/v2?bankInvoiceId=1961101c8c524c7fa15a9f101e965c58&orderNumber=d76d899c-6ffb-7116-ae89-afc802a92bb0";
};

const openLandingpage = () => {
  window.location.href =
    "https://www.sberbank.ru/ru/person/payments/online_sberpay";
};

const clearMessage = () => {
  window.location.href =
    "./same_page.html";
};

if (platform == "android") {
  setTimeout(openSberpay, 100);
  clearMessage();
  setTimeout(openLandingpage, 800);
} else if (platform == "iPhone") {
  setTimeout(openIosAppSmartonline, 50);
  clearMessage();
  setTimeout(openBtripsexpenses, 50);
  clearMessage();
  setTimeout(openSberpay, 50);
  clearMessage();
  setTimeout(openSbolpay, 50);
  clearMessage();
  setTimeout(openLandingpage, 800);
}