Payment Scenario¶

Single-step Scenario¶

A successful payment example using a single-step scenario is described and illustrated below. In this example, the payment is made using a bank card.

Please note

All payment methods, except for payment via bank card, are activated upon request: payment via bank card is available by default, to enable other methods, please contact our support team.

The client selects a product or service on the partner’s trading platform and proceeds to payment.
The partner displays its own payment form to the client for entering card details.
The client enters the card details and confirms the payment.
The partner sends a payment creation request to QIWI, providing the payment identifier, payment amount, card data, and indicating a single-step payment process (flags:[SALE]).

If flags:[SALE] is not included, the payment will be processed in a two-step scenario: the client’s funds will be held after the clients confirms the payment on the payment form, and only debited after QIWI receives confirmation from the partner.
QIWI returns the payment status to the partner (WAITING — created, awaiting client authentication through 3D-Secure), along with authentication data: pareq and acsUrl.
The partner uses the received data to authenticate the client and informs QIWI of successful authentication: refer to steps in the article «Internet Acquiring» → 3D-Secure.
QIWI sends a request for payment authorization and confirmation to the issuing bank through the payment system (payment processing network).
The issuing bank reserves (holds) and immediately debits the client’s funds from the card.
QIWI records the successful debit and returns the payment status COMPLETED to the partner.
The partner makes a decision about the successful completion of the payment. To do this, they perform the actions specified in the article «General Principles and Rules» → «Decision on Transaction Success».

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        60 }}}%%
sequenceDiagram
    participant С as Client
    participant P as Partner
    participant Q as QIWI
    participant B as Issuing Bank
    С->>P: Selects product or service, initiates payment
    Note right of С: Enters card details
    P->>+Q: Payment creation request
    Note right of P: siteId, paymentId, amount, cardData, flags: SALE
    Q->>-P: Payment Creation Response
    Note left of Q: siteId, paymentId, amount, status:WAITING, requirements.threeDS.pareq, requirements.threeDS.acsUrl
    rect rgb(230, 230, 230)
    Note over С, B: Client authentication using 3D-Secure 3D-Secure
    end
    Q->>+B: Request for payment authorization and confirmation
    Note right of Q: Through the payment system (payment processing network)
    B->>B: HOLD
    B->>B: CAPTURE
    B->>-Q: Response to request
    Note left of B: ОК
    Q->>Q: Payment completion
    Q->>P: Payment status
    Note left of Q: status:COMPLETED
    rect rgb(255, 238, 223)
    Q->>P: «Decision on Transaction Success» scenario
    P->>Q: 
    end
    P->>С: Displays result on form
    Note right of С: «Payment successful»

The QIWI element on the diagram represents a combination of participants engaged in the payment process. The scenarios referred to in the diagram can be found in the following articles:

«3D-Secure».
«General Principles and Rules» → «Decision on Transaction Success».

The partner receives, processes, and stores client card data.

Payment Creation RequestPayment Creation Response

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  },
  "flags": [ "SALE" ]
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "1811",
    "billId": "autogenerated-a29ea8c9-f9d9-4a60-87c2-c0c4be9affbc",
    "createdDateTime": "2019-08-15T13:28:26+03:00",
    "amount": {
        "currency": "RUB",
        "value": 1.00
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "444444******1049",
        "rrn": "123",
        "authCode": "181218",
        "type": "CARD"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-15T13:28:26+03:00"
    },
    "requirements" : {
        "threeDS" : {
          "pareq" : "eJyrrgUAAXUA+Q==",
          "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
        }
    }
}

Request and response are provided as an example: for the current format and list of parameters, refer to the API documentation.

Examples of client authentication requests can be found in the article «3D-Secure».

Two-step Scenario¶

A successful payment example using a single-step scenario is described and illustrated below. In this example, the payment is made using a bank card.

Please note

The two-step scenario only allows for the one payment method to be used — via bank card.

