SBP

Introduction

You can accept payments via SBP (the Fast Payment System) of the National Payment Card System (NSPK). In this case, the client scans a dynamic of static QR code in a browser or clicks the button in a mobile application to make a payment instead of entering card data.

To enable the ability to accept payments via SBP, contact technical support.

Payment via dynamic QR code

Payment on payment page

1. The Customer places an order and proceeds to payment.
2. The Merchant sends an order registration request to the Payment Gateway – register.do.
3. In response to a registration request, the Payment Gateway returns a unique order identifier in the payment system (in the orderId parameter) and a URL to which the Customer must be redirected to receive the payment form (in the formUrl parameter).
4. The Merchant's system sends to the Customer's browser a redirect to the URL (see Step 3).
5. Customer's browser requests the payment form at received URL.
6. The browser displays the payment page, where the Customer chooses to pay via SBP.
7. The payment page requests a QR code from the Payment Gateway.
8. The Payment Gateway sends a QR code request to NSPK.
9. NSPK returns a response to the QR code request.
10. A QR code is displayed to the Customer in a browser. In case of a mobile app, the button for payment is displayed.
11. The Customer scans the QR code using specialized software or (in case of a mobile app) clicks the button and makes a payment.
12. The Payment Gateway receives a response with the payment result.

13. If the payment is unsuccessful, then the number of payment attempts is reduced and the Payment Gateway sends a callback about the unsuccessful payment to the Merchant’s system.

    If the payment is successful, Steps 13–14 are skipped and the scenario goes to Step 15.
    

14. If the Merchant is configured to send notifications (callbacks, email), then a notification is sent to the Customer about unsuccessful payment for the order. The process stops.

15. The Payment Gateway sends a request to NSPK about the final status of the payment.

16. NSPK returns a callback with the payment status.

17. The Payment Gateway moves the order to the "Deposited" status.

18. The Payment Gateway sends a callback about successful payment to the Merchant's system.

19. If the Merchant is configured to send notifications (callbacks, email), then a notification is sent to the Customer about successful payment for the order.

Payment in a payment form on Merchant side

1. The Customer places an order and initiates payment. See customer identification.
2. The Merchant sends an order registration request to the Payment Gateway – register.do.
3. In response to a registration request, the Payment Gateway returns a unique order identifier in the payment system (in the orderId parameter).
4. The Merchant redirects the Customer to the Merchant's payment form.
5. The Customer chooses to pay via SBP.
6. The Merchant sends a request to receive a QR code to the Payment Gateway – sbp/c2b/qr/dynamic/get.do.
7. The Payment Gateway sends a QR code request to NSPK.
8. NSPK returns a response to the QR code request.
9. The Payment Gateway returns a response to the QR code request to the Merchant's system.

10. Depending on where the payment is made, the action at this step may be one of the following:

    • On the Merchant's payment form in a web browser: the Merchant displays the QR code from the renderedQr parameter to the Client.
    • In WebView with Merchant payment form opened from mobile app: The Merchant opens a link from the payload parameter in WebView. When payload is opened via WebView, the JS SBP widget is launched, which, when a bank is selected, forms a direct Deep Link. After that, the Deep Link shall be followed.

    • In the mobile app itself (the payment button on step 5 is located in the Merchant application, not on the payment form in WebView) there are several options:

      • The Merchant uses the SDK of the SBP widget so that the Client can select a bank. As a result of the selection, the SDK widget will generate a Deep Link to open.
      • The Merchant opens the link from the payload parameter in WebView. Just like when using the payment form via WebView, when opening payload via WebView, the JS SBP widget is launched to form a direct Deep Link on bank selection. After that, the Deep Link should be followed.

11. The Customer scans the QR code using specialized software or (in case of a mobile app) makes a payment in the selected bank's app.

12. The Payment Gateway receives a response with the payment result.

13. If the payment is not successful, then the number of payment attempts is reduced and the Payment Gateway sends a callback about the unsuccessful payment to the Merchant’s system.

    If the payment is successful, Steps 13–14 are skipped and the scenario goes to Step 15.
    

14. If the Merchant is configured to send notifications (callbacks, email), then a notification is sent to the Customer about unsuccessful payment for the order.

15. The Merchant requests the payment status from the Payment Gateway – sbp/c2b/qr/dynamic/status.do.

16. The Payment Gateway returns a callback with the payment status.

17. If the Merchant is configured to send notifications (callbacks, email), then a notification is sent to the Customer about successful payment for the order.

18. Merchants sends order status request getOrderStatusExtended.do to the Payment gateway.

19. The Payment gateway returns order status.

Customer identification

To identify a Customer before payment, the Merchant:

• enables the corresponding permission by contacting the support team;
• requests from the Customer the data to be used for identification: the full name and the telephone number of the Customer.

Then, a dynamic QR code is generated for payment (step 2) with Customer data. This code should be used for payment.

