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.

Settlements

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" : {
        "wrap":true,
        "diagramMarginY": 0,
        "mirrorActors":true,
        "width":120,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorFontSize":14,
        "actorMargin":
        15 }}}%%
sequenceDiagram
    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
    end
    end
    rect rgb(255, 238, 223)
    Note over P2, B: Settlements
    B->>PS: ₽₽₽
    PS->>Q: ₽₽₽
    Q->>P2: ₽₽₽
    end

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.

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.

Creating a Key Pair¶

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

1. Generate a private key.

   Command

   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.

   Command

   openssl rsa -in private-key.pem -pubout -out public-key.pem
   

3. Encode the public-key.pem in Base64.

   Command

   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.

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" : {
        "wrap":true,
        "messageFontSize":15,
        "noteFontSize":14,
        "actorMargin":
        110 }}}%%
sequenceDiagram
    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]
    B->>-P: 
    Note left of B: Redirect to `successUrl`
    rect rgb(255, 238, 223)
    B->>+P: «Notification Handling» scenario
    P-->>-B: 
    Note left of B: billId, paymentId, status:SUCCESS
    end
    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
    end
    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:

• «QIWI Form Payment using the API».
• «Notifications».