Raiffeisenbank (Russia) Subscription API

openapi: 3.2.0
info:
  title: Raiffeisen Ru Subscription API
  version: '1.0'
  contact:
    email: ecom@raiffeisen.ru
    name: Support e-mail
    x-team-id: 178
    x-short-team-name: PAPAS
  x-description-i18n:
    eng: "You can give your comments about current documentation in repository: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/sbp_en.yaml\n\n# Connect to SBP\n\nTo receive SBP payments, submit application on [site](https://www.rbo.raiffeisen.ru/sign-form/).\n\nRaiffeisenbank will complete the registration.\nAfter the process is completed, you will be notified by email.\n\n## SBP participants\n\n### Buyer\n* selects the services / goods in the partner software and the item “Payment via SBP” (optional)\n* scans the QR code provided by the partner and confirms the payment in the application of their bank\n* receives the result of payment and paid services / goods\n\n### Partner\n* requests the formation of a QR code for the selected goods / services (basket)\n* displays a QR code to the client for scanning and making payment\n* processes notifications of the results of SBP operations\n* requests payment data (optional)\n* ensures the delivery of goods / services to the buyer upon payment\n\n### Raiffeisenbank\n* provides an interface for requesting a QR code from a partner\n* provides money transfer to the partner's account upon settlements in SBP\n* defines the format of the notification of the fact of the SBP payment\n* provides an interface for receiving payment data\n\n## Support 54-FZ\n\nIn accordance with the Federal Law NO. 54-FZ of May 22, 2003 \"On the use of cash registers in implementation of settlements in the Russian Federation\",\nfor taxation purposes a fiscal receipt is required for making settlements for goods sold, work performed or services rendered, as well as transfer of the receipts to tax authorities.\n\nRaiffeisenbank provides generation of fiscal receipts and their transfer to tax authorities by integration via [API](https://pay.raif.ru/doc/fiscal.html).\n\n# General schemas of work\n\n## Working with a form\nTo accept payments online on the website or in the mobile application, you can use [QR code opening protocol in the form](https://pay.raif.ru/doc/ecom_en.html).\n\n<a href='images/SBP and ECOM EN. Working with a form.png' target='_blank'><img src='images/SBP and ECOM EN. Working with a form.png'></a>\n\n## White label SBP API\n\nThe figure below shows the schema of information exchange with a partner when making a payment using a QR code.\n\n<a href='images/SBP EN. White label SBP API.png' target='_blank'><img src='images/SBP EN. White label SBP API.png'></a>\n\n## Subscription schema\n\nYou can offer the client to link the SBP payment to the loyalty program or to an account in your service. To do this, you can generate a QR code and display it to the client or redirect it via a special link that is located in the response to the request to create a QR code for a subscription.\n\nAfter that, using the unique subscription identifier, you can apply for debiting funds from the client for your goods and services without the client's acceptance.\n\n<a href='images/SBP EN. Subscription schema.png' target='_blank'><img src='images/SBP EN. Subscription schema.png'></a>\n\n## Payment and subscription schema\n\nThere is also a schema in which one request receives a QR code to receive payment and subscription.\n\nIn this case, the client makes a payment, after which a window is displayed with a proposal to activate the subscription.\n\nThe customer can pay but unsubscribe. Also, the client can make a payment from a bank application that does not support subscriptions.\n\n<a href='images/SBP EN. Payment and subscription schema.png' target='_blank'><img src='images/SBP EN. Payment and subscription schema.png'></a>\n\n## Working with QRVariable\n\nThe diagram below depicts usage scenario for QRVariable. It is a new QR code type that is differentiated from QRStatic and QRDynamic.\n\n<a href='images/SBP EN. Working with QRVariable.png' target='_blank'><img src='images/SBP EN. Working with QRVariable.png'></a>\n\n## Subscription with recurring charges\nSubscriptions support automatic recurring charges made by bank on regular basis. As of now, only monthly charges are supported.\nIn case of unsuccessful payment another attempt is made on the same day. If the second attempt fails, charge will be repeated the next day and so on. Failed attempts do not cause subscription cancellation.<br><br>\nAutomatic recurring charges can be made for both of subscription scenarios listed above. To enable the feature, additional fields must be passed either in [QR creation method](#operation/post-sbp-v2-qrs) or in [subscription creation method](#operation/post-sbp-v1-subscriptions).<br><br>\nPayment notifications might be received by [callbacks](#tag/Callback). In this case subscriptionId will be passed in the [body message](#operation/сallbackPay). Subscription can be deactivated via [cancellation method](#operation/delete-sbp-v1-subscriptions-subscriptionId).\n<a href='images/SBP EN. Subscription with recurring payments.png' target='_blank'><img src='images/SBP EN. Subscription with recurring payments.png'></a>\n# Ready solutions\nYou can use our SDK for faster integration:\n* [Java](https://github.com/Raiffeisen-DGTL/sbp-sdk-java)\n[Our other solutions](https://pay.raif.ru/doc/solutions.html).\n# API description\nThe interaction is carried out using the HTTP protocol using the GET/POST/DELETE methods (the description of each request clearly indicates the required method and address).\n\nPOST requests use JSON arguments, GET/DELETE requests work with query strings.\n\nThe API always returns a response in JSON format, regardless of the type of request.\n\nThe response of any method contains a message code (code). If a logical error occurs during the processing of any request, the API will additionally return a description of the error (message).\n\n## Authorization\nRequests like:\n* receiving information on a QR code\n* receipt of payment information\n* processing a return on payment\n* receiving information on return\n\nare authorized using the API secret key (secretKey). The authorization parameter is specified in the Authorization header, the value of which is formed as \"Bearer secretKey\".\n\nYou can view your sbpMerchantId and generate keys in your [personal account](https://www.rbo.raiffeisen.ru/acquiring/mcp#/) in the \"Accept payments\" tab\n\n<div align=center><a href='images/createKey.png' target='_blank'><img src='images/createKey.png'></a></div>\n\nTo generate test data, please contact the Bank's support team by sending an email to ecom@raiffeisen.ru\n\nThe secret key must be stored in a trusted environment, since refunds can be made using it.<br><br>\nIt is our recommendation to create a single merchant for all trading locations owned by your company. If so, there will be no need to:\n- store a dictionary linking merchants with your trading locations\n- store a large amount of secret keys and set them up at each trading location individually\n- create additional merchants if new trading locations are opened by the company\n- make refunds strictly at the same store where items were purchased\n- make complicated reports based on various merchants\n- link QR codes with corresponding merchants (in case of using QRVariable)\n# Mobile version and application\nWe recommend using our [payment form](https://pay.raif.ru/doc/ecom_en.html), for working in the mobile version of the site or mobile application.\n\nIf you plan to use your form, then you need to implement a bank selection widget, for this you need to get its scheme for each bank:\n- [bank schemes for payment QR](https://qr.nspk.ru/proxyapp/c2bmembers.json )\n- [bank schemes for subscription QR codes](https://sub.nspk.ru/proxyapp/c2bmembers.json )\n\nAnd substitute it in the url from the payload parameter, instead of https.\n\nFor the correct choice of the bank's app, we recommend using the SDK from the NSPK:\n\nIOS , Android , Web - https://sbp.nspk.ru/business_online/#widget-business\n\nOr you can use our SDK:\nAndroid - https://github.com/Raiffeisen-DGTL/sbp-sdk-android\nIOS - https://github.com/Raiffeisen-DGTL/payform-sdk-ios\n\n### Recommendations for working with deeplink in mobile applications\n\nFor correct deeplink handling in WebView, we recommend the following implementation:\n\n1. **Configure WebView:**\n   ```kotlin\n   webView.settings.javaScriptEnabled = true\n   webView.settings.setSupportMultipleWindows = false\n   ```\n\n2. **Create a custom WebViewClient:**\n   ```kotlin\n   webView.webViewClient = object : WebViewClient() {\n       override fun shouldOverrideUrlLoading(\n           view: WebView,\n           request: WebResourceRequest\n       ): Boolean {\n           val url = request.url.toString()\n\n           return if (url.startsWith(\"http://\") || url.startsWith(\"https://\")) {\n               false\n           } else {\n               try {\n                   val intent = Intent(Intent.ACTION_VIEW, Uri.parse(url))\n                   if (intent.resolveActivity(view.context.packageManager) != null) {\n                       view.context.startActivity(intent)\n                       true\n                   } else {\n                       // resolveActivity may return null on API 30+ due to package visibility\n                       // try launching directly as fallback\n                       view.context.startActivity(intent)\n                       true\n                   }\n               } catch (e: ActivityNotFoundException) {\n                   // No app available to handle this scheme\n                   false\n               } catch (e: Exception) {\n                   e.printStackTrace()\n                   false\n               }\n           }\n       }\n   }\n   ```\n\n3. **How it works:**\n   - `http://` and `https://` links → load inside WebView\n   - Other schemes (deeplinks) → open in installed apps via Intent\n\nThis approach ensures correct deeplink handling and keeps web pages within your app.\n\n# NFC and SBPay\nTo work with SBP via NFC, it is necessary to implement interaction via [\"QRVariable\"](#section/General-schemas-of-work/Working-with-QRVariable).\n\nYou need to generate a QR code with the QRVariable type for each cash register.\nFrom the response to the QR generation request, you need to get a link from the payload parameter, in the link to the beginning of the domain you need to add \"web.\" and the resulting link needs to be write into an NFC tag.\n\nExample:\n\nIn payload you got https://qr.nspk.ru/AS100004BAL7227F9BNP6KNE007J9B3K,\n\nthe NFC tag will need to be write https://web.qr.nspk.ru/AS100004BAL7227F9BNP6KNE007J9B3K\n\n# Testing\n\nFor a full payment testing cycle, Raiffeisenbank provides the opportunity to use a demo application for scanning QRC on behalf of the buyer at:\nhttps://pay.raif.ru/pay/rfuture/\n\nThe specified address can be opened in the browser of any device with a camera. No additional software / plugins need to be installed. Then click on the SBP icon (if necessary, allow the browser access to the camera) and bring the QR code image to it.\nIf the camera doesn't open, check the url, it has to have https.\n"
  x-logo:
    url: images/raifflogo.png
    backgroundColor: '#FFFFFF'
    altText: Raiff logo
  description: 'Operations tagged Subscription across 2 of this provider''s published API definitions: raiffeisen-ru-raif-pay-sbp-openapi.json, raiffeisen-ru-raif-pay-sbp-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://pay.raif.ru/api
  description: Production
- url: https://pay-test.raif.ru/api
  description: Sandbox
tags:


# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/raiffeisen-ru/refs/heads/main/openapi/raiffeisen-ru-subscription-api-openapi.yml