On payment processing, Payment gateway compares the data specified during QR code generation:

• Payer's full name
• Payer's phone number and/or
• identifier of the Payer's bank (BIC)

with Customer's data. If they are the same (Payer=Customer), then Payment gateway confirms the possibility of order payment.

If at least one parameter differs, the payment is declined.

If none of the three parameters (full name, phone number, BIC) of the Payer is specified when requesting the order registration (step 2), the parameters are not transferred and the order registration and payment are performed without prior identification of the Customer.

Payment via "instant invoice" service

Payment via "instant invoice" service is possible on the payment page or on the Merchant's side.

The payment scenario is similar to the Payment on the payment page scenario.

If this functionality is enabled, the QR code displayed in the Customer's mobile app is also a link. For payment, the customer clicks the QR code instead of scanning it, and the online bank is opened.

At the merchant's request, the use of "instant invoice" functionality can be replaced by using of NSPK widget. In this case, when the customer chooses SBP on a mobile device, the QR code is not displayed, and the link is opened allowing to choose the bank for payment.

Cancellation and refund

Cancellation of a payment request

1. The client wishes to cancel the order/payment using the already created QR code.
2. The Merchant sends a request to the Payment Gateway to cancel the QR code sbp/c2b/qr/dynamic/reject.do, passing mdOrder and `qrId `.
3. The Payment Gateway checks whether the QR code can be canceled.
4. The Payment Gateway requests the status of the QR code.
5. NSPK sends a response: QR status = ACWP (see Order statuses).

If the response has a different status, go to Step 8. 6. The Payment Gateway assigns the order status = Deposited. 7. The Payment Gateway sends a response with a cancellation error. 8. NSPK sends a response: QR status = RCVD (see Order statuses).

If the response has a different status, go to Step 10. 9. The Payment Gateway sends a response with a cancellation error. 10. NSPK sends a response: QR status = RJCT or NTST (see Order statuses). 11. The Payment Gateway updates the QR code status: Status: QR=REJECTED_BY_USER. 12. The Payment Gateway sends a response with a successful cancellation. 13. NSPK sends a notification of successful payment 14. NSPK sends a response with the status QR = ACWP (see Order statuses). 15. The payment gateway requests an auto-refund. 16. NSPK notifies the Payment Gateway about the successful refund.

After canceling the QR code, the order can again be paid using any previously available payment methods, including restarting SBP C2B payment by registering a new QR code.

Order statuses

Refund via API

1. The Merchant sends a request for a refund to the Payment Gateway – refund.do.
2. The Payment Gateway sends a request to NSPK for the possibility of a refund.
3. NSPK sends a response to the request.
4. The Payment Gateway sends a request for a refund to NSPK.
5. In response, NSPK sends the refund status to the Payment Gateway: PENDING or REJECT.
   If the refund status is REJECT, go to Step 6.
   If the refund status is PENDING, go to Step 7.
6. The Payment Gateway sends an error response to the Merchant with a corresponding message in the errorMessage parameter.
7. The Payment Gateway is awaiting the final refund status from NSPK.
8. NSPK sends a callback to the Payment Gateway with the result of the refund: ACCEPTED or REJECT.
   If the status is ACCEPTED, go to Step 9.
   If the status is REJECT, go to Step 10.
   If no callback notification is received within the time interval set in the Payment Gateway settings, go to Step 11.
9. The Payment Gateway returns a response with the error code 0 to the Merchant. The script is being completed.
10. The Payment Gateway sends an error response to the Merchant with a corresponding message in the errorMessage parameter. The script is being completed.
11. The Payment Gateway sends an error response to the Merchant with a corresponding message in the errorMessage parameter. In this case, the following steps starting from Step 12 are taken in order to get the refund status.
12. The Merchant resends the request for the refund to the Payment Gateway - refund.do.
13. Upon receiving a repeated request, the Payment Gateway checks the refund status - PENDING.
14. The Payment Gateway sends a request for the refund status to NSPK.
15. NSPK sends a response to the request - ACCEPTED, REJECT, PENDING.
16. The Payment Gateway updates the refund status.
    If the status is ACCEPTED, go to Step 17.
    If the status is REJECT, go to Step 18.
    If the status is PENDING, go to Step 19.
17. The Payment Gateway returns a response with the error code 0 to the Merchant.
18. The Payment Gateway sends an error response to the Merchant with a corresponding message in the errorMessage parameter.
19. The Payment Gateway sends an error response to the Merchant with a corresponding message in the errorMessage parameter.

Refund via Personal Area

In case of the Customer's refusal to receive the goods (services) or its return, partial or full refund to the Customer's card is possible . The refund operation is performed after debiting the Customer's account. During the refund operation, you can specify the amount less or equal to the debited amount. The refund amount is specified in minor currency units. The operation is applicable to the orders in Deposited and Refunded statuses.

Partial refund is available as many times as you like until the entire order amount is refunded.

