Notifications¶

To allow the partner to track the status of transaction, QIWI uses notifications, which are HTTPS POST requests sent to the partner’s URL.

Structure¶

Each request consists of headers and the request body.

The Signature header of the request contains a digital signature. The digital signature is used to protect against request tampering: its value allows to verify that the notification came from QIWI and not from fraudsters.

The request body contains a JSON object with the notification data (data). The set of data depends on the type of transaction for which the notification is generated.

Notifications can be sent for both financial and non-financial transactions. An example of a financial transaction is payment confirmation, and a non-financial transaction is card verification.

For descriptions of notifications and examples of their contents, see the Payment API documentation.

Scenario¶

Each time a partner’s server receives a notification, it must:

• Compute the signature.
• Compare the computed signature with the value from the Signature header.

In case of a mismatch, the notification should be ignored.

If the partner’s server has received and processed the notification, it should return an HTTP 200 OK response. Until then, QIWI will attempt to resend the notification within a certain time period.

An example of a successful notification handling scenario is shown in the diagram below.

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":14,
        "actorMargin":90 }}}%%
sequenceDiagram
    participant B as QIWI
    participant P as Partner
    Note left of B: The client made a payment for goods or services
    B->>P: Event notification (Signature, data)
    P->>P: Compute the signature
    P->>P: Compare with Signature
    Note over P: The computed result matches the value in Signature
    P->>B:  HTTP Status: 200 OK
    B->>B: Successful result of notification handling

Computing the Digital Signature¶

To compute the signature, you need the string representation of the «secret» (secret) and of the data to be signed, i.e., of the parameters of the notification body (parameters).

The value of secret corresponds to the server notification key specified in the «Settings» section of the personal account.

The signature is computed for the following parameters of the notification body:

Signature Computation Algorithm

1. Convert the values of the relevant parameters to string representation (UTF-8) and concatenate them into one string.

   Example

   parameters = {payment.paymentId}|{payment.createdDateTime}|{payment.amount.value}

2. Compute the hash (HMAC) using the SHA256 algorithm: hash = HMAС(SHA256, secret, parameters).

The value from step 2 needs to be compared with the value of the Signature header in the notification.

URL¶

The URL for receiving notifications is set for a specific siteId and specified in the personal account under the «Settings» section.

The URL must start with https, as notifications are sent via HTTPS on port 443. The URL must be accessible from the Internet.

The site certificate must be issued by a trusted certificate authority: Comodo, Verisign, Thawte, etc.

Notification Frequency¶

Notifications that QIWI considers unsuccessfully delivered are distributed in queues for resending:

• 1 attempt with a delay of 5 seconds;
• 1 attempt with a delay of 1 minute;
• 3 attempts with a delay of 5 minutes each.

The time for resending attempts may increase.

Notification Example¶

{
  "payment": {
    "type": "PAYMENT",
    //paymentId required for payment confirmation
    "paymentId": "824c7744-1650-4836-abaa-842ca7ca8a74",
    "createdDateTime": "2022-07-27T12:43:35+03:00",
    "merchantSiteUid": "test-00",
    "status": {
        "value": "SUCCESS",
        "changedDateTime": "2022-07-27T12:43:47+03:00"
    },
    "amount": {
        "value": 1.00,
        "currency": "RUB"
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "512391******6871",
        "cardHolder": null,
        "cardExpireDate": "3/2030"
    },
    "tokenData": {
        "paymentToken": "cc123da5-2fdd-4685-912e-8671597948a3",
        "expiredDate": "2030-03-01T00:00:00+03:00"
    },
    "customFields": {
        "cf2": "dva",
        "cf1": "1",
        "cf4": "4",
        "cf3": "tri",
        "cf5": "5",
        "full_name": "full_name",
        "phone": "phone",
        "contract_id": "contract_id",
        "comment": "test",
        "booking_number": "booking_number"
    },
    "paymentCardInfo": {
        "issuingCountry": "643",
        "issuingBank": "Tinkoff Bank",
        "paymentSystem": "MASTERCARD",
        "fundingSource": "UNKNOWN",
        "paymentSystemProduct": "TNW|TNW|Mastercard® New World—Immediate Debit|TNW|Mastercard New World-Immediate Debit"
    },
    "customer": {
        "email": "darta@mail.ru",
        "account": "11235813",
        "phone": "79850223243"
    },
    "gatewayData": {
        "type": "ACQUIRING",
        "eci": "2",
        "authCode": "0123342",
        "rrn": "001239598011"
    },
    "billId": "191616216126154",
    "flags": [
        "AFT"
    ]
  },
  "type": "PAYMENT",
  "version": "1"
}