Feedback
bss@qiwi.com
NAV Navbar
Examples

General Information

Last update: 2020-06-19 | Edit on GitHub

Online payments protocol allows RSP to start accepting fast and secure payments from credit cards.

The protocol provides fully functional API for payment operations. API implements REST principles and uses HTTPS application protocol. Parameters are transferred by HTTP PUT method in the request body JSON data.

Ways of Integration

Online payments protocol provides several ways of integration:

Available API Methods

Method API Checkout
One-step funds authorization + +
Two-steps funds authorization + +
Card tokenization + +
Token payment + -

Steps to Start

To start using Protocol, you need to complete three simple steps.

Step 1. Leave request to integrate on b2b.qiwi.com

After processing requests, our personnel will contact you to discuss possible ways of integration, collect the necessary documents and start integration.

Step 2. Get access to your Account

Upon connecting to the Protocol, we provide your ID and access to your Account in our system. We send the Account credentials to your e-mail address specified on Step 1.

Step 3. Issue Token for the integration

To use API and requests you need authorization parameter Token. Send its value in Authorization HTTP header as Bearer Token.

Test and Production Mode

Send all requests to URL:

https://api.qiwi.com/partner{API_REQUEST}

The URL pathname's variable part {API_REQUEST} is request-specific. In this documentation, only {API_REQUEST} part is specified in the requests description.

Upon completion of three steps, your ID is in test mode by default. You can proceed operations, but without debiting credit card. See Test Data for details.

Test environment has restrictions on the total amount and number of operations. By default, maximum amount of a test transaction is 10 rubles. Maximum number of test transactions is 100 per day (MSK time zone). Only test transactions within allowed amount are taken into account.

When integration on your side is completed, we turn your ID to production mode (cards are debited).

Checkout

Quick Start

1. Issue invoice to customer

First, obtain a link to Payment Form and redirect the customer there.

Request example

PUT /partner/bill/v1/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "expirationDateTime": "2018-04-13T14:30:00+03:00"
}

Send HTTP PUT-request to API URL with {API_REQUEST}:

/bill/v1/bills/{billId}

with parameters:

Request details

In response you receive the following data:

Response example

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

{
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100.00,
      "currency": "RUB"
    },
    "status": {
      "value": "WAITING",
      "changedDateTime": "2018-03-05T11:27:41+03:00"
    },
    "comment": "Text comment",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}
