Partner Form Payment¶

General Information¶

The partner can implement payments using its own payment form through 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 and debited immediately 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 displays its own payment form to the client for entering card details.
3. The client enters the card details and confirms the payment.

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

5. QIWI returns the payment status to the partner (WAITING — created, awaiting client authentication through 3D-Secure), along with authentication data: pareq and acsUrl.

6. The partner uses the received data to authenticate the client and informs QIWI of successful authentication: refer to steps in the article «Payments» → «Internet Acquiring» → 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 debit and returns the payment status COMPLETED to the partner.
10. 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».

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: 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"
        }
    }
}

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.

1. The client selects a product or service on the partner’s trading platform and proceeds to payment.
2. The partner displays its own payment form to the client for entering card details.
3. The client enters the card details and confirms the payment.
4. The partner sends a payment creation request to QIWI, providing the payment amount and the card data.
5. QIWI returns the payment status to the partner (WAITING — created, awaiting client authentication through 3D-Secure), along with authentication data: pareq and acsUrl.
6. The partner uses the received data to authenticate the client and informs QIWI of successful authentication: refer to steps in the article «Payments» → «Internet Acquiring» → 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 hold.

10. The partner performs the actions outlined 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.

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

    Order collection, etc.

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

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

14. The issuing bank debits the client’s funds from the card.
15. QIWI records the successful completion of the payment.
16. 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».

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

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

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

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