QIWI Form Payment using the API¶

General Information¶

The partner can implement payments with the QIWI payment form using the API.

There are several scenarios for accepting payments:

• Single-step scenario - where authorization and payment confirmation are executed within a single API request.
• Two-step scenario - where authorization and payment confirmation are executed through separate requests.

In the single-step scenario, the client’s funds are held and immediately debited after the client confirms the payment on the payment form. It is technically impossible to reverse the debit; only refund is available.

In the two-step scenario, the client’s funds are held after the client confirms the payment on the payment form and are debited only after QIWI receives confirmation from the partner. The held funds can be reversed, and the debited funds can be refunded.

Getting Started¶

1. Follow the steps outlined in the article «Payments» → «Internet Acquiring» → «Getting Started».
2. Generate an API Access Key.

1. Conduct an API interaction test.

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.

1. The client selects a product or service on the partner’s trading platform and proceeds to payment.

2. The partner sends a invoice creation request to QIWI, providing the payment amount, invoice lifespan, 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.

3. QIWI returns the invoice status to the partner (CREATED — created, awaiting payment), along with the QIWI payment form URL payUrl.

4. The partner directs the client to the received payUrl.

   Alternatively, you can use the Checkout Popup library to open the form in a popup window.

5. The client selects a payment method, enters payment details, and clicks «Pay».

6. QIWI authenticates the client using 3D-Secure.
7. QIWI sends a request for payment authorization and confirmation to the issuing bank through the payment system (payment processing network).
8. The issuing bank reserves (holds) and immediately debits the client’s funds from the card.

9. QIWI records the successful completion of the payment — invoice payment.

   Optional steps

   Step 10 is optional and is executed only if the successUrl is configured for the partner. Details can be found in the article «Payment Form» → «URL for Successful Payment».

10. The QIWI form directs the client to the «URL for Successful Payment».

11. 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
    Note right of С: Initiates payment
    P->>+Q: Invoice creation request
    Note right of P: siteId, billId, amount, expirationDateTime, flags: SALE
    Q->>-P: Invoice creation response
    Note left of Q: siteId, billId, amount, invoiceUid, status:CREATED, expirationDateTime, payUrl
    P->>С: Redirect to the payUrl
    Note left of P: Payment form
    rect rgb(230, 230, 230)
    С->>С: Filling out the form data
    С->>Q: Code execution (API call using a form)
    rect rgb(255, 238, 223)
    Q->>+С: Client authentication using 3D-Secure 3D-Secure
    С->>-Q: 
    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: Invoice payment completion
    Q->>С: Displays result on form
    Note right of С: «Payment successful»
    opt Redirect to the successUrl (optional step)
    С->>P: 
    Note left of P: Payment status page in the partner's interface
    end
    end
    rect rgb(255, 238, 223)
    Q->>P: «Decision on Transaction Success» scenario
    P->>Q: 
    end

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».

PUT /partner/payin/v1/sites/test-00/bills/1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "amount": {
        "currency": "RUB",
        "value": 150.00
    },
    "comment": "Spasibo",
    "expirationDateTime": "2023-07-07T14:30:00+03:00",
    "flags": [
        "SALE"
    ]
}

HTTP/1.1 200 OK
Content-Type: application/json

{
    "billId": "1234567890",
    "invoiceUid": "143a6822-6ef2-478f-a30b-4ad8c044d6d8",
    "amount": {
        "currency": "RUB",
        "value": "150.00"
    },
    "expirationDateTime": "2023-07-07T14:30:00+03:00",
    "status": {
        "value": "CREATED",
        "changedDateTime": "2023-02-17T14:50:44+03:00"
    },
    "comment": "Spasibo",
    "flags": [
        "SALE"
    ],
    "payUrl": "https://oplata.qiwi.com/form?invoiceUid=143a6822-6ef2-478f-a30b-4ad8c044d6d8"
}

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.

1. The Client selects a product or service on the partner’s trading platform and proceeds to payment.
2. The partner sends a invoice creation request to QIWI, providing the payment amount and invoice lifespan.
3. QIWI returns the invoice status to the partner (CREATED — created, awaiting payment), along with the QIWI payment form URL payUrl.