Parameter Type Description
billId String Unique invoice identifier in the merchant's system
siteId String Merchant's site identifier in QIWI Kassa
amount Object Invoice amount data
amount.value Number Invoice amount. The number is rounded down to two decimals
amount.currency String Invoice currency identifier (Alpha-3 ISO 4217 code: RUB, USD, EUR)
status Object Invoice current status data
status.value String String representation of the status
status.changedDateTime String Status refresh date. Date format:
YYYY-MM-DDThh:mm:ss±hh
customFields Object Additional data
customer Object Customer data. Possible elements:
email, phone, account
comment String Comment to the invoice
creationDateTime String System date of the invoice issue. Date format:
YYYY-MM-DDThh:mm:ss±hh
payUrl String New Payment Form URL
expirationDateTime String Expiration date of the Payment Form link (invoice payment's due date). Date format:
YYYY-MM-DDThh:mm:ss±hh

Redirect the customer to the link from payUrl field. It opens the Payment Form.

2. Wait until the notification

When customer pays for the invoice, we send two server callbacks - first on the successfully processed payment, second - on the invoice payment.

2a. Processed payment notification

Processed payment notification body example

{
 "payment":{
   "paymentId":"9999999",
   "type":"PAYMENT",
   "createdDateTime":"2019-06-03T08:19:16+03:00",
   "status":{
     "value":"SUCCESS",
     "changedDateTime":"2019-06-03T08:19:16+03:00"},
   "amount":{
     "value":111.11,
     "currency":"RUB"},
   "paymentMethod":{
     "type":"CARD",
     "cardHolder":"CARD HOLDER",
     "cardExpireDate":"1/2025",
     "maskedPan":"411111******0001"},
   "gatewayData":{
     "type":"ACQUIRING",
     "authCode":"181218",
     "rrn":"123"},
   "customer":{},
   "billId":"f1e1a1f11ae111a11a111111e1111111",
   "flags":["SALE"]
 },
 "type":"PAYMENT",
 "version":"1"
}
Parameter Type Description
paymentId String Unique payment identifier in the merchant's system
type String Operation type PAYMENT
createdDateTime String System date of the payment creation. Date format:
YYYY-MM-DDThh:mm:ssZ
amount Object Payment amount data
amount.value Number Payment amount. The number is rounded down to two decimals
amount.currency String Payment currency identifier (Code Alpha-3 ISO 4217: RUB, USD, EUR)
status Object Payment status data
status.value String Current payment status
status.changedDateTime String Status refresh date. Date format:
YYYY-MM-DDThh:mm:ss±hh
paymentMethod Object Payment method data
paymentMethod.type String Payment method type. Possible values: TOKEN, CARD
paymentMethod.maskedPan String Masked card PAN
paymentMethod.cardHolder String Card holder name
paymentMethod.cardExpireDate String Card expiration date
gatewayData String Payment gateway data
gatewayData.type String Gateway type. Possible value: ACQUIRING
gatewayData.authcode String Auth code
gatewayData.rrn String RRN value (ISO 8583)
customer Object Customer identifiers. Possible elements: email, phone, account
billId String Corresponding invoice ID
flags Array of Strings Operation flags: SALE - one-step payment scenario

Invoice payment notification body example


{ 
  "bill": {  
     "siteId":"23044",
     "billId":"1519892138404fhr7i272a2",
     "amount":{  
        "value":100.00,
        "currency":"RUB"
     },
     "status": {  
        "value":"PAID",
        "datetime":"2018-03-01T11:16:12"
     },
     "customer": {},
     "customFields": {},
     "creationDateTime":"2018-03-01T11:15:39",
     "expirationDateTime":"2018-04-01T11:15:39+03:00"
  },
  "version":"1"
}

2b. Invoice payment notification

Parameter Type Description
billId String Unique invoice identifier in the merchant's system
siteId String Merchant's site identifier in QIWI Kassa
amount Object Invoice amount data
amount.value Number Invoice amount. The number is rounded down to two decimals
amount.currency String Invoice currency (Code Alpha-3 ISO 4217: RUB, USD, EUR)
status Object Invoice status data
status.value String Current invoice status
status.changedDateTime String Status refresh date. Date format:
YYYY-MM-DDThh:mm:ss±hh
customFields Object Additional fields
customer Object Customer data. Possible elements: email, phone, account
comment String Comment to the invoice
creationDateTime String System date of the invoice creation. Date format:
YYYY-MM-DDThh:mm:ss
payUrl String Payment Form link
expirationDateTime String Expiration date of the pay form link (invoice payment's due date). Date format:
YYYY-MM-DDThh:mm:ss+\-hh:mm

See description of server notifications and their types in Server Notifications.

How to make refund to the customer

If you need to make a refund of the operation, send refund request.

Send HTTP PUT request to API URL with {API_REQUEST}:

/bill/v1/bills/{billId}/refunds/{refundId}

Request refund example

PUT /partner/bill/v1/bills/893794793973/refund/1 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "amount": {
         "currency": "RUB",
         "value": 42.24
    }
}
Parameter Type Description
billId String Unique invoice identifier
refundId String Unique refund identifier in the merchant's system
amount Object Invoice amount data
amount.value Number Invoice amount rounded down to two decimals
amount.currency String Invoice currency (Code Alpha-3 ISO 4217)

Request details

Payment Form

Payment Form URL

To pay for the order, the customer should open the link from payUrl parameter of the response to invoice request.

You can add the following parameter for the Payment Form URL:

Invoice URL example with extra parameter

https://oplata.qiwi.com/form?invoiceUid=606a5f75-4f8e-4ce2-b400-967179502275&successUrl=https://developer.qiwi.com/ru/payments/#introduction
Parameter Description Type
successUrl The URL to which the client will be redirected in case of successful payment. Redirect happens after successful 3DS authentication. URL must be UTF8-encoded. UTF-8 encoded string

Personalization

Personalization allows you to create a payment form with your style, customizable logo, background and color of the buttons.

To create styles, send a request to our support via payin@qiwi.com. On setting up, the name of the style (for example, codeStyle) is specified.

To use style on the Payment Form, send "themeCode":"codeStyle" field with specified style name in customFields parameter of the invoice request.

Using Payment Form style

PUT /partner/bill/v1/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
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": {},
   "customFields": {"themeCode":"codeStyle"}
}

Customer form

Two-Step Scenario

Two-step scenario includes (1) holding funds on the customer's card and (2) confirming the operation.

1. How to hold funds

Hold request example

PUT /partner/bill/v1/bills/893794793973 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {  
     "currency": "RUB",  
     "value": 42.24
   },
   "comment": "Spasibo",
   "expirationDateTime": "2019-09-13T14:30:00+03:00",
   "customer": {},
   "customFields": {},
   "paymentFlags":["AUTH"]
}

