QIWI Payment Form¶

The QIWI form is designed for filling payment details for the purchase of goods or services. When paying with the QIWI form, the partner does not receive, process, or store clients payment data (such as card details). The form handles this.

Customization¶

Customization allows you to configure the appearance of the form.

The following elements can be customized:

Element	Requirements	Customization is required
Logo	PNG or SVG format, size 48x48 or proportional larger	✅
Buttons color	HEX format	✅
Provider or service name		✅
Service agreement link

To customize the form, contact the support service and provide:

A list of elements that require customization (see table above).
siteId and a unique style code for the form (you can use numbers, Latin letters, and hyphens -).

As a result, the code, and therefore the appearance of the form, will be associated with a specific siteId.

To apply a style to the form, pass the code in the:

themeCode parameter of the customFields object in the invoice creation request if the scenario involves payment using the API.

Example

"themeCode": "merchant01-theme01"
extras[themeCode] in the direct form call if the scenario involves payment without using the API.

Example

...&extras[themeCode]=merchant01-theme01

Please note

The code value is case-sensitive.

Form Example

PAY-FORM

Form URL¶

The URL of the QIWI payment form is returned in response to the invoice creation request , and is contained in the payUrl parameter. The partner directs the client to the received URL for order payment.

payUrl example

https://oplata.qiwi.com/form?invoiceUid=606a5f75-4f8e-4ce2-b400-967179502275

The partner can independently add parameters to the original payUrl:

Parameter	Description	Value
successUrl	See the «URL for Successful Payment» section	URL-encoded string
lang	Form language. The default language is Russian (`ru`)	`ru`, `en`
paymentMethod	See the «Payment Methods» section in the «Payment Acceptance» article → «QIWI Form Payment» → «QIWI Form Payment using the API»	`CARD`, `SBP`, `QIWI_WALLET`

payUrl example successUrl parameter

https://oplata.qiwi.com/form?invoiceUid=606a5f75-4f8e-4ce2-b400-967179502275&successUrl=https://example.com/payments/#introduction

Opening the Form in an Iframe¶

When opening the URL of the form in an iframe (iframe src="<payUrl link>..." />), the partner can use the postMessage method to track the form’s states.

Possible states:

INITIALIZED — form loaded.
PAYMENT_ATTEMPT — payment attempt.
PAYMENT_SUCCEEDED — successful payment.
PAYMENT_FAILED — payment failed.
INITIALIZATION_FAILED — form loading error.

iframe event handler example

window.addEventListener('message', function (event) {
    switch (event.data) {
        case 'INITIALIZED':
            // form loaded
            break;
        case 'PAYMENT_ATTEMPT':
            // payment attempt
            break;
        case 'PAYMENT_SUCCEEDED':
            // successful payment
            break;
        case 'PAYMENT_FAILED':
            // payment failed
            break;
    }
}, false)

Please note

If the form is opened in an iframe from the partner’s website, QIWI Wallet payment may not be available: during authentication in QIWI Wallet, cookies of the qiwi.com domain are set, and some browsers block the setting of cookies from third-party domains. See the WebKit documentation for details.

URL for Successful Payment¶

After payment on the QIWI form, the client can be redirected from the form to a specific page on the partner’s website via successUrl. The client will be at successUrl 3-10 seconds after a successful transaction.

When the client is redirected to successUrl, the partner can understand that the client has paid for the goods or services, and the status of the transaction in QIWI will change shortly.

Please note

To make a decision regarding the success of a transaction, the partner needs to follow the actions outlined in the article «General Principles and Rules» → «Decision on Transaction Success».

The URL should be specified in UTF-8 encoding.

Language¶

The form supports two languages: Russian and English. The default language is Russian, but this can be changed by contacting the support manager.