Raiffeisenbank (Russia) White Label API

openapi: 3.2.0
info:
  title: Raiffeisen Ru White Label API
  version: '1.0'
  contact:
    name: Support e-mail
    email: ecom@raiffeisen.ru
    x-team-id: 178
    x-short-team-name: PAPAS
  license:
    name: Proprietary
    url: https://www.raiffeisen.ru/
  x-description-i18n:
    eng: "# Connection to acquiring\nTo connect, fill out an application in [the online bank](https://www.rbo.raiffeisen.ru/sign-form/internet-acquiring) or [the mobile application.](https://rbo.page.link/internet)\n\nFor questions about working with the API, please contact Raiffeisenbank support service:\n- email: ecom@raiffeisen.ru\n\n### Preparatory activities\nTo accept payments:\n* Fill out the [application](https://www.rbo.raiffeisen.ru/sign-form/internet-acquiring) to connect acquiring\n* Choose an integration method and implement it\n* Make test payments\n\n# Operation scheme\n## Payment on the merchant's form\n\n<a href='images/WLEcom_en.svg' target='_blank'><img src='images/WLEcom_en.svg'></a>\n\n## Create payment with subscription\n\n<a href='images/WLEcom-sub-and-payment_en.svg' target='_blank'><img src='images/WLEcom-sub-and-payment_en.svg'></a>\n\n## Bind card\n`IN DEVELOPMENT` <br>\n\n<a href='images/WLEcom-bind-card_en.svg' target='_blank'><img src='images/WLEcom-bind-card_en.svg'></a>\n\n### Payment scenario\n`This workflow requires your company to have PCI DSS certification`<br><br>\nTo make a payment using your own payment form, you must support integration with the [Bank's API](#tag/white-label) methods.\n\n**1. Creating a payment or binding a bank card**\n\nTo make a payment or bind a bank card, you must first create a payment using the [[Create payment]](#operation/post-payments-v1-merchants-publicId-payments) method, specifying the required 'flow' parameter:\n- `flow: CARD` — Card payment\n- `flow: CARD_BINDING` — Card binding\n\nAs a result of executing the method, the payment will be generated in the Bank's system.\nThe method response will return a payment object with the status `NEW`.\n\n- Together with the payment object, additional parameters required for performing an additional [[3DS Method]](#operation/post3DSMethod) step may be returned.\n\n**2. Continuing the payment**\n\nAfter the payment or bind bank card has been created, you must continue processing the payment using the [[Continue payment]](#operation/put-payments-v1-merchants-publicId-payments-id) method.\n- In some cases, the method can complete the payment (transfer it to the final status `SUCCESS`) if the payment passes via 3DS v.2 frictionless flow.\n\n**3. Calling the issuer's ACS for 3DS authentication and OTP code entry by the user**\n\nIf, as a result of executing the [[Continue payment]](#operation/put-payments-v1-merchants-publicId-payments-id) method, the status `3DS_PENDING` is returned,\nthe merchant must redirect the payer to the issuing bank's authorization page, and also send a POST request to the issuer's authentication service.\n\n- The issuing bank's address will be returned in the `acsUrl` parameter\n- The parameters required to send in the request depend on the 3DS version\n\n**3DS v.1**:\n  | Parameter           | Description             |\n  |---------------------|-------------------------|\n  | `MD`                | Information for payment identification. The parameter is returned in the response of the [[Continue payment]](#operation/put-payments-v1-merchants-publicId-payments-id) method. |\n  | `PaReq`             | The parameter required for payer authentication. The parameter is returned in the response of the [[Continue payment]](#operation/put-payments-v1-merchants-publicId-payments-id) method. |\n  | `TermUrl`           | The URL on the merchant's side, to which the ACS will return the response after passing 3DS. The payer will also be redirected to this address after successful OTP code entry.|\n\n**3DS v.2**:\n  | Parameter         | Description             |\n  |-------------------|-------------------------|\n  | `creq`            | Payment session data required for 3DS authentication. The parameter is returned in the response of the [[Continue payment]](#operation/put-payments-v1-merchants-publicId-payments-id) method. |\n\nExample of sending a POST request to the issuer's ACS to continue 3DS v.2:\n```js\n  export function createContinuePayment3ds2Iframe(acsUrl, creq) {\n    const container = document.getElementById('otp-page');\n    const iframe = window.document.createElement('iframe');\n    iframe.id = 'threeDs-2-iframe';\n    iframe.style = 'height: 100%; width: 100%; overflow: hidden; position: absolute; top: 0; left: 0; background: white; z-index: 1000; border: none;';\n    const html = `\n      <body onload=\"document.forms[0].submit()\">\n        <div>\n          <form name=\"form\" action=\"${acsUrl}\" method=\"post\">\n            <input type=\"hidden\" name=\"creq\" value=\"${creq}\">\n          </form>\n        </div>\n      </body>\n    `;\n    container.appendChild(iframe);\n    iframe.contentWindow.document.open();\n    iframe.contentWindow.document.write(html);\n  }\n```\n\nAfter calling the ACS and successful OTP code entry by the user, the merchant's `termUrl` will receive an incoming request from the issuer with the `cres` parameter (in case of 3DS v.2 challenge), or `pares` and `md` in case of 3DS v.1.\n\nExample of obtaining pares via subscription and post-message listening:\n```js\n  window.addEventListener('message', (event) => {\n    try {\n      if (typeof event.data !== 'string') return;\n      const { pares } = JSON.parse(event.data);\n      // Call the required 3DS confirmation method to complete the payment\n    } catch (error) {\n      console.error('Error processing message:', error);\n    }\n  });\n```\n\n**4. 3DS confirmation and payment completion**\n\nTo complete the payment, you must finish processing the payment using the\n[[3DS v.1 Confirmation]](#operation/put-payments-v1-merchants-publicId-payments-id-3ds1-confirm) or\n[[3DS v.2 Confirmation]](#operation/put-api-payments-v1-merchants-publicId-payments-id-3ds2-confirm) methods.\n\nExample of completing the payment via 3DS v.1:\n  ```js\n  window.parent.postMessage(JSON.stringify({\n    pares: paRes\n  }), '*');\n  ```\n\nExample of completing the payment via 3DS v.2:\n  ```js\n  window.parent.postMessage(JSON.stringify({\n    cres: document.getElementById('data').dataset.cres,\n  }), '*');\n  ```\n\n**Payment status model**:\n\n<div style=\"text-align: center;\">\n  <img src=\"images/wl-ecom-payment-status-model.png\" alt=\"Payment status model\">\n</div>\n\n# Integration\nInteraction is carried out via the HTTP protocol using the `POST` `GET` `PUT` `DELETE` methods.\n\nWhen sending requests to open a payment form and create an order with opening a payment form, the API returns a response in the HTML document format, responses to other requests are returned in JSON format.\n\n## Authorization\nTo authorize requests, you need:\n* `publicId` - The identifier that is used to open the payment form and is public.\n* `secretKey` - A secret key that is used for inter-service interaction. It is private, must be stored in a secure place and must not be transferred to third parties.\n\n| Circuit          | URL address             |\n|------------------|-------------------------|\n| Production       |https://pay.raif.ru      |\n| Test             |https://pay-test.raif.ru |\n\nInter-service requests are authorized using the secret key `secretKey`. The authorization parameter is passed in the `Authorization` header, the value of which is formed as `Bearer + secretKey`\n\nYou can view the production `publicId` and generate a `secretKey` in the [Online Bank](https://www.rbo.raiffeisen.ru/acquiring/mcp#/), or [Personal Account](https://pay.raif.ru/account/#/auth).\n\nInstructions for generating `secretKey` can be found in the Help Center:\n* [Generate a secret key in Online Banking](https://help.pay.raif.ru/sbp/rbo/secretkey)\n* [Generate a secret key in your Personal Account](https://help.pay.raif.ru/sbp/lk/secretkey)\n\nTo generate a `secretKey` in the test circuit, you must contact the support service ecom@raiffeisen.ru\n\n# Testing\nFor a full payment testing cycle, you must specify a payment amount greater than 10 rubles.\n\n`Test cards for payment scenarios`\n| Card PAN          | Card validity period| CVV | OTP code| 3DS Scenario       |\n|-------------------|---------------------|-----|---------|--------------------|\n| 2201382000000039  | 12/35               | 880 |         | 3DS2 Frictionless  |\n| 2201382000000021  | 12/35               | 880 |   1234  | 3DS2 Challenge     |\n| 4000001000000018  | 12/35               | 880 |   1234  | 3DS1 Flow          |\n\n## Negative testing\n\nThe amounts listed below can be used to trigger errors for payments or subscription debits.\n\n| Scenario | Amount | Error type |\n|----------|--------|------------|\n|* Card payment <br> * Card subscription debit | 99.51 | Insufficient funds to perform the operation |\n|* Card payment | 99.61 | Authorization amount exceeded the card spending limit |"
  x-logo:
    url: images/raifflogo.png
    backgroundColor: '#FFFFFF'
    altText: Raiff logo
  description: 'Operations tagged white-label across 2 of this provider''s published API definitions: raiffeisen-ru-raif-pay-whitelabel-ecom-openapi.json, raiffeisen-ru-raif-pay-whitelabel-ecom-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://pay-test.raif.ru/api
  description: Sandbox
- url: https://pay.raif.ru/api
  description: Production
tags:


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