Add to the invoice request body the following parameter: "paymentFlags":["AUTH"].

Parameter Type Description
billId String Unique identifier in the RSP system
amount Object Invoice amount data
amount.value Number(6.2) Amount of invoice rounded down to two decimals
amount.currency String Invoice currency (Code Alpha-3 ISO 4217: RUB, USD, EUR)
expirationDateTime URL encoded string
YYYY-MM-DDhh:mm+\-hh:mm
Invoice due date. Time should be specified with time zone. When date is overdue, invoice status becomes EXPIRED final status and invoice payment is not possible.
paymentFlags Array of strings Additional payment options.
Use value AUTH to perform two-step scenario of funds authorization

Response example:

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

{
    "siteId": "test-01",
    "billId": "gg",
    "amount": {
        "currency": "RUB",
        "value": 42.24
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-28T16:26:36.835+03:00"
    },
    "customFields": {
        "AUTH": "true"
    },
    "comment": "Spasibo",
    "creationDateTime": "2019-08-28T16:26:36.835+03:00",
    "expirationDateTime": "2019-09-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=78d60ca9-7c99-481f-8e51-0100c9012087"
}

You receive an URL of the Payment Form in the payUrl parameter of the response.

1a. Obtain transaction id for capture operation

Notification body example

{
  "payment":
  {
    "paymentId":"804900",  <==paymentId necessary for capture operation
    "type":"PAYMENT",
    "createdDateTime":"2019-08-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2019-08-28T12:58:53+03:00"
    },
    "amount":{
      "value":1.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"444444XXXXXX4444",
      "rrn":null,
      "authCode":null,
      "type":"CARD"
    },
    "customer":{
      "phone":"75167693659"
    },
    "gatewayData":{
      "type":"ACQUIRING",
      "eci":"6",
      "authCode":"181218"
    },
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

When payment is successfully processed, you will receive server notification. Take paymentId parameter from the notification for capture operation.

You also may use the invoice status method to get actual payment status and paymentId parameter.

2. Confirm operation

Using operation ID (paymentId), you can make capture request which confirms the operation.

Request structure:

HTTP PUT request with empty body to API URL with {API_REQUEST}:

/payin/v1/sites/{siteId}/payments/{paymentId}/captures/{captureId}

where:

Request details

Requests, Statuses and Errors

Invoice creation

{
   "amount": {  
     "currency": "RUB",  
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {},
   "customFields": {}  
   }
}
{
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100.00,
      "currency": "RUB"
    },
    "status": {
      "value": "WAITING",
      "changedDateTime": "2018-03-05T11:27:41+03:00"
    },
    "comment": "Text comment",
    "creationDateTime": "2018-03-05T11:27:41",
    "expirationDateTime": "2018-04-13T14:30:00+03:00",
    "payUrl": "https://oplata.qiwi.com/form/?invoice_uid=d875277b-6f0f-445d-8a83-f62c7c07be77"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Invoice status

[
    {
        "paymentId": "12600406",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:31:49+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQX7gM3fq+hNqO0oI5prexilN1UDEMwl6FcHZZ19m7v63DtRY=",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINED",
            "changedDateTime": "2020-03-26T19:32:09+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12600433",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:32:22+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUWFvgjAQ52lBUtjD3M9++qFgCxl0i/OtJv2WT/tv8LXqG0vw==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "DECLINED",
            "changedDateTime": "2020-03-26T19:32:54+03:00",
            "reason": "ACQUIRING_NOT_PERMITTED"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        }
    },
    {
        "paymentId": "12601084",
        "billId": "d35cf63943e54f50badc75f49a5aac7c",
        "createdDateTime": "2020-03-26T19:46:21+03:00",
        "amount": {
            "currency": "RUB",
            "value": 10.00
        },
        "capturedAmount": {
            "currency": "RUB",
            "value": 10.00
        },
        "refundedAmount": {
            "currency": "RUB",
            "value": 0.00
        },
        "paymentMethod": {
            "type": "CARD",
            "maskedPan": "427638******1410",
            "rrn": "008692274763",
            "authCode": "242847",
            "type": "CARD"
        },
        "createdToken": {
            "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6",
            "name": "427638******1410"
        },
        "customer": {
            "account": "1",
            "phone": "0",
            "address": {}
        },
        "requirements": {
            "threeDS": {
                "pareq": "eJxVUdtuwjAM7b6t/1fcku04w==",
                "acsUrl": "https://ds1.mirconnect.ru:443/vbv/pareq"
            }
        },
        "status": {
            "value": "COMPLETED",
            "changedDateTime": "2020-03-26T19:46:43+03:00"
        },
        "customFields": {
            "customer_account": "1",
            "customer_phone": "0"
        },
        "flags": [
            "AFT"
        ]
    }
]
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}