The client selects a product or service on the partner’s trading platform and proceeds to payment.
The partner displays its own payment form to the client for entering card details.
The client enters the card details and confirms the payment.
The partner sends a payment creation request to QIWI, providing the payment identifier, the payment amount and the card data.
QIWI returns the payment status to the partner (WAITING — created, awaiting client authentication through 3D-Secure), along with authentication data: pareq and acsUrl.
The partner uses the received data to authenticate the client and informs QIWI of successful authentication: refer to steps in the article «Internet Acquiring» → 3D-Secure.
QIWI sends a request for payment authorization to the issuing bank through the payment system (payment processing network).
The issuing bank reserves (holds) the client’s funds from the card.
QIWI records the successful hold.
The partner performs the actions outlined in the article «General Principles and Rules» → «Decision on Transaction Success».
The partner performs necessary actions before obtaining funds from the client - debits them from their card.

Order collection, etc.
The partner sends to QIWI a payment confirmation request, in which they transmit the payment identifier.

By default, QIWI expects payment confirmation within 72 hours from the moment of its successful authorization - payment of the bill. After this period, the payment is automatically confirmed. To change the waiting period or configure automatic payment cancellation, please contact customer support. The waiting period cannot exceed 5 days.
QIWI sends a request for payment confirmation to the issuing bank through the payment system (payment processing network).
The issuing bank debits the client’s funds from the card.
QIWI records the successful completion of the payment.
The partner makes a decision about the successful completion of the payment. To do this, they perform the actions specified in the article «General Principles and Rules» → «Decision on Transaction Success».

%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        60 }}}%%
sequenceDiagram
    participant С as Client
    participant P as Partner
    participant Q as QIWI
    participant B as Issuing Bank
    С->>P: Selects product or service, initiates payment
    Note right of С: Enters card details
    P->>+Q: Payment creation request
    Note right of P: siteId, paymentId, amount, cardData
    Q->>-P: Payment creation response
    Note left of Q: siteId, paymentId, amount, status:WAITING, requirements.threeDS.pareq, requirements.threeDS.acsUrl
    rect rgb(230, 230, 230)
    Note over С, B: Client authentication using 3D-Secure 3D-Secure
    end
    Q->>+B: Request for payment authorization
    Note right of Q: Through the payment system (payment processing network)
    B->>B: HOLD
    B->>-Q: Authorization result
    Note left of B: ОК
    Q->>Q:  Operation status
    Note over Q: Funds are held
    rect rgb(255, 238, 223)
    Q->>P: «Decision on Transaction Success» scenario
    Note left of Q: paymentId
    P->>Q: 
    end
    P->>С: Displays result
    Note left of P: Order is being prepared
    P->>P: Preparing the order
    Note over P: The order is ready for shipping
    P->>+Q: Payment confirmation request
    Note right of P: siteId, paymentId, captureId
    Q->>+B: Request for payment confirmation
    Note right of Q: Through the payment system (payment processing network)
    B->>B: CAPTURE
    B->>-Q: Confirmation result
    Note left of B: ОК
    Q->>Q:  Payment status
    Note over Q: COMPLETED
    Q->>-P: Payment confirmation response
    Note left of Q: siteId, paymentId, captureId, amount, status: COMPLETED
    rect rgb(255, 238, 223)
    Q->>P: «Decision on Transaction Success» scenario
    Note left of Q: paymentId
    P->>Q: 
    end
    P->>С: Displays result
    Note left of P: Order shipped

The QIWI element on the diagram represents a combination of participants engaged in the payment process. The scenarios referred to in the diagram can be found in the following articles:

«3D-Secure».
«General Principles and Rules» → «Decision on Transaction Success».

The partner receives, processes, and stores client card data.

Payment Creation RequestPayment Creation ResponseNotification of Successful Payment AuthorizationPayment Confirmation Request

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  }
}

HTTP/1.1 200 OK
Content-Type: application/json
{
    "paymentId": "1811",
    "billId": "autogenerated-a29ea8c9-f9d9-4a60-87c2-c0c4be9affbc",
    "createdDateTime": "2019-08-15T13:28:26+03:00",
    "amount": {
        "currency": "RUB",
        "value": 1.00
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "444444******1049",
        "rrn": "123",
        "authCode": "181218",
        "type": "CARD"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-15T13:28:26+03:00"
    },
    "requirements" : {
        "threeDS" : {
          "pareq" : "eJyrrgUAAXUA+Q==",
          "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
        }
    }
}

See the «Internet Acquiring» → «Notifications» section.

PUT /partner/payin/v1/sites/test-00/payments/804900/capture/cap1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

Request and response are provided as an example: for the current format and list of parameters, refer to the API documentation.

Examples of client authentication requests can be found in the article «3D-Secure».