• Payment Gateway (PG, Gateway) is a number of solutions for the Internet acquiring process using various payment means.
• Merchant is the system or the person interacting with PG.
• Payer is the individual or the legal entity that makes a payment with his/her card for the merchant’s services in PG.
• Order is the elementary entity of PG describing the order in a certain online store or its analog.
• One-stage payment is the transaction of payment for goods/services that does not require additional confirmation (Completion), i.e. the funds are blocked and debited in one stage. This type of payment is preferred if the goods or services are provided immediately after the payment.
• Two-stage payment is the transaction of payment for goods/services that requires an additional confirmation (Completion), i.e. the payment is made in two stages. At the first stage, the payer's funds are checked and blocked (pre-authorization); then, at the second stage, the company either confirms that the funds should be debited or cancels the blocking of funds. The amount to be debited may be lower than the blocking amount.
• Holding (Blocking of funds) - The status of the amount of funds intended for compensation under the conducted transaction, from the time of successful authorization to the completion of settlements between the participating banks. At this stage, the funds are still on the Payer’s account, but are no longer available for use on the card.
• Refund means a partial or full refund of the Payer’s funds in case of their refusal to receive goods/services or the return of these. Refund is an offline transaction carried out after the funds are debited from the Payer. The reimbursement deadlines generally depend on the issuing bank and may be up to 30 days.
• Payment transaction cancellation (Reversal) is the operation of withdrawal (cancellation) of the Payer's funds withholding. Cancellation is an online operation, i.e. the card issuer receives an immediate request to unblock the amount. The cancellation may be carried out before the beginning of mutual settlements between the participating banks, therefore it is available for a limited time.
• Binding is the correspondence between the Payer and the card payment details (card or token number and validity period).
• 3-D Secure (3DS) is the protocol of additional Payer authentication based on the concept of three domains: acquirer, issuer and compatibility.
• Access Control Server (ACS) is the element of 3-D Secure infrastructure that ensures the Payer authentication on the issuing bank's side.
• MPI, 3DS Server is the element of 3-D Secure infrastructure on the acquiring bank's or Merchant's side.
• Fiscalization (54-FZ) is the procedure for generating a fiscal receipt for a successfully paid Order. This concept includes both the generation of a receipt for successful payment and the generation of a refund receipt, a closing receipt, etc.
• FDF - Fiscal Document Format. Standard of the Federal Tax Service, according to which all fiscal receipts are generated.
• Electronic Certificate (EC) is a record in the State Information System of Electronic Certificates (GIS ES). The EC holder gets access to this record using a national payment instrument, that is a PS Mir card.
• GWS — Goods/work/service
• NPCS - National Payment Card System
• FEC - Front Office of NPCS Electronic Certificates is the solution for a trade and service enterprise making it possible to purchase certain types of goods, work, services using EC tools

• Connection coordinates. Information about the coordinates for connecting to the test environment is also available in a special section for each service (on the right of the page).

Attention! For correct interaction with the gateway, you need to install the NCC certificate of the Digital Ministry.

Attention! Provisional windows are provided in the test environment: on the weekdays, the time intervals are reserved for 02:00 - 06:00, 09:00 - 10:00 and 18:00 - 20:00 (Moscow time), during which maintenance work can be done to implement the functionality in the test facility.The stability of the environment performance at this time is not guaranteed.

Test environment: https://ecomtest.sberbank.ru/...

Production environment: https://epay.sberbank.ru/...

• The payment gateway represents HTTP REST services by the POST method, with the transmission in "Content-Type: application/json" headers and a character set in the UTF-8 encoding. Messages are transmitted in JSON format (RFC 7159);
• The names of objects in the services are passed as case-sensitive;
• TLS protocols 1.2 and 1.3 are used for interaction;
• After the Merchant’s registration, the login and password to be used for connection to PG are provided;
• For the interaction with PG services, it is required to install the NCC certificate of the Digital Ministry.

Attention! It's not allowed to assign the value "null" to the parameters! If the parameter is "null", it should be completely excluded from the query.

Entry of the details on the Merchant's side without 3DS on the Gateway side

Entry of the details on the Merchant's side with 3DS on the Gateway side