Refund

{
  "amount": {
    "value": 2.34,
    "currency": "RUB"
  }
}
{
    "amount": {
      "value": 50.50,
      "currency": "RUB"
    },
    "datetime": "2018-03-01T16:06:57+03",
    "refundId": "1",
    "status": "PARTIAL"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Invoice payment confirmation for two-step scenario

{
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example capture"
}
{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": 6.77
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

API

Quick Start

Request example

PUT /partner/payin/v1/sites/Obuc-00/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"
  }
}

To make your customer perform payment, create a payment. Make the following actions:

1. Authorize payment

Send HTTP PUT request to API URL with {API_REQUEST}:

/payin/v1/sites/{siteId}/payments/{paymentId}

with parameters:

Request details

You get in response:

Response example with 3DS requirements

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"
        }
    }
}
Parameter Type Description
paymentId String Unique payment ID in RSP's system, the same as in the request
createdDateTime String System date of the payment creation. Date format:
YYYY-MM-DDThh:mm:ss
amount Object Payment amount data
amount.value Number Payment amount rounded down to two decimals
amount.currency String Payment currency (Code Alpha-3 ISO 4217)
status Object Payment status data
status.value String Current payment status
status.changedDateTime String Status refresh date. Date format:
YYYY-MM-DDThh:mm:ss±hh
customer Object Customer identifiers. Possible elements: email, phone, account

To create a payment, most often you need to proceed additional authentication for the customer. This is the case when:

In this case, in response you will receive an additional requirements object with fields:

2. Complete customer authentication (optional)

POST /partner/payin/v1/sites/Obuc-00/payments/8937947/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  },
  "cvv2": {
    "cvv2": "string"
  }
}

Send HTTP POST request to API URL with {API_REQUEST}

/payin/v1/sites/{siteId}/payments/{paymentId}/complete

with the parameters:

Request details

3. Confirm payment

Using operation ID (paymentId), you can make capture to confirm the payment operation.

Send HTTP PUT request with empty body to API URL with {API_REQUEST}

/payin/v1/sites/{siteId}/payments/{paymentId}/captures/{captureId}

where:

Request details

Capture example

PUT /partner/payin/v1/sites/Obuc-00/payments/8937947/captures/43234 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

Requests, Statuses and Errors

Payment

{
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "CARDHOLDER NAME"
  },
  "amount": {
    "currency": "RUB",
    "value": 200.00
  },
  "billId": "string",
  "customer": {
    "account": "string",
    "address": {
      "city": "Moscow",
      "country": "Russian Federation",
      "details": "Severnoe chertanovo microdistrict 1a 1",
      "region": "Moscow city"
    },
    "email": "customer@example.com",
    "phone": "+79991234567"
  },
  "deviceData": {
    "datetime": "2017-09-03T14:30:00+03:00",
    "fingerprint": "TW96aWxsYS81LjAgKHBsYXRmb3JtOyBydjpnZWNrb3ZlcnNpb24p",
    "ip": "127.0.0.1",
    "screenResolution": "1280x1024",
    "timeOnPage": 1440,
    "userAgent": "Mozilla/5.0 (platform; rv:geckoversion) Gecko/geckotrail Firefox/firefoxversion"
  },
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example payment",
  "customFields": {},
  "flags": [
    "SALE"
  ]
}
{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "paymentCardInfo": {
    "issuingCountry": "810",
    "issuingBank": "QiwiBank",
    "paymentSystem": "VISA",
    "fundingSource": "CREDIT",
    "paymentSystemProduct": "P|Visa Gold"
  },
  "customFields" : { },
  "flags" : [ ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Payment status

{
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "WAITING",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "customFields" : { },
  "flags" : [ ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Completing authentication

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  },
  "cvv2": {
    "cvv2": "string"
  }
}
{
  "paymentId" : "223E",
  "createdDatetime" : "2018-11-01T17:10:31.284+03:00",
  "amount" : {
    "currency" : "RUB",
    "value" : 200.00
  },
  "capturedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "refundedAmount" : {
    "currency" : "RUB",
    "value" : 0.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "maskedPan" : "444444******1049"
  },
  "customer" : { },
  "deviceData" : { },
  "requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
  },
  "status" : {
    "value" : "COMPLETED",
    "changedDateTime" : "2018-11-01T17:10:32.607+03:00"
  },
  "customFields" : { },
  "flags" : [ ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Payment confirmation

{
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example capture"
}
{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": 6.77
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Capture status

{
  "captureId": "bxwd8096",
  "createdDatetime": "2018-11-20T16:29:58.96+03:00",
  "amount": {
    "currency": "RUB",
    "value": 6.77
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:29:58.963+03:00"
  }
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Refund

{
  "amount": {
    "value": 2.34,
    "currency": "RUB"
  }
}
{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Refund status

{
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
}
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

All refunds status

[
 {
  "refundId": "tcwv3132",
  "createdDatetime": "2018-11-20T16:32:55.547+03:00",
  "amount": {
    "currency": "RUB",
    "value": 2.34
  },
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-20T16:32:55.55+03:00"
  },
  "flags": [
    "REVERSAL"
  ]
 }
]
{
  "serviceName" : "payin-core",
  "errorCode" : "validation.error",
  "description" : "Validation error",
  "userMessage" : "Validation error",
  "dateTime" : "2018-11-13T16:49:59.166+03:00",
  "traceId" : "fd0e2a08c63ace83"
}
{
  "serviceName" : "payin-core",
  "errorCode" : "payin.resource.not.found",
  "userMessage" : "Resource not found",
  "description" : "Resource not found",
  "traceId" : "c3564ba25e221fe3",
  "dateTime" : "2018-11-13T16:30:52.464+03:00"
}

Reasons for rejection

Code of the reason for the payment rejection is returned in status.reason field of request responses and in status.reasonCode field of notifications.

Rejection reason code Description
INVALID_STATE Incorrect transaction status
INVALID_AMOUNT Incorrect payment amount
DECLINED_BY_MPI Rejected by MPI
DECLINED_BY_FRAUD Rejected by fraud monitoring
GATEWAY_INTEGRATION_ERROR Acquirer integration error
GATEWAY_TECHNICAL_ERROR Technical error on acquirer side
ACQUIRING_MPI_TECH_ERROR Technical error on 3DS authentication
ACQUIRING_GATEWAY_TECH_ERROR Technical error
ACQUIRING_ACQUIRER_ERROR Technical error
ACQUIRING_AUTH_TECHNICAL_ERROR Error on fund authorization
ACQUIRING_ISSUER_NOT_AVAILABLE Issuer error. Issuer is not available at the moment
ACQUIRING_SUSPECTED_FRAUD Issuer error. Fraud suspicion
ACQUIRING_LIMIT_EXCEEDED Issuer error. Some limit exceeded
ACQUIRING_NOT_PERMITTED Issuer error. Operation not allowed
ACQUIRING_INCORRECT_CVV Issuer error. Incorrect CVV
ACQUIRING_EXPIRED_CARD Issuer error. Incorrect card expiration date
ACQUIRING_INVALID_CARD Issuer error. Verify card data
ACQUIRING_INSUFFICIENT_FUNDS Issuer error. Not enough funds
ACQUIRING_UNKNOWN Unknown error
BILL_ALREADY_PAID Bill already paid
PAYIN_PROCESSING_ERROR Payment processing error

Server Notifications

The Protocol supports the following notification types for API events: PAYMENT, CAPTURE, REFUND, and BILL.

PAYMENT, CAPTURE, REFUND notifications are sending on events of payment operation, payment confirmation, and refund for payment, accordingly. BILL notifications are sending when you use Checkout, as soon as the invoice is paid.

A notification is an incoming HTTP POST message. The JSON-formatted notification message contains event data in UTF-8 codepage.

Specify the notification server address in your Personal Profile on kassa.qiwi.com site in Settings section. You may also specify the address in optional callbackUrl parameter of API requests.

The notification contains a request signature which RSP should verify on its side to secure from notification fraud.

To make sure the notification is from QIWI, we recommend you to accept messages only from the following IP addresses belonging to QIWI:

To treat notification as successfully delivered, we need your notification server to respond with HTTP code 200 OK.

If your server is unavailable or responds differently, QIWI system resends the notification message several times with growing interval during the day until it receives 200 OK HTTP code server response.

Notification Authorization

HTTP headers of notification messages contain the UTF-8 encoded generated signature which you need to validate.

Notification type HTTP Header with signature
PAYMENT, CAPTURE, REFUND Signature
BILL X-Api-Signature-SHA256

To validate the signature, use the following algorithm:

  1. Join values of some parameters from the notification with the pipe "|" character. For example:

    parameters = {amount.currency}|{amount.value}|{billId}|{siteId}|{status.value}

    where {*} – notification parameter value. All values are treated as strings. Make sure strings are UTF-8 encoded. Parameters to join are specified in the notification description.

  2. Calculate hash HMAC value with SHA256 algorithm (signature string and secret key are UTF8-encoded):

    hash = HMAС(SHA256, token, parameters) where:

    • token – HMAC function key which you can obtain in your Account;
    • parameters – string from step 1;
  3. Compare the notification signature with the result of step 2. If there is no difference, the validation is successful.

PAYMENT, CAPTURE, REFUND Notification Format

Notification type is specified in type parameter.

PAYMENT/REFUND/CAPTURE Notification example

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
Signature: J4WNfNZd***V5mv2w=
Host: server.ru

{
   "payment/refund/capture":{
      "paymentId/refundId/captureId":"4504751",
      "tokenData":{
         "paymentToken":"4cc975be-483f-8d29-2b7de3e60c2f",
         "expiredDate":"2021-12-31T00:00:00+03:00"
      },
      "type":"PAYMENT",
      "createdDateTime":"2019-10-08T11:31:37+03:00",
      "status":{
         "value":"SUCCESS",
         "changedDateTime":"2019-10-08T11:31:37+03:00"
      },
      "amount":{
         "value":2211.24,
         "currency":"RUB"
      },
      "paymentMethod":{
         "type":"CARD",
         "maskedPan":"220024/*/*/*/*/*/*5036",
         "rrn":null,
         "authCode":null,
         "type":"CARD"
      },
      "paymentCardInfo": {
         "issuingCountry": "810",
         "issuingBank": "QiwiBank",
         "paymentSystem": "VISA",
         "fundingSource": "CREDIT",
         "paymentSystemProduct": "P|Visa Gold"
      },
      "customer":{
         "ip":"79.142.20.248",
         "account":"token32",
         "phone":"0"
      },
      "billId":"testing122",
      "customFields":{},
      "flags":[
         "SALE"
      ]
   },
   "type":"PAYMENT",
   "version":"1"
}
Parameter Description Type
paymentId/refundId/captureId Payment/refund/capture operation unique identifier in RSP's system String(200)
type Operation type String(200)
createdDateTime System date of the operation creation URL-encoded string
YYYY-MM-DDThh:mm:ss
amount Object Operation amount data
amount.value Operation amount rounded down to two decimals Number(6.2)
amount.currency Operation currency (Code: Alpha-3 ISO 4217) String(3)
billId Corresponding invoice ID String(200)
status Operation status data Object
status.value Invoice status value String
status.changedDatetime Date of operation status update URL encoded string
YYYY-MM-DDThh:mm:ssZ
status.reasonCode Rejection reason code String(200)
status.reasonMessage Rejection reason description String(200)
status.errorCode Error code Number
paymentMethod Payment method data Object
paymentMethod.type Payment method type String
paymentMethod.maskedPan Masked card PAN String
paymentMethod.rrn Payment RRN Number
paymentMethod.authCode Payment Auth code Number
paymentCardInfo Card information. Only in PAYMENT notifications Object
paymentCardInfo.issuingCountry Issuer country code String(3)
paymentCardInfo.issuingBank Issuer name String
paymentCardInfo.paymentSystem Card's payment system String
paymentCardInfo.fundingSource Card's type (debit/credit/..) String
paymentCardInfo.paymentSystemProduct Card's category String
customer Customer data Object
customer.phone Phone number to which invoice issued (if specified) String
customer.email E-mail to which invoice issued (if specified) String
customer.account Customer ID in RSP system (if specified) String
customer.ip IP address String
customer.country Country from address string String
customFields Fields with additional information Object
customFields.cf1 Extra field with some information to operation data String
customFields.cf2 Extra field with some information to operation data String
customFields.cf3 Extra field with some information to operation data String
customFields.cf4 Extra field with some information to operation data String
customFields.cf5 Extra field with some information to operation data String
flags Additional API commands Array of Strings. Possible values - SALE , REVERSAL
version Callback version String

By default, signature is verified for those notification fields:

PAYMENT: payment.paymentId|payment.createdDateTime|payment.amount.value

REFUND: refund.refundId|refund.createdDateTime|refund.amount.value

CAPTURE: capture.captureId|capture.createdDateTime|capture.amount.value

Callback service sorts unsuccessful notifications on the following queues:

Time of secondary sending notification may slightly shift upward.

BILL Notifications Format

BILL Notification example

POST /qiwi-notify.php HTTP/1.1
Accept: application/json
Content-type: application/json
X-Api-Signature-SHA256: J4WNfNZd***V5mv2w=
Host: server.ru

{
   "bill":{
      "siteId":"Obuc-00",
      "billId":"testing122",
      "amount":{
         "value":"2211.24",
         "currency":"RUB"
      },
      "status":{
         "value":"PAID",
         "changedDateTime":"2019-10-08T11:31:39+03"
      },
      "customer":{
         "account":"account42"
      },
      "customFields":{},
      "comment":"Spasibo",
      "creationDateTime":"2019-10-08T11:30:16+03",
      "expirationDateTime":"2019-10-13T14:30:00+03"
   },
   "version":"1"
}
Parameter Description Type
billId Invoice operation unique identifier in RSP's system String(200)
siteId RSP' site identifier in QIWI Kassa Number
amount Object Operation amount data
amount.value Operation amount rounded down to two decimals Number(6.2)
amount.currency Operation currency (Code: Alpha-3 ISO 4217) String(3)
status Invoice status data Object
status.value Invoice status value String
status.changedDatetime Date of invoice status update URL encoded string
YYYY-MM-DDThh:mm:ssZ
customer Customer data Object
customer.phone Phone number to which invoice issued (if specified) String
customer.email E-mail to which invoice issued (if specified) String
customer.account Customer ID in RSP system (if specified) String
creationDatetime Invoice creation date URL encoded string
YYYY-MM-DDThh:mm:ssZ
expirationDateTime Invoice payment due date URL encoded string
YYYY-MM-DDThh:mm:ssZ
comment Invoice comment String(255)
customFields Additional invoice data (if specified) Object
version Callback version String

By default, signature is verified for those notification fields:

amount.currency|amount.value|billId|siteId|status.value

Electronic Receipt Transfer (for Fed.Rule 54)

The payment receipt is sent in cheque optional field of bill and payment operation requests in Checkout and API methods, respectively.

Receipt Description

{
 ...
 "cheque" : {
  "sellerId" : 3123011520,
	"customerContact" : "Test customer contact",
  "chequeType" : "COLLECT",
	"taxSystem" : "OSN",
	"positions" : [
    {
      "quantity" : 1,
      "price" : {
        "value" : 7.82,
        "currency" : "RUB"
      },
      "tax" : "NDS_0",
      "paymentSubject" : "PAYMENT",
      "paymentMethod" : "FULL_PAYMENT",
      "description" : "Test description"
    }
	]
 }
}
Parameter Req. Type Description
sellerId Y Number Organization's TIN
chequeType Y Number Cash operation (1054 fiscal tag):
COLLECT – Incoming cash
COLLECT_RETURN - Cash return
CONSUME - Outcoming cash
CONSUME_RETURN - Outcoming cash return
customerContact Y String(64) Customer's phone or e-mail (fiscal tag 1008)
taxSystem Y Number Tax system (fiscal tag 1055):
OSN - General, "ОСН"
USN – Simplified income, "УСН доход"
USN_MINUS_CONSUM – Simplified income minus expense, "УСН доход - расход"
ENVD – United tax to conditional income, "ЕНВД"
ESN - United agriculture tax, "ЕСН"
PATENT – Patent tax system, "Патент"
positions Y array Commodities list
quantity Y Number Quantity (fiscal tag 1023)
price Y Number One item price, with discounts and extra charges (fiscal tag 1079)
tax Y Number VAT rate (fiscal tag 1199):
NDS_CALC_18_118 - VAT rate 18% (18/118)
NDS_CALC_10_110 – VAT rate 10% (10/110)
NDS_0 – VAT rate 0%
NO_NDS – VAT not applicable
NDS_CALC_20_120 – VAT rate 20% (20/120) (20/120)
description Y string(128) Name
paymentMethod Y Number Cash type (fiscal tag 1214):
ADVANCED_FULL_PAYMENT – payment in advance 100%. Full payment in advance before commodity provision
PARTIAL_ADVANCE_PAYMENT – payment in advance. Partial payment before commodity provision
ADVANCE – prepayment
FULL_PAYMENT – full payment, taking into account prepayment, with commodity provision
PARTIAL_PAYMENT – partial payment and credit payment. Partial payment for the commodity at the moment of delivery, with future credit payment.
CREDIT – credit payment. Commodity is delivered with no payment at the moment and future credit payment is expected.
CREDIT_PAYMENT – payment for the credit. Commodity payment after its delivery with future credit payment.
paymentSubject Y Number Payment subject (fiscal tag 1212):
COMMODITY – commodity except excise commodities (name and other properties describing the commodity).
EXCISE_COMMODITY – excise commodity (name and other properties describing the commodity).
WORK – work (name and other properties describing the work). .
SERVICE – service (name and other properties describing the service).
GAMBLING_RATE – gambling rate (in any gambling activities).
GAMBLING_PRIZE – gambling prize payment (in any gambling activities)в.
LOTTERY_TICKET – lottery ticket payment (in accepting payments for lottery tickets, including electronic ones, lottery stakes in any lottery activities).
LOTTERY_PRIZE – lottery prize payment (n any lottery activities).
GRANTING_RESULTS_OF_INTELLECTUAL_ACTIVITY – provision of rights to use intellectual activity results.
PAYMENT – payment (advance, pre-payment, deposit, partial payment, credit, fine, bonus, reward, or any similar payment subject).
AGENCY_FEE – agent's commission (in any fee to payment agent, bank payment agent, commissioner or other agent service).
COMPAUND_PAYMENT_SUBJECT – multiple payment subject (in any payment constituent subject to any of the above).
OTHER_PAYMENT_SUBJECT – other payment subject not related to any of the above.

Tokenization

The Protocol supports card tokenization. It allows you to save encrypted customer's cards and use it for recurring payments.

By default, tokenization in the protocol is disabled. Contact your personal manager to enable this option.

Payment Token Issue

Request body example

{
   "amount": {  
     "currency": "RUB",  
     "value": 2211.24
   },
   "customer": {
   	"account":"token324"
   },
   "flags":["BIND_PAYMENT_TOKEN"]
}

To issue payment card token, you need to add the following fields in the payment request:

Token notification example

{
  "payment":{
    "paymentId":"9790769",
    "tokenData":{
      "paymentToken":"66aebf5f-098e-4e36-922a-a4107b349a96",
      "expiredDate":"2021-12-31T00:00:00+03:00"
    },
    "type":"PAYMENT",
    "createdDateTime":"2020-01-23T15:07:35+03:00",
    "status":{
      "value":"SUCCESS",
      "changedDateTime":"2020-01-23T15:07:36+03:00"
    },
    "amount":{
        "value":2211.24,
        "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"4111111111",
      "cardHolder":"CARD HOLDER",
      "cardExpireDate":"12/2021",
      "type":"CARD"
    },
    "customer":{
      "ip":"79.142.20.248",
      "account":"token324",
      "phone":"0"
    },
    "billId":"testing1222213",
    "flags":["SALE"]
  },
  "type":"PAYMENT",
  "version":"1"
}

You would receive the following data in subsequent payment type notification:

Parameter Type Description
tokenData Object Card token data
tokenData.paymentToken String Card token
tokenData.expiredDate Object Token expiration date. Date format:
YYYY-MM-DDThh:mm:ss±hh:mm

You should use the obtained data for the Customer's payments.

How To Pay By Token

You can pay by token using API methods only.

Instead of card payment data, use the following parameters in paymentMethod object:

Token payment request example

{
  "amount": {
    "currency": "RUB",
    "value": 2000.00
  },
  "paymentMethod" : {
    "type": "TOKEN",
    "paymentToken" : "f42abb6c-4b6b-464e-adcc-fbdc197bd24d"
  },
  "customer": {
        "account": "token324"
  }
}
Partameter Type Description
type String Operation type, use TOKEN only
paymentToken String Card token

Make sure you specify unique customer ID related to the payment token in account field. Without this field, payment by token is impossible.

Payouts

By default, we make payouts for processed operations once every two days when 10,000 rubles reached. If you need a custom schedule for payouts, contact your personal manager.

QIWI holds a commission for each confirmed operation. If operation is rejected before the confirmation, commission will not hold. If partial refund is made before the confirmation, commission will be recalculated.

Test Data

Use production url for testing purposes.

By default, for each new RSP siteId is created in the system in testing mode. You can ask your manager to make testing mode of any of your siteId, or add new siteId in testing mode.

Test card numbers

To make tests of various payment methods and responses, use different expiry dates:

Test environment has restrictions on the total amount and number of operations. By default, maximum amount of a test transaction is 10 rubles. Maximum number of test transactions is 100 per day (MSK time zone). Only test transactions within allowed amount are taken into account.

To process 3DS operation, use unknown name as card holder name.

3DS in testing mode may be properly tested on real card number only.

Error Codes

The Online Payment Protocol API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request is invalid.
401 Unauthorized – Your API key is wrong.
403 Forbidden – The API request is hidden.
404 Not Found – The specified resource could not be found.
405 Method Not Allowed – You tried to create a payment with an invalid method.
406 Not Acceptable – You requested a format that isn't json.
410 Gone – The resource requested has been removed from our servers.
429 Too Many Requests – You're requesting too many payments.
500 Internal Server Error – We had a problem with our server. Try again later. If response body is empty, repeat the request with the same parameters. If the body is non-empty, make payment status request/invoice status request.
502 Bad Gateway - No connection to service
503 Service Unavailable – We're temporarily offline for maintenance. Please try again later.