This function is available to Merchants with the corresponding permissions (coordinated with the bank). The refund button is available only to the users with a corresponding permission.

See the description of refund in Merchant Portal here.

Autorefund

1. Order status changes to DECLINED.
2. Payment Gateway requests SBP C2B operation in NSPK.
3. NSPK returns the operation status status=ACWP.
4. Payment Gateway requests refund for SBP C2B operation.
5. NSPK performs refund for the operation.
6. NSPK returns the notification about the final refund status to Payment Gateway.
7. Payment Gateway stores the refund event in the order history.
8. Payment Gateway sends callback notification with the refund information to the Merchant (the notification contains the operation type operation=refund and the indicator of successful operation status=1).
9. Merchant requests the order status, sending the getOrderStatusExtended.do request to Payment Gateway.
10. Payment Gateway returns the order information.

Refund of the order payed via CL

For refund of the order payed via CL, use standard scenario.

Autorefund

1. Order status changes to DECLINED.
2. Payment Gateway requests SBP C2B operation in NSPK.
3. NSPK returns the operation status status=ACWP.
4. Payment Gateway requests refund for SBP C2B operation.
5. NSPK performs refund for the operation.
6. NSPK returns the notification about the final refund status to Payment Gateway.
7. Payment Gateway stores the refund event in the order history.
8. Payment Gateway sends callback notification with the refund information to the Merchant (the notification contains the operation type operation=refund and the indicator of successful operation status=1).
9. Merchant requests the order status, sending the getOrderStatusExtended.do request to Payment Gateway.
10. Payment Gateway returns the order information.

Two-phase payments with SBP

An order is considered a two-phase if it is registered with registerPreAuth.do method.

SBP does not support two-phase payments, but it is possible to pay for two-phase orders via the SBP through the Payment Gateway. This requires a specific permission in the Payment Gateway. This permission will not make the payment two-phase, it only allows you to pay for a two-phase order using the usual SBP payment.

A two-phase order paid via SBP is captured immediately after payment: its status becomes DEPOSITED (not APPROVED, as would be at a regular two-phase payment). In this case, the funds will be are immediately debited from the Client's account; you do not need to capture the order in the Merchant Portal or execute deposit.do.

To cancel such orders, use the Refund option in the Merchant Portal or the refund.do method as shown in Refund section.

Example

A gas station uses a two-phase payment to pre-authorize funds on the customer's account and then capture the amount for the actual fuel dispensed (it may differ from the pre-authorized amount).

In the gas station's app, the customer can pay for orders by card or via SBP. It is not known in advance which payment method the customer will choose. Therefore, the order is registered as a two-phase order; after paying by card, the standard capture operations are performed. But if the customer decides to pay for the order via SBP, then the funds are immediately debited from the account (/deposit.do is not required), and /refund.do is used to adjust the amount.

Payment via dynamic UPC

To work with dynamic QR code (universal payment code, UPC) contact the Bank for enabling the corresponding setting. If the setting is enabled, you can pay using SBP and the Digital Ruble.

Integration for this payment method is similar to SBP integration. You can find the description of integration schemes in the Payment via dynamic QR code section.

API methods

See API methods description here.

Callback notifications

Callback notifications are sent to the Merchant in the following cases:

• When a credential is stored
• When a stored credential payment fails

When a credential is stored

When a credential is stored with or without payment, a Callback notifications is sent to the Merchant.

If storing a credential with payment or storing a credential without payment fails, Payment Gateway sends a callback notification to the Merchant, passing NSPK code in the sbp.c2b.operation.nspkCode parameter.

Example of callback notification for storing a credential, status=1

https://test.com/callback?amount=1000&orderNumber=136007&checksum=4BE878188646A0BEEA459F14FF9D9BEFE09D25E3945B98959BBC7B9D6B6941D0&mdOrder=03013b49-ecba-7792-806a-03f80203b80c&operation=bindingCreated&refundedAmount=0&memberId=100000000008&status=1

If the merchant has passed subscriptionServiceName (name of the service provided) and/or subscriptionServiceId (identifier of the service provided) in the request of QR code (get.do), the callback notification contains these parameters.

When a stored credential payment fails

When a stored credential payment fails, Payment Gateway sends a callback notification to the Merchant, passing NSPK code in the sbp.c2b.operation.nspkCode parameter.

The information about the failure is stored in the order history.

Example of callback notification for stored credential payment failure, status=0, sbp.c2b.operation.nspkCode=RQ05031

https://test.com/callback?sbp.c2b.operation.nspkCode=RQ05031&amount=10000&orderNumber=169008&mdOrder=036d42d3-78c3-77a9-af76-49fa00a3e120&operation=deposited&status=0

If the merchant has passed subscriptionServiceName (name of the service provided) and/or subscriptionServiceId (identifier of the service proveded) in the request of QR code (get.do), the callback notification contains these parameters.

Response codes from NSPK