Skip to content

General Principles and Rules

This article describes the general principles and rules of interaction with the services of the Internet Acquiring product.

Payment Processing and Settlement

Here’s a simplified example of a successful payment and subsequent settlement, involving a credit card.

Payment Processing

  1. The client selects a product or service on the partner’s platform, goes to the payment form, fills out the necessary fields, and clicks «Pay».
  2. QIWI receives a request to process the operation.
  3. QIWI sends a request to the payment system that services the card.
  4. The payment system sends a request to the bank that issued the client card.
  5. The issuing bank updates the client account amount, sending a successful transaction response to the payment system.
  6. The payment system sends a successful transaction response to QIWI.
  7. QIWI informs the partner about the successful completion of the operation.


As a result of payment processing, funds accumulate and, when a certain amount is reached or after a specific number of days, they are transferred to the partner’s settlement account in their chosen credit institution.

%%{init: {
    "sequence" : {
        "diagramMarginY": 0,
        15 }}}%%
    participant С as Client
    participant P1 as Partner's Trading Platform
    participant P2 as Partner's Credit Institution
    participant Q as QIWI
    participant PS as Payment System
    participant B as Issuing Bank
    rect rgb(230, 230, 230)
    Note over С, B: Payment Processing
    loop Repeats at specified intervals
    С->>P1: Payment for goods or services
    Note over P1: Payment Form
    P1->>+Q: Request for transaction
    Q->>+PS: Request for transaction
    PS->>+B: Request for transaction
    B->>-PS: ОК
    PS->>-Q: ОК
    Q->>-P1: ОК
    P1->>С: Communication with the client
    rect rgb(255, 238, 223)
    Note over P2, B: Settlements
    B->>PS: ₽₽₽
    PS->>Q: ₽₽₽
    Q->>P2: ₽₽₽

Electronic Payment Signatures

To accept payments, the partner may need to sign a request and include the X-Digital-Sign header containing the signature value.

To determine which requests require passing X-Digital-Sign: <signature value>, refer to the HTTP Headers section in the Payments API documentation.

X-Digital-Sign serves as an additional security factor: its use does not eliminate the need to pass the Authorization request header with Bearer Token value.

To sign a request, the partner must:

  1. Create a key pair using the RSA-2048 algorithm.

    • OpenSSL is one of the available utilities.
    • The private key size is 2048 bits, and the format is PEM.
  2. Provide QIWI with the Base64-encoded public key corresponding to the secret key.

  3. Sign each request to the Payments API requiring the X-Digital-Sign header.

Steps 1 and 2 are performed once, and step 3 is performed each time a request is created.

Please Note

RSA key pairs need to be reissued annually.

Creating a Key Pair

To create a key pair using OpenSSL, the partner must:

  1. Generate a private key.

    openssl genrsa -out private-key.pem 2048

    This command will create a file with the private key (private-key.pem) in the command execution folder.

    Please Note

    Do not provide access to the private key to third parties; keep it confidential.

  2. Generate a public key corresponding to the private key.

    openssl rsa -in private-key.pem -pubout -out public-key.pem
  3. Encode the public-key.pem in Base64.

    base64 -i public-key.pem

Providing the Public Key to QIWI

The partner must provide QIWI with the result obtained in the step 3 of the «Creating a Key Pair» stage. The method of providing public-key.pem should be clarified with the support manager.

Signing a Payment Request

To sign payment requests, the partner should perform the actions described below. Examples in the description are given in Bash.

  1. Create the request body as a string with request parameters.

    Line pattern
    REQUEST_BODY='{"amount":{"value":100, "currency":"RUB"},...'
  2. Generate a digital signature using the SHA256withRSA algorithm and the private-key.pem obtained in the step 3 of the «Creating a Key Pair» stage.

    SIGNATURE_RAW=$(echo -n $REQUEST_BODY | openssl dgst -sha256 -sign private-key.pem)
  3. Encode the digital signature as a string using Base64.

    SIGNATURE_BASE64=$(echo -n $SIGNATURE_RAW | base64)
  4. Include the encoded digital signature in the X-Digital-Sign header when sending a request to the Payments API.

Decision on Transaction Success

To make a decision regarding the success of an operation (e.g. payment authorization or payment confirmation), the partner should:

  • Wait for a notification from QIWI.
  • Send a transaction status request to QIWI.

To understand the operation’s status, it is recommended to rely on the value of the status field in the response to the status request for the corresponding operation. This helps mitigate risks associated with receiving false notifications, which are compromise data in case the «secret» used for notification signature verification is leaked.

The transaction status request is recommended to be performed after receiving the notification.

Please note

If a notification is not received within 10 minutes of the transaction, it is necessary to request the status.

The sequence of actions to make a decision about the success of the operation, using the example of QIWI form payment, is illustrated below. In this example, payment is made using a single-step scenario.

%%{init: {
    "sequence" : {
        110 }}}%%
    participant С as Client
    participant P as Partner
    participant B as BaaS
    С->>P: Payment using QIWI form
    Note right of С: «Pay»
    P->>+B: Сценарий «QIWI Form Payment using the API»
    Note right of P: billId, flags:[SALE]
    Note left of B: Redirect to `successUrl`
    rect rgb(255, 238, 223)
    B->>+P: «Notification Handling» scenario
    Note left of B: billId, paymentId, status:SUCCESS
    rect rgb(230, 230, 230)
    P->>+B: Invoice status request (Payments API)
    Note right of P: billId
    B-->>-P: Invoice status response
    Note left of B: billId, status:PAID, paymentsData
    P->>С: Communication with the client

The described requests can be found in the Payment API documentation..

The scenarios referred to in the diagram can be found in the following articles: