Feedback
bss@qiwi.com
NAV Navbar
Examples

General Information

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 Secret Key for the integration

To use API and requests you need authorization parameter SECRET_KEY. Send it in Authorization HTTP header as Bearer SECRET_KEY.

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

Issue invoice to customer

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

Request body example

 {
   "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:

Parameter Description Type
billId Unique identifier in the RSP system String
amount Invoice amount data Object
amount.value Amount of invoice rounded down to two decimals Number(6.2)
amount.currency Invoice currency (Code Alpha-3 ISO 4217) String
expirationDateTime 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. URL encoded string
YYYY-MM-DDhh:mm+\-hh:mm

In response you receive the following data:

Response body example

 {
    "siteId": "23044",
    "billId": "893794793973",
    "amount": {
      "value": 100,
      "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

Request details

Redirect the customer to Payment Form URL received in response

To pay for the order, the customer has to open the link specified in payUrl parameter of the response. Redirect the customer and wait for payment callback.

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.

Processed Payment Notifications

Processed payment notification 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
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


{ "bill":
  {  
     "siteId":"23044",
     "billId":"1519892138404fhr7i272a2",
     "amount":{  
        "value":"100",
        "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"
}

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 details on server callbacks and callback types in Server Notifications.

Make refund to the customer

To make 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 body example

{
    "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

Two-Step Scenario

How to hold funds

Hold request example

{
   "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:


{
    "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 response:

Parameter Type Description
billId String Unique invoice identifier in merchant's system
siteId String Merchant's site identifier in QIWI Kassa
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: RUB, USD, EUR)
status Object Invoice status data
status.value String Invoice current status
status.changedDateTime String Status refresh date. Date format:
YYYY-MM-DDThh:mm:ss±hh
customFields Object Additional fields including paymentFlags
customFields.AUTH String Two-step authorization transaction
customer Object Customer identifiers. Possible elements: email, phone, account
comment String Invoice comment
creationDateTime String System date of the invoice creation. Date format:
YYYY-MM-DDThh:mm:ss
payUrl String Payment Form URL
expirationDateTime String Expiration date of the payment form URL. Date format:
YYYY-MM-DDThh:mm:ss+\-hh:mm

Obtain transaction id for capture operation

Notification 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":"444444\*\*\*\*\*\*4444",
      "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 callback. Take paymentId parameter from the callback for capture operation.

paymentId String Unique payment identifier in the merchant's system
type String Operation type
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)
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

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,
      "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
  }
}
{
    "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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

{
  "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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 body example

{
  "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 body example

{
    "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"
    }
}
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:

"requirements" : {
    "threeDS" : {
      "pareq" : "eJyrrgUAAXUA+Q==",
      "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
    }
}

2. Complete customer authentication (optional)

Send HTTP PUT request to API URL with {API_REQUEST}

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

with the parameters:

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

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

curl https://api.qiwi.com/partner/payin/v1/sites/test-01/payments/2820220333/captures/43234
-X PUT
-H 'Accept: application/json'
-H 'Content-Type: application/json'
-H 'Authorization: Bearer NDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE
-d ‘{}'

Requests, Statuses and Errors

Payment

{
  "callbackUrl": "https://example.com/callbacks",
  "comment": "Example payment",
  "paymentId": "string",
  "billId": "string",
  "amount": {
    "currency": "RUB",
    "value": 200
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "CARDHOLDER NAME"
  },
  "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"
  },
  "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"
  },
  "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}

Payment Status

{
  "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"
  },
  "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }

[CAPTURE]: Payment Confirmation

{
  "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }

Refund

{
  "refundId": "tcwv3132",
  "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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",
  "cause" : {
    "amount" : [ "Invalid format. Amount value must be greater then zero" ]
  }
}
{
  "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"
}
{
  "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"
}
{
  "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"
}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"

}
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }
{
  "serviceName":"payin-core",
  "errorCode":"internal.error",
  "userMessage":"Internal error",
  "description":"Internal error",
  "traceId":"3fb3420ee1795dcf",
  "dateTime":"2020-02-12T21:28:01.813+03:00"
 }

Rejection Reasons

Payment rejection reason code 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: payment, capture, refund, and bill.

A notification is an inbound POST request with body containing JSON serialized payment data in UTF-8 codepage.

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, you ought to accept notifications from the following IP addresses belonging to QIWI:

Notification is treated as successfully delivered if RSP server responds with HTTP code 200 OK. Therefore, our system will repeat notification delivery attempts with incremental time during the day until it receives 200 OK HTTP code server response.

RSP's notification server address is specified 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.

Notification Authorization

You need to verify the inbound notification's digital signature. It is placed in X-Api-Signature-SHA256 HTTP header with UTF-8 encoding. We use HMAC integrity test with SHA256 hash.

Use the signature verification algorithm:

  1. Join values of some parameters from the notification with "|" separator:

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

    where {*} – notification parameter value. All values are treated as strings. Make sure strings are UTF-8 encoded.

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

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

    • secret_key – HMAC function key;
    • parameters – string from step 1;
  3. Compare X-Api-Signature-SHA256 HTTP header value with the result of step 2.

PAYMENT, CAPTURE, REFUND Notification Types

PAYMENT/REFUND/CAPTURE Notification example

{
   "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"
      },
      "customer":{
         "ip":"79.142.20.248",
         "account":"token32",
         "phone":"0"
      },
      "billId":"testing122",
      "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
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
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

These notifications are sent when you use Checkout. The notification is sent as soon as the invoice is paid.

BILL Notification example

{
   "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:

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

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.

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.