Entry of the details on the Merchant's side with a simplified 3DS on the Gateway side

Entry of the details on the Gateway side

Payment using bindings

General algorithm for making payments using binding.

The scenario is divided into two stages:

1. Creation of a binding.

Below there is a brief description of the algorithm for creating a binding.

1.1. After receiving the Payer’s consent to further using the card data for making payments, the Merchant registers the order using register.do (with a mandatory transmission of the clientId parameter.

Attention! In case the specified parameter (clientId) is not present in the query, no binding will be created. The query can also pass features=VERIFY. In this case, the order amount must be 0 rubles and 0 kopecks, and the funds will not be debited from the Payer. At the same time, all necessary checks are carried out. This method of order registration is the most correct one for generating bindings.

1.2. The payer pays for the order with all attributes: card data and 3DS input or transaction payment via SberPay.

1.3. If the order is paid successfully, a binding will be created, whose ID can be obtained using the getOrderStatusExtended.do and/or getBindings.do queries.

1.4. Optional step. If it is necessary to return the funds under the order (when authorizing for an amount other than 0 rubles and 0 kopecks), a reverse.do query may be sent. The cancellation is required to prevent actual debiting of funds in case a technical operation is used to link the card.

Binding creation completed.

2. Payment using a binding

Below there is a brief description of the algorithm of payment using the available binding.

There are several payment options which can be initiated by both the Payer, and the Merchant.

1. The initiator is the Merchant.

Method 1.

1.1.1. The Merchant sends a recurrentPayment.do query.

1.1.2. The payment gateway enriches the query with the card data corresponding to the bindingId received from the Merchant.

1.1.3. The authorization is carried out using the data of the cards filled in in clause 1.1.2.

1.1.4 The authorization result is sent to the Merchant.

Method 2.

1.2.1. The Merchant registers the order using register.do / registerPreAuth.do with a mandatory transmission of the clientId parameter.

1.2.2. The order payment is initiated with the help of paymentOrderBinding.do, with the transfer of the bindingId parameter.

Attention! The bindingId parameter must match the clientId passed during the order registration.If you attempt to pay with the binding created for another clientId, the error "The order cannot be paid with this binding" will return.

1.2.3. The payment gateway checks that clientId and bindingId match. If there is a match, the Payment Gateway enriches the query with the card data corresponding to the transmitted bindingId value.

1.2.4. The authorization is performed using the data of the cards filled in in clause 1.2.3.

1.2.5. The authorization result is sent to the Merchant.

2. The initiator is the Payer.

2.1. The payer selects the payment with the saved card.

2.2. The Merchant registers the order using register.do / registerPreAuth.do with the mandatory transmission of the clientId parameter.

2.3. The order payment is initiated with the help of paymentOrderBinding.do, with the transfer of the bindingId parameter.

Attention! The bindingId parameter must match the clientId passed during the order registration.If you attempt to pay with the binding created for another clientId, the error "The order cannot be paid with this binding" will return.

2.4. The payment gateway checks clientId against bindingId. If the check is correct, the Payment Gateway enriches the query with the card data corresponding to the transmitted bindingId value.

2.5. The authorization is carried out using the data of the cards filled in in clause 1.2.3.

2.6. The authorization result is sent to the Merchant.

2.7. The Merchant notifies the Payer of the authorization result.

Attention! If the clientId and bindingId do not match, the error "The order cannot be paid with this binding" is returned to the Merchant.

In e-commerce, conversion is a critical indicator. If the integration is correct and the Merchant journey is intuitive, one of the main ways to improve the indicators is to transfer additional parameters.

Additional parameters make it possible to get more complete information about Merchants and their payment transactions, making it possible to significantly reduce the risks of fraud and avoid excessive blocking of transactions by the Bank, NPCS and other issuers. Additional parameters can be transmitted upon the order registration and in the payment services in blocks jsonParams or additionalParameters in accordance with the service description in the documentation.

Transfer of cart and payer account identifier of the partner are the most important factors that increase the conversion. The order cart transfer may be used without the fiscalization functionality.

Additional parameters may overlap 3DS parameters and in most cases affect the outcome of payer authentication, increasing the likelihood of frictionless flow work.

Errors of this block are returned at the stage of validation of the request to the Gateway

Description of the Gateway error codes

Errors of this block are returned at the processing stage of the called service

Errors of this block are returned when the operation is succesfully processed by the Processing Center Each order has 3 payment attempts before the order expiration time (20 minutes by default, this value can be specified during the order registration).

When interacting with the Payment Gateway, the Merchant has access to payment functions with SberPay in the mobile Sberbank Online app. The implementation of the functionality to achieve the best possible conversion rates provides for the compliance of the Merchant's payment experience with the Bank's requirements, the functionality description and the examples of implementation are available in briefing materials.

SberPay supports the APP channel payment feature set. Two implementations of the payment feature set are used:

• SberPay SDK InApp
• SberPay App2App

SberPay SDK InApp

This SDK is a software development kit that enables easy integration of SberPay into a partner’s mobile app and enhance user expirience.

SDK InApp benefits include: • No need to make any modifications to the implemented method. The Bank is responsible for any InApp SDK surface modifications and support • Better conversion into payments. All Sber cards are available on the SDK InApp surface, while balances and additional Sber financial services are also displayed • Advanced customer experience. The shortest possible customer journey. Long-term cookie-driven authentication support. Customers are not led away from a partner’s surface. A high-quality payment surface UX/UI • InApp SDK operating stability is not vulnerable to sanctions.

Developer materials available by the link

SberPay App2App

This legacy SberPay feature set enables integration of SberPay into a partner’s app. Payments are to be confirmed and completed in the Sber app via a deeplink embedded in the SberPay payment button.

SberPay supports its own payment feature set on desktop and mobile WEB sites.

SberPay WEB SDK

WEB SDK enables integration of the native SberPay payment surface into a partner’s website. This technology solution offers the best SberPay customer experience and has the following benefits:

• Straightforward implementation. The Bank will provide a ready-made library that the partner only needs to embed into their web site • Customers are not led away from a web site. From the customer’s prospective, a payment is completed right on the website without any redirections. A convenient payment curtain allows customers to see all of their cards and balances at once, and supports Sber’s financial services • No support costs. The Bank updates and maintains the customer experience on the payment surface • A single sign-in is sufficient. Once a customer has authenticated on the payment surface, we will remember them. All subsequent payments will be made seamlessly.

Developer materials available by the link

SberPay Web2App (native integration)

This is an alternative native payment experience on a WEB surface without using a payment page. The payment feature set is implemented under two scenarios: • A partner displays a QR code on their website’s surface. The customer must scan it to make a payment. The payment will be confirmed and completed within Sberbank’s app. • A partner displays a “Pay by phone number” button. To pay, the customer will enter their Sberbank app-linked phone number. After that, they will be sent a push notification or an SMS. The push notification or a link in the SMS will open the Sberbank app where the client will confirm and complete the payment. IMPORTANT! This payment feature set requires a particularly thorough compliance with the Bank’s UX/UI guidelines.

Payment page

SberBank’s payment page is installed by default when Sber’s acquiring service is enabled. The partner has the ability to enable payments via SberPay on the payment page surface. It’s an easy and convenient way to shop online. A customer just needs to press the SberPay payment button and scan the QR code (or select payment by the phone number). Payments are completed within the Sberbank app, where customers can select any available card. You won’t need to make any modifications if you have SberBank’s acquiring service enabled.

You can file an application to join SberPay at our site

Please note! Work with the SberPay payment functionality is available as part of the services described in the documentation, but can be integrated by the Merchant separately from other payment methods. When working with the SberPay functionality, the utilisation of the sberbankOnlineAttributes block in the query body in jsonParams is mandatory when registering an order in the register/registerPreAuth services.

When integrating the mweb2app scenario on apple devices, it is necessary to implement a deeplink lookup procedure. This is related to different app versions installed on users' devices. Detailed instructions for the procedure implementation are available in document.

For additional details on the SberPay testing procedure, please see documentation.

The description of the requirements to Merchant experience when implementing the SberPay functionality is in the attached document.

The description of the integration of the SberPay functionality is in the attached document.

The logos guide for SberbankOnline is in the attached document.

The transaction processing and the Gateway responses correspond to the description placed in the sections [Description of Gateway response codes] doc#section/Obshaya-informaciya/Opisanie-kodov-otveta-Shlyusa) and Description of Gateway error codes.

The example of payment with SberPay SDK can be found at link.

The instructions for SberPay SDK implementation for websites and mobile applications are available at link.

You can see how to draw a button SberPay here.

Acceptable options for rendering the logo of SberPay is in the attached document

In accordance with Federal Law of the Russian Federation No. 54-FZ dated July 1, 2017, when conducting online sales, the Seller (in this documentation - the Merchant), using an online cash register, is obliged to generate a cash receipt and send it to the Federal Tax Service and the buyer. In order to meet this requirement, Sberbank developed the mechanism for integration with online cash registers, which enables to simplify this procedure for the Merchant. At present, the Payment Gateway supports only ATOL Online, EVOTOR Digital Cash Desks, Business.ru with FDF versions 1.05 and 1.2 and OFD.RU with FDF version 1.1 and 1.2

• Sending data to an online cash register to generate receipts in FDF formats 1.05 and 1.2;
• Generation of receipts and refunds of receipts (including partial);
• Possibility to resend an unsuccessful receipt with changing the cart;
• Resending the receipt in case of a cash register error or at the sending timeout;
• Creating a receipt separately from the financial transaction (closing receipt);
• Possibility to divide the receipt into several, if the maximum size is exceeded;
• Getting the receipt status with a separate API query.

For a cash receipt to be registered successfully, the following conditions must be met:

• To create a receipt it is necessary to transfer the cart with the mandatory presence of ffdVersion and receiptType parameters in any of the register, registerPreAuth, deposit, reverse, refund services;
• Each receipt will have the parameters that were transferred as part of the relevant service;
• The order fiscalization functionality is connected and successfully configured for the merchant: the credentials for connecting the online cash register are correct and entered in settings.

Starting from 04/01/2025, before selling market goods, it is necessary to online check the marking code in an Honest Sign. There are 2 ways to perform verification:

1. On the side of your cash register service, you must enable marking code verification and specify the pre-receive Honest Sign Token. The check will be performed automatically by the cash register service, and the data will be transmitted into the Honest Sign. In this case, you cannot transfer sectoralItemProps (tag 1260) and all nested objects as part of the bucket. Please note that only Business cash register services support this method.Ru and Farms from OFD.RU .
2. Self-integration with a Honest Sign to obtain data on the status of the marking code, and the inclusion of this data in the sectoralItemProps object (tag 1260) when forming a "closing" receipt.

1260 tag composition:

To connect the Evotor cash register, it is necessary to:

1. Log in the Digital cash register service to receive a cloud cash register or install the Digital cash register app from the Evotor store of your online cash register.
2. On your own, in accordance with instructions or with the help of Evotor employees, register the cash register with the Federal Tax Service (FTS) and the Fiscal Data Operator (FDO).
3. In your Digital cash register personal account (if you use a cloud cash register) or in the Evotor personal account (if you use an online cash register), get the cash register credentials - Cash register group code.
4. You can set up the integration through your personal account of SberBusiness or by sending a query to the technical support service of Sberbank's Internet acquiring. The query should specify the Cash Register Group Code, the FDF version used and the merchantID provided by the Bank.

To connect the ATOL cash register, it is necessary to:

1. Log in the service "ATOL Online";
2. On your own, in accordance with instructions or with the help of ATOL Online employees, register the cash register with the Federal Tax Service (FTS) and the Fiscal Data Operator (FDO);
3. Get the cash register credentials (login, password, cash register group code) in your ATOL Online personal account;
4. You can set up the integration through your personal account of SberBusiness or by sending a query to the technical support service of Sberbank's Internet acquiring. The query should specify the cash register credentials and the FDF version being used.

To connect the OFD.RU cash register, it is necessary to:

1. Log in the personal account of the OFD.RU Merchant;
2. Register the cash register with the Federal Tax Service (FTS);
3. Get the cash register credentials (login, password) in your OFD.RU Merchant personal account;
4. You can set up the integration through your personal account of SberBusiness or by sending a query to the technical support service of Sberbank's Internet acquiring. The query should specify the cash register credentials and the FDF version being used.

To connect the Business.ru cash register, it is necessary to:

1. Log in the personal account of the Business.ru;
2. Register the cash register with the Federal Tax Service (FTS);
3. Contact with Business.ru support with a request to enable Sberbank api-integration;
4. Get the cash register credentials (login, password) in your Business.ru Merchant personal account;
5. You can set up the integration through your personal account of SberBusiness or by sending a query to the technical support service of Sberbank's Internet acquiring. The query should specify the cash register credentials and the FDF version being used.

Functionality is under development

SberSpasibo is a bonus loyalty program from Sberbank for its Merchants.

The Payer’s special bonus account is credited with a percentage of the purchase amount made by the Payer with the card.

In order to credit bonuses to the bonus account of the Payer paying with the card, the store connected to the Payment Gateway does not need to make any additional calls on its side.

The accumulated bonuses (1 bonus is equal to 1 ruble) can be used to pay for goods in partner stores. The ability to pay for goods/services with bonuses can be provided in several ways.

Payment using bonuses on the PG payment page

Payment with bonuses in SberPay

Payment with bonuses through binding

• The order must be issued in Russian rubles.
• Only the full order cancellation is available (the partial order cancellation is not available)
• Instead of the standard services for completion of the two-stage scenario deposit and return of the Payer's fundsrefund, it is necessary to use the equivalent services autoCompletion and autoRefund, specifying the total transaction amount in rubles and bonuses.
• In the event of completion of the two-stage scenario, or a partial refund, the Payment Gateway will recalculate the proportion of bonuses and rubles.
• When you work with the cart of goods, additional checks are carried out for the content of the cart:

  • For each item, the product of the unit value itemPrice and the qunatity of itemsquantity.value shall be exactly equal to the final amount of the item itemAmount.

  • The sum of the values of all product items itemAmount shall be equal to the total receipt amount total and the transaction amount in the query amount/compositeAmount.

  • For related transactions within one order (completion of the two-stage scenario, cancellation, refund), it is necessary to:

    • Ensure the consistency of unique positionId and itemCodeproduct item identifiers within the Cart.
    • Transfer the values of the goods itemPrice and itemAmount before the deduction of bonuses.

  • The unique identifier of the product item within the Cart(positionId) must be greater than or equal to 1.

  • It is possible to return only the goods included in the payment under the one-stage scenario (transmitted in the queryregister) or in the payment completion under the two-stage scenario (transmitted in the query autoCompletion).

  • The SberSpasibo loyalty processing is responsible for distributing the discount in the shopping cart during payment with bonuses.

    • Due to the peculiarity of SberSpasibo loyalty program bonus distribution on the side of loyalty processing for transferred items, the Gateway uses the following rounding method when making returns:
    • Determines the value of the discounted item by subtracting the discount amount per item from the original item value;
    • Determines the unit price of an item by dividing the discounted item value by the quantity of the item using mathematical rounding;
    • When you return the value of the last item unit in an position, its price is calculated by subtracting the price of all previous items from the discounted value of the item.

    Example:

    • There are 3 items in the card with a price of 33.00. Discount of SberSpasibo loyalty program is apllied you 29.99;
    • Item value including discout: 33.00 - 29.99 = 3.01;
    • Item unit price including discount: 3.01/3 = 1.00;
    • Price of the last returned item unit: 3.01 - 1.00 - 1.00 = 1.01.

    This technique is applicable when implementing its own solution for fiscalization.

  • If the fiscalization by the gate functionality is used (functional is under development):

    • The payment gateway deducts the applied discount in bonuses from the value of the item. The discount deduction due to bonuses does not apply to the service for creating a new receipt doReceipt.
    • If after applying the discount with bonuses, it is impossible to correctly calculate the price for a unit of goods, one product item is divided into two product items with different prices for a unit of goods, with the total value of product items maintained.
• Data on the status of bonuses for loyalty programs in the order are available in the response to the service for obtaining information about the order getOrderStatusExtended.

Functionality is under development

Electronic certificate is a new payment tool that enables to independently purchase certain types of goods, work and services at the expense of budgets if there are grounds for receiving governmental support measures in kind. The electronic certificate is issued for the PS Mir card, and the payment is carried out similarly to the transactions using bank cards and allows an instant payment for certain types of goods if there are grounds for providing social support measures.

The certificate contains information about what goods, work or services, in what quantity and in what maximum amount can be purchased using it. The funds are not transferred to the PS Mir card, but are reserved in the budget until the purchase is made. At the same time, it is necessary to use own funds only if the quantity and/or cost of the goods, work or services being purchased exceeds the quantity and/or maximum cost in the electronic certificate.

In order to enable the acceptance of payments with electronic certificates, the Merchant shall do the following:

1. To carry out settlements on transactions using an EC, it is required to conclude a supplementary agreement to the IE contract.

2. To be able to interact with the Front Office of Electronic Certificates of NPCS TSE, the Merchant needs to support the encoding of goods corresponding to the list of goods/work/services - truCode.

3. It is necessary to log in the State Information System of Electronic Certificates GIS ES.

4. The seller's internal accounting systems must ensure that the GWS are encoded in line with the list approved in accordance with Resolution of the Government of the Russian Federation No. 631 dated April 23, 2021 "On the procedure of generation and approval of the Lists of certain types of goods, works, services purchased using an electronic certificate at the expense of the budget of the budgetary system of the Russian Federation". The up-to-date list is published in the Unified Regulatory Reference Information System.

5. Complete the registration of the seller and the stores in the Automated System for Collection of Questionnaires (ASCQ) to obtain an access key (API KEY). NPCS JSC sends a link to the e-mail address of the seller's employee specified as a technical specialist when filling in the form on the website of the State Information System of Electronic Certificates (GIS ES) at step 3 to enter ASCQ and create a password to access the seller's personal account in ASCQ. When you enter the system for the first time, ASCQ will prompt you to set a login password.

6. Having the API KEY, the Merchant must receive a cash register ID (cashboxId) and a cash register key (MAC KEY) in NPCS FEC.

7. The merchant must transfer the API KEY, cashboxId, MAC KEY to the Acquiring Bank and perform a test transaction.

8. Go to the production environment.

The guide for trade and service enterprises explaining how to organize the acceptance of electronic certificates when paying for certain types of goods, work, services is posted on the official website of NPCS JSC in the Electronic Certificates section - Offer for TSE.

Payment using an EC on the PG payment page

• The order must be issued in Russian rubles.
• Transactions paid with an EC cannot be cancelled. Partial and full returns of the goods purchased with EC funds are supported. When you return the goods purchased with EC funds, the funds will be returned to the EC account.
• EC funds are used to pay, in full or in part, for only those goods for which GWS codes were transferred; the goods from the cart without GWS codes cannot be paid with EC.
• When using an EC, you must transfer the shopping cart. Additional checks of the content of the shopping cart are carried out on the side of PG:
  • For each item, the product of the unit value itemPrice and the quantity of items quantity.value shall be exactly equal to the final value of the item itemAmount
  • The sum of the values of all the items itemAmount shall be equal to the total receipt amount total and the transaction amount amount in the query.
  • When generating the return operation, it is necessary to ensure the invariability of the parameters of cart items: positionId, itemCode, itemPrice, truCode.
  • Only the items included in the payment (transmitted in the queryregister) may be returned.
• Data on the status of EC funds in the order are available in the response to the service for obtaining order information getOrderStatusExtended.
• In case of fiscalization on the Merchant’s side, after receiving the details of the fiscal receipt of purchase or return from the online cash register, it is necessary to transfer these parameters of the fiscal receipt in the service externalReceipt to transmit them to FEC. If the fiscalization is performed on the side of PG, no additional calls to work with EC are required.

You can read the instructions in your Sberbank Business Online personal account on Sberbank website. Below you can find the most popular links to the sections dedicated to work with orders of Internet acquiring.

• Create a link to payment
• Completion of two-stage orders
• Cancellation of orders (one- and two-stage)
• Reset of the gateway password and generation of the API-key
• Generation of reports
• Execution of the return (including partial) under the order
• Order search

API methods for creating an order, cancelling an order, obtaining an order status, performing a refund on the order.

API methods for making the order payment

API methods for creating, receiving information, activating, deactivating, and making payments by bindings Attention! For some merchant categories (MCC) recurrent payments, using the MIR card are not possible.

API methods for working with MirPay payments