Partner Form Payment¶

General Information¶

The partner can implement payments using its own payment form through the API.

Please Note

The partner must comply with the PCI DSS security standards and have the appropriate certificate, as bank card data accepted for payment is sensitive information.

Important Information

According to Russian Central Bank 13-MP rule the compliance of the partner’s actual activities with those declared by him at the conclusion of the contract is checked. For this, as well as to reduce the risk of invalid and fraudulent transactions, the partner needs to integrate a script designed to collect additional client data when making payments.

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¶

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

The API access key is a character string used to authorize requests to the API in accordance with the OAuth 2.0 standard (RFC 6749, RFC 6750). It is issued within your personal account under the “Settings” section.

Conduct an API interaction test.

The default siteId provided to you is in test mode. In this mode, you can perform operations without actual movement of funds. Testing is available only for certain payment methods. For more details, refer to the article «Test Mode».

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 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 «Payments» → «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: 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"
        }
    }
}

Requests and responses are provided as an example. For the actual format and list of parameters, please refer to the «API Methods Reference» section of the Payment 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 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 «Payments» → «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».

During the notification receipt stage, the partner receives a payment identifier for payment confirmation — paymentId.
The partner performs necessary actions before obtaining funds from the client - debits them from their card.

Order collection, etc.
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.
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 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: 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.»

Requests and responses are provided as an example. For the actual format and list of parameters, please refer to the «API Methods Reference» section of the Payment API documentation.

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