4. The partner directs the client to the received payUrl.

   Alternatively, you can use the Checkout Popup library to open the form in a popup window.

5. The client selects a payment method, enters payment details, and clicks «Pay».

6. QIWI authenticates the client using 3D-Secure.
7. QIWI sends a request for payment authorization to the issuing bank through the payment system (payment processing network).
8. The issuing bank reserves (holds) the client’s funds from the card.

9. QIWI records the successful payment of the invoice.

   Optional steps

   Step 10 is optional and is executed only if the successUrl is configured for the partner. Details can be found in the article «Payment Form» → «URL for Successful Payment».

10. The QIWI form directs the client to the «URL for Successful Payment».

11. The partner makes a decision regarding the successful payment of the invoice. To do this, they perform the actions specified in the article «General Principles and Rules» → «Decision on Transaction Success».

    During the notification receipt stage, the partner receives a payment identifier for payment confirmation — paymentId.

12. The partner performs necessary actions before obtaining funds from the client - debits them from their card.

    Order collection, etc.

13. The partner sends to the QIWI a payment confirmation request, in which they transmit the payment identifier received in step 10.

    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.

14. QIWI sends a request for payment confirmation to the issuing bank through the payment system (payment processing network).

15. The issuing bank debits the client’s funds from the card.
16. QIWI records the successful completion of the payment.
17. 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
    Note right of С: Initiates payment
    P->>+Q: Invoice creation request
    Note right of P: siteId, billId, amount, expirationDateTime, `flags: SALE`
    Q->>-P: Invoice creation response
    Note left of Q: siteId, billId, amount, invoiceUid, status:CREATED, expirationDateTime, payUrl
    P->>С: Redirect to the payUrl
    Note left of P: Payment form
    rect rgb(230, 230, 230)
    С->>С: Filling out the form data
    С->>Q: Code execution (API call using a form)
    rect rgb(255, 238, 223)
    Q->>+С: Client authentication using 3D-Secure 3D-Secure
    С->>-Q: 
    end
    Q->>+B: Request for payment authorization and confirmation
    Note right of Q: Through the payment system (payment processing network)
    B->>B: HOLD
    B->>-Q: Authorization result
    Note left of B: ОК
    Q->>Q:  Invoice payment status
    Note over Q: ОК
    Q->>С: Displays result on form
    Note right of С: «Payment successful»
    opt Redirect to the successUrl (optional step)
    С->>P: 
    Note left of P: Payment status page in the partner's interface
    end
    end
    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».

PUT /partner/payin/v1/sites/test-00/bills/1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "amount": {
        "currency": "RUB",
        "value": 150.00
    },
    "comment": "Spasibo",
    "expirationDateTime": "2023-07-07T14:30:00+03:00"
}

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: api.qiwi.com

An example response to the payment creation request can be found in the «Single-step Scenario section».

Payment Methods¶

Payment Methods are configured for a specific siteId and are displayed on the QIWI form depending on certain conditions (see the table below). Payment by bank card is available by default.

Payment using Payment Token¶

The client can pay for an order with a bank card without entering details. Payment in this case is made using a payment token. To connect this payment method, contact customer support.

The issuance of a payment token is described in the article «Payment Token».

Payment using a payment token can be implemented through a single-step or two-step scenario: in the invoice creation request, you need to specify the identifier of the client for whom the token was issued (the customer.account parameter). Payment with a payment token is not possible without specifying customer.account parameter.

PUT /partner/payin/v1/sites/test-02/bills/1815 HTTP/1.1
Accept: application/json
Authorization: Bearer 7uc4b25xx93xxx5d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {
     "currency": "RUB",
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {
     "account": "token234"
   },
   "customFields": {
    "cf1": "Some data"
   }
}

If one or more tokens have been issued for a client, the QIWI form displays a list of linked payment instruments.

The client can select the desired card from the list. It is not necessary to specify payment details and pass 3D-Secure authentication.