QIWI
Feedback
bss@qiwi.com
NAV Navbar
Samples

Introduction

About API

Universal API for payments towards any payment recipients (providers).

Among the possible recipients are:

Terms and abbreviations used in the document

Token: Character line for counter-party authentication according to the standard OAuth 2.0 [RFC 6749] [RFC 6750]
API: Application Programming Interface - a set of ready-made methods provided by the application (system) for use in external software products
JSON: JavaScript Object Notation - a text data exchange format based on JavaScript [RFC 7159]
path: Parameters are passed as part of the path in URL
query: Parameters are passed in the request body as formdata
header: Parameters are passed in HTTP request header
body: Parameters are passed in the request body

Use Cases

API methods usage diagram

Basic sequence diagram

Forms API methods are described in Forms API section.

Payout API methods are described in Payout API section.

Option to implement API methods at the checkout

Below, the case of implementation of the payment at the checkout of the counter-party with API use is described.

Step 1 scenario. Payment possibility check

Stakeholder:

Primary Actor:

Actors:

Target:

Trigger:

Main success scenario:

  1. The cashier finds the payee in the system
    Request a tree of the providers directory or Request a list of providers methods are used
  2. The system requests payment details
    Provider Form methods are used
  3. The cashier enters the payment details and identification data, with the help of the system makes sure of the completeness and correctness of the entered data and begins to check the possibility of payment
  4. The system sends to API all payment details and API confirms the possibility of payment
    Payment creation method is used
  5. The cashier informs the customer about the possibility of payment and proceeds to the step 2 scenario.

Extensions:

Step 2 Scenario. Making payment

Stakeholder:

Primary Actor:

Actors:

Target:

Trigger:

Main success scenario:

  1. The cashier receives funds from the Client
  2. The Cashier initiates the payment process allowed in the payment step 1 scenario in the System.
  3. The systems makes a payment permitted in step 1 scenario Payment request execution is used
  4. The system prints the cash receipt
  5. The cashier provides a receipt for the services rendered to the Client

Alternative scenario:

Main scenario options:

Authorization

Authorization of Payout API methods

GET /partner/payout/some/method HTTP/1.1
Accept: application/json
Authorization: Bearer mF_9.B5f-4.1JqM
Host: api.qiwi.com

When calling the Payout API methods, counter-party requests are authorized by the token provided in the request and known only to the counter-party.
Token is specified in the Authorization: Bearer header [RFC 6749] [RFC 6750]

Authorization is also possible by presenting X.509 v3 certificate [RFC 5280]
In this case header Authorization: Bearer must not using

Authorization of Forms API methods

GET /partner/sinap/some/method HTTP/1.1
Accept: application/json
X-Application-Id: 83cca1c0-49f2-417a-bd88-2803058dfd77
X-Application-Secret: 2924502d-f1e4-4f06-96ed-cdce126cf499
Host: api.qiwi.com

The requests of the counter-party in calling methods Forms API does not require authorization, but must be accompanied in the headers with the identifiers defining the version of an application called X-Application-Id and access code to it X-Application-Secret

Versioning

Versioning when calling the Payment API methods

The Payment API supports method versioning. The URL used to access the method contains a suffix that specifies the required version of the method:

http[s]://<host>[:<port>][/service]/v<version>/<method>

Currently, two versions of the Payment API are supported - 1 and 2. The description of specific methods explicitly specifies the API versions in which this method can be used.

GET /partner/payout/v1/some/method HTTP/1.1
Host: api.qiwi.com

Working with methods and data

API uses REST architecture.

According to the specified architecture, this API uses the following HTTP methods (HTTP Request):

Most methods provide physical or logical idempotence (where clients can make the same call repeatedly with the same result). Although idempotent operations produce the same result on the server, the response itself may not be the same (for example, the payment status may change between requests).

GET methods are implemented as read-only operations, making them idempotent. However, this does not mean that the server should return the same result every time. Since the status of the requested object (payment) may vary.

The data in the methods are transmitted in the following ways

The returned data is passed as JSON elements of the objects.

If incoming request have an entity attached to it server uses the HTTP request header Content-Type: application/json

Similarly, to determine what type of representation is desired at client side, HTTP header Accept: application/json

API Endpoints

Test environment

To call API methods in test environment, use the following endpoints:

API Section Authorization Encryption URL
{payout.api.url} Token RSA https://api-test.qiwi.com/partner/payout/
{forms.api.url} Certificate RSA https://private-api-test.qiwi.com/partner/payout/
{forms.api.url} Token RSA https://api-test.qiwi.com/partner/sinap/
{forms.api.url} Certificate RSA https://private-api-test.qiwi.com/partner/sinap/
{payout.api.url} Token GOST https://api-gost-test.qiwi.com/partner/payout/
{forms.api.url} Certificate GOST https://private-api-gost-test.qiwi.com/partner/payout/
{forms.api.url} Token GOST https://api-gost-test.qiwi.com/partner/sinap/
{forms.api.url} Certificate GOST https://private-api-gost-test.qiwi.com/partner/sinap/

Production environment

To call API methods in production environment, use the following endpoints:

API Section Authorization Encryption URL
{payout.api.url} Token RSA https://api.qiwi.com/partner/payout/
{payout.api.url} Certificate RSA https://private-api.qiwi.com/partner/payout/
{forms.api.url} Token RSA https://api.qiwi.com/partner/sinap/
{forms.api.url} Certificate RSA https://private-api.qiwi.com/partner/sinap/
{payout.api.url} Token GOST https://api-gost.qiwi.com/partner/payout/
{payout.api.url} Certificate GOST https://private-api-gost.qiwi.com/partner/payout/
{forms.api.url} Token GOST https://api-gost.qiwi.com/partner/sinap/
{forms.api.url} Certificate GOST https://private-api-gost.qiwi.com/partner/sinap/

Forms API methods

Provider form

Description: Returns provider form

HTTP Request: GET {forms.api.url}/providers/{id}/form

Request

GET /partner/sinap/providers/mosoblgaz-podolsk/form HTTP/1.1
Accept: application/json
X-Application-Id: <X-Application-Id-String>
X-Application-Secret: <X-Application-Secret-String>
Host: api.qiwi.com

Parameters

Parameter Position Description Type
id path Required. Provider ID string

Response

Response example

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

{
  "id": "mosoblgaz-podolsk",
  "content": {
    "terms": {
      "type": "DefaultPayoutTerms",
      "id": "mosoblgaz-podolsk"
    },
    "elements": [
      {
        "type": "field",
        "name": "sinap-form-version",
        "value": "payout::mosoblgaz-podolsk, 1"
      },
      {
        "type": "field",
        "name": "account",
        "validator": {
          "type": "predicate",
          "predicate": {
            "type": "regex",
            "pattern": "^\\d{12}$"
          },
          "message": "Некорректное значение"
        },
        "view": {
          "title": "Номер лицевого счёта",
          "prompt": "Номер лицевого счёта",
          "widget": {
            "type": "text",
            "stripStaticSymbols": false
          },
          "hint": "12 цифр"
        },
        "sensitiveData": false,
        "hideFromConfirmationScreen": false
      },
      {
        "type": "field",
        "name": "payment_type",
        "validator": {
          "type": "predicate",
          "predicate": {
            "type": "regex",
            "pattern": "^1$|^2$|^3$"
          },
          "message": ""
        },
        "view": {
          "title": "Тип платежа",
          "prompt": "Тип платежа",
          "widget": {
            "type": "list",
            "choices": [
              {
                "value": "1",
                "title": "Оплата за газ"
              },
              {
                "value": "2",
                "title": "Оплата за тех обслуживание"
              },
              {
                "value": "3",
                "title": "Прочее"
              }
            ]
          }
        },
        "value": "1",
        "hideFromConfirmationScreen": false
      },
      {
        "type": "dependency",
        "condition": {
          "type": "predicate",
          "field": "payment_type",
          "predicate": {
            "type": "regex",
            "pattern": "^1$"
          }
        },
        "content": {
          "elements": [
            {
              "type": "field",
              "name": "_has_counter",
              "view": {
                "title": "Указать счётчики",
                "prompt": "Указать счётчики",
                "widget": {
                  "type": "switch",
                  "offValue": "0",
                  "onValue": "1"
                }
              },
              "value": "1",
              "hideFromConfirmationScreen": false
            },
            {
              "type": "dependency",
              "condition": {
                "type": "predicate",
                "field": "_has_counter",
                "predicate": {
                  "type": "regex",
                  "pattern": "^1$"
                }
              },
              "content": {
                "elements": [
                  {
                    "type": "field",
                    "name": "counter",
                    "validator": {
                      "type": "predicate",
                      "predicate": {
                        "type": "regex",
                        "pattern": "\\d+"
                      },
                      "message": "Некорректное значение"
                    },
                    "view": {
                      "title": "Текущие показания счетчика",
                      "prompt": "Текущие показания счетчика",
                      "widget": {
                        "type": "text",
                        "stripStaticSymbols": false
                      }
                    },
                    "sensitiveData": false,
                    "hideFromConfirmationScreen": false
                  },
                  {
                    "type": "field",
                    "name": "counter_date",
                    "validator": {
                      "type": "predicate",
                      "predicate": {
                        "type": "regex",
                        "pattern": "\\d+"
                      },
                      "message": "Некорректное значение"
                    },
                    "view": {
                      "title": "Дата снятия показаний",
                      "prompt": "Дата снятия показаний",
                      "widget": {
                        "type": "date",
                        "format": "ddMMyyyy",
                        "allowsFutureDate": false
                      }
                    },
                    "sensitiveData": false,
                    "hideFromConfirmationScreen": false
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}
Field Type Description
id string Provider Id
content/elements Array Elements Form
content/terms Terms Class Object describing payment terms (fees, limits etc.)

Response with HTTP error code (4xx, 5xx) includes FormsErrors object. For details see API Error Processing.

Reference request data about field

Description: Returns online data processing on provider field

HTTP Request: POST {forms.api.url}/refs/{id}/containers

Parameters

Request

POST /partner/sinap/refs/some-bank/containers HTTP/1.1
Accept: application/json
Content-type: application/json
X-Application-Id: <X-Application-Id-String>
X-Application-Secret: <X-Application-Secret-String>
Host: api.qiwi.com

{
    "account": "42301810000000000001"
}
Parameter Position Description Type
id path Required. Request Id string

Request body contains set of objects with this structure:

Parameter Type Description
Parameter name is given from array "params" object "type":"ref" in array elements string Parameter value determined in interface

How to use

Online check is requested if form field determined like field with extra online processing "type":"ref"

Request result can be one of the following:

Field example for which this method is used ~~~ json { "id":"some-bank", "type":"ref", "title":"Проверить номер счета", "message":"Необходимо проверить номер счета", "params":[{ "field":"account", "triggerReload": true } ] } ~~~

Structure "ref" is part of array Elements

Parameter Type Description
type const "ref" Required. Element type which is requiring online processing
title string Required. Field heading
message string Required. Checking message
id string Required. ID to request
params string Required. Array to request. Contains object parameters: pair "field" - name (parameter name from parent object field) and pair "triggerReload" - true/false (if true, when parameter value "name" is changed by user, field must be automatically update with new value)

Response

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

{
  "elements": [
    {
      "type": "field",
      "view": {
        "title": "Minimum recommended payment",
        "prompt": "Minimum recommended payment",
        "widget": {
          "type": "info"
        }, "value": "3510.00"
      }
    }
  ]
}

If successful, the response contains:

Response with HTTP error code (4xx, 5xx) includes FormsErrors object. For details see API Error Processing.

Forms API Data Models

Content

Basic container contains class object Elements with page elements.

Terms

Class object describing payment condition:

"terms": {
  "type": "DefaultPayoutTerms",
  "id": "mosoblgaz-podolsk"
}
Parameter Type Description
id String Required. Provider ID(If it differs from Form ID, Payment must be created on this ID)
type String Required. Scheme type of provider payment. Possible values:
"DefaultPayoutTerms" - The only payment scheme
sumConstraint SumConstraint Restrictions of payment value

SumConstraint

Class object describing restrictions of payment value:

{
   "type": "FixedSumConstraint",
   "sum" : {
      "currency": "643",
      "amount":"123.45"
    }
}
Parameter Type Description
type one of
"FixedSumConstraint"
"EditableSumConstraint"
Required. Type of restriction
"FixedSumConstraint" - Amount cant be changed
"EditableSumConstraint" - Amount can be changed
sum Money Amount to pay.
Can be used only to "FixedSumConstraint"
suggestedSum Money Recommended amount to pay.
Can be used only to "EditableSumConstraint"
limit Limit Limited restrictions to amount of payment
Can be used only to "EditableSumConstraint"

Elements array

Array of "Elements" class objects interface form. Each array object of this class contains parameters:

Parameter Type Description
type String Type of interface element.</br> Possible values
"field" - Element to unconditional display
"dependency" - Element with display conditions
"ref" - Element, generating online-checking
name String Variable name, that is appropriate to element form. Only to type "field"
validator Validator Checking condition of "name" value. Only to type "field".
view  View Display parameters of element form. Only to type "field".
/If it is missing, element is hidden
value String Value of displayed field (if this element is static). Only to type "field".
sensitiveData boolean If true - data in field is confidential (masking is needed on screen, receipt, logs, etc.) Only to type "field".
semantics Semantic (unnecessary) Class object, describing field semantic (to extra validation/help inputting). Только для type "field".
condition Condition Display conditions of element form. Only to type "dependency".
content Content Element description of extra interface form which is needed to be processed if condition "condition" is done . Only to type "dependency".
id String Online-request ID /refs. Only to type "ref".
message String Message about checking. Only to type "ref".
title String Field heading. Only to type "ref".
params Массив Array to sending in request /refs. Contains objects with "field" parameters - <name> и "triggerReload" - true/false (if true, while changing parameter <name> value by user, on interface form object must be automatically update with new value)
Only to type "ref".

Example with type "ref" is shown in the method description Reference request data about field.

Semantic

Optional field semantic (to extra validation/help inputting):

 "semantics": {
   "type": "LastName"
}
Parameter Type Description
type String Enum:
"FirstName"
"LastName"
"MiddleName"
"OwnerFirstName"
"OwnerLastName"
"OwnerMiddleName"
"BirthDate"
"Email"
"Phone"
"WalletPhone"

Validator

Condition block of checking variable value <name>. Parameters:

"validator":{
  "type":"predicate",
  "predicate":{},
  "message":"Проверьте номер карты"
}
Parameter Type Description
type String Checking type. Possible values:
predicate - Logical condition or set of logical conditions
message String Message, if the value hasn't completed the checking
predicate Predicate Block of checking conditions (Only for type "predicate").

Condition

"condition": {
    "type": "predicate",
    "field": "account_type",
    "predicate": {
        "type": "regex",
        "pattern": "2"
    }
}
Parameter Type Description
type String Condition type. Possible values:
"predicate" - Checking field value with logical conditions
"and" - Checking values of several fields with "AND" operator
conditions array Object contains these pairs:
"field" - <name> - field name
"type" - "validity" - checking type (find object Validator to this field and check)
Only to type "and"
predicate Predicate Only to type "predicate"
field String The field which is checking. If the checking is successful, element form is displaying.
Only to type "predicate"

Predicate

Object contains logical checking conditions.

{
  "pattern" : "^2$|^5$",
  "type" : "regex"
}
Parameter Type Description
type string Checking type. Possible values:
regex - Checking with regular expression
and - set of logical conditions with "AND" operator
pattern String или array string Applied with type "regex". Contains regular expression to check value
array Applied with type "and". Contains a set of several "predicate" objects.
Checking all conditions in array, that are combined by logical operator, specified in type

View

{
  "title": "Номер счета",
  "prompt": "Номер счета",
  "widget": {}
}
Parameter Type Description
title String Heading of form element
prompt String Hint
info String Extra information about element. Can be hidden under the help button. In text can be used Markdown language
widget Widget Type of form element and its property

Widget

Example of "widget" with "radio" elements

"widget": {
  "type": "radio",
  "choices": [{
      "value": "1",
      "title": "Номер карты"
  },
  {
      "value": "2",
      "title": "Номер счета"
  }]
}

Example of "widget" with text

"widget": {
    "type": "text",
    "mask": "dddd dddd dddd dddd?dd",
    "keyboard": "numeric"
}
Parameter Type Description
type String Element type. Possible values:
"info" - defines static text (as field value)
"text" - defines a field to input
"radio" - defines a radio button (for selecting one of many choices)
"list" - defines list of choices
mask String Mask for input
for "text" only
keyboard String Recommended keyboard type (if acceptable) - "numeric", "text" (by default).
for "text" only
stripStaticSymbols boolean Need to remove all static symbols before check value if "true"
for "text" only.
expansion Expansion Defines hidden list items
for "radio" only
choices Array of Choices List of choices
for "radio" or "list" only

Expansion

Parameter Type Description
threshold number number of items (buttons) displayed
title String Title of hidden items (buttons). If total count of items more then "threshold"

Choices array

Each array object of this class contains parameters:

Parameter Type Description
title String Position (button) title
value Number Value of selected item to processing

Payout API service methods

Request a tree of providers catalogue

Description: Request of providers catalogue
Support in API versions: All versions
HTTP Request: GET {payout.api.url}/v{version}/agents/{agentId}/points/{pointId}/providers/directory/{providerCode}

Request of the entire catalog

GET /partner/payout/v1/agents/acme/points/00001/providers/?expand=true HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Query of a child providers/categories/nodes for "money-transfer" node

GET /partner/payout/v1/agents/acme/points/00001/providers/directory/money-transfer?expand=false  HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Parameters

Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string
providerCode path Unique identifier of the provider/host. Default is root string
expand query true (default) - Return the requested {providerCode}, with all level of hosts belonging to it
false - Return the requested {providerCode}, with one level of hosts belonging to it
boolean

Response

The response to request of the entire catalogue

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

{
        "providerCode" : "root",
        "name": "Корень каталога",
        "payable" : false,
        "form": false,
        "parents": [],
        "children": [
            {
                "providerCode" : "mobile-network-operator",
                "name": "Операторы мобильной связи",
                "payable" : true,
                "form": true,
                "parents": ["root"],
                "children": [
                    {
                        "providerCode" : "mts",
                        "name": "МТС",
                        "payable" : true,
                        "form": true,
                        "parents": ["mobile-network-operator"],
                        "children": []
                    },
                    {
                        "providerCode" : "megafon",
                        "name": "Мегафон",
                        "payable" : true,
                        "form": true,
                        "parents": ["mobile-network-operator"],
                        "children": []
                    },
                    {
                        "providerCode" : "beeline",
                        "name": "Билайн",
                        "payable" : true,
                        "form": true,
                        "parents": ["mobile-network-operator"],
                        "children": []
                    }
                ]
            },
            {
                "providerCode" : "money-transfer",
                "name": "Денежные переводы",
                "payable" : false,
                "form": false,
                "parents": ["root"],
                "children": [
                    {
                        "providerCode" : "contact",
                        "name": "Денежные переводы Контакт",
                        "payable" : false,
                        "form": true,
                        "parents": ["money-transfer"],
                        "children": [
                            {
                                "providerCode" : "contact-cis",
                                "name": "Денежные переводы Контакт (СНГ)",
                                "payable" : true,
                                "form": true,
                                "parents": ["contact"],
                                "children": []
                            }
                        ]
                    },
                    {
                        "providerCode" : "unistream",
                        "name": "Денежные переводы Юнистрим",
                        "payable" : true,
                        "form": true,
                        "parents": ["money-transfer"],
                        "children": []
                    }
                ]
            }
        ]
    }

Response to the request of children providers and categories for the money-transfer host.

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

{
   "providerCode" : "money-transfer",
   "name": "Денежные переводы",
   "payable" : false,
   "form": false,
   "parents": ["root"],
   "children": [
       {
           "providerCode" : "contact",
           "name": "Денежные переводы CONTACT",
           "payable" : false,
           "form": true,
           "parents": ["money-transfer"],
           "children": []
       },
       {
           "providerCode" : "unistream",
           "name": "Денежные переводы Юнистрим",
           "payable" : true,
           "form": true,
           "parents": ["money-transfer"],
           "children": []
       }
   ]
}

The successful response contains a tree of available providers/hosts elements, with the following parameters for each of them:

Parameter Description Type
providerCode Required. Unique identifier of the provider string
name Required. Provider name (in Russian) string
payable Required. Means that the element is not a payment one and it is not possible to create a payment for it (for example, it is a host) boolean
form Required. Means that there is a form to this element that can be required from Forms API boolean
parents Required. The providerCode array of hosts this element belongs to [string]
children Recursive array of elements belonging to this element [like this object]

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Addition

form & payable combinations

"form": "payable": description
true true Payment element for which there is a form in Forms API
true false Not a payment element, for which there is a form in SINAP, with the results of processing of which it is possible to obtain the identifier of the host
false true Payment element for which there is no form in Forms API.
This type of payment does not imply working with the payer directly and setting parameters for them. The parameters are fixed and agreed upon separately
false false Not a payment element. For example, a host that contains other elements

Request of providers list

Description: Returns all providers in the form of a flat list
Support in API versions: All versions
HTTP Request: GET {payout.api.url}/v{version}/agents/{agentId}/points/{pointId}/providers

Request

GET /partner/payout/v1/agents/acme/points/00001/providers HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Parameters

Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string

Response

Response

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

[
    {
        "providerCode" : "mobile-network-operator",
        "name": "Операторы мобильной связи",
        "form": true
    },
    {
        "providerCode" : "mts",
        "name": "МТС",
        "form": true
    },
    {
        "providerCode" : "megafon",
        "name": "Мегафон",
        "form": true
    },
    {
        "providerCode" : "beeline",
        "name": "Билайн",
        "form": true
    },
    {
        "providerCode" : "contact-cis",
        "name": "Денежные переводы Контакт (СНГ)",
        "form": true
    },
    {
        "providerCode" : "unistream",
        "name": "Денежные переводы Юнистрим",
        "form": true
    },
    {
        "providerCode" : "card-token",
        "name": "Выплаты по токену карты",
        "form": false
    }
]

The successful response contains a sequential array of provider object elements, with the following parameters for each of them:

Parameter Description Type
providerCode Required. Unique identifier of the provider string
name Required. Provider name (in Russian) string
form Required. Means that there is a form to this element that can be required from Forms API boolean

The difference from the previous method is that only a list of available providers you can pay to is displayed. Therefore, the parameters of the elements are reduced to the required minimum.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Request for provider information

Description: Returns extended provider information
Support in API versions: All versions
HTTP Request: GET {payout.api.url}/v{version}/agents/{agentId}/points/{pointId}/providers/{providerCode}

Request

GET /partner/payout/v1/agents/acme/points/00001/providers/qiwi-wallet HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Parameters

Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of the payment acceptance point string
providerCode path Required. Unique identifier of the provider string

Response

Response

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

{
  "name": "Qiwi кошелек",
  "legalName": "КИВИ Банк (АО)",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "identificationLevels": {
    "RUB": [
      {
        "min": "1.00",
        "max": "15000.00",
        "identificationType": "NONE"
      },
      {
        "min": "15000.01",
        "max": "600000.00",
        "identificationType": "SIMPLIFIED"
      }
    ]
  }
}

A successful response contains complete information about the provider, the payment limits set for it, and the required identification levels in the ProviderInfo object format.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Balance request (version 1)

Description: Retrieves the balance available for making payments
Support in API versions: version 1
HTTP Request: GET {payout.api.url}/v1/agents/{agentId}/points/{pointId}/balance

Request

GET /partner/payout/v1/agents/acme/points/00001/balance HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Parameters

Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of the payment acceptance point string

Response

Response

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

{
  "balance": {
    "value": "200.00",
    "currency": "RUB"
  },
  "overdraft": {
    "value": "200.00",
    "currency": "RUB"
  },
  "available": {
    "value": "400.00",
    "currency": "RUB"
  }
}

The successful response contains information about the balance available for the payment in the format BalanceInfo.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Balance request (version 2)

Description: Retrieves the balance available for making payments by currency
Support in API versions: version 2
HTTP Request: GET {payout.api.url}/v2/agents/{agentId}/points/{pointId}/balance

Request

GET /partner/payout/v2/agents/acme/points/00001/balance HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Parameters

Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of the payment acceptance point string

Response

Response

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

{
  "RUB": {
    "balance": {
      "value": "200.00",
      "currency": "RUB"
    },
    "overdraft": {
      "value": "200.00",
      "currency": "RUB"
    },
    "available": {
      "value": "400.00",
      "currency": "RUB"
    }
  },
  "EUR": {
    "balance": {
      "value": "100.00",
      "currency": "EUR"
    },
    "overdraft": {
      "value": "100.00",
      "currency": "EUR"
    },
    "available": {
      "value": "200.00",
      "currency": "EUR"
    }
  }
}

The successful response contains information about the balance available for payment in the format BalanceInfo for each available currency.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Payout API payment methods

Create payment

Description: Registers a payment and its preparation for further execution

Support in API versions: All versions

HTTP Request: PUT {payout.api.url}/v{version}/agents/{agentId}points/{pointId}/payments/{paymentId}

Parameters

Request

PUT /partner/payout/v1/agents/acme/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6 HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Content-type: application/json
Host: api.qiwi.com

{
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "account": "9123456789"
    }
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:02:35.589Z",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
}
Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string
paymentId path Required. Unique payment ID (eg UID) string
body body Required. Payment creation object PaymentCreationParams

PaymentCreationParams object is passed in the request field filled by the partner's software:

Response

Example of a successful response body

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:02:35.646Z",
  "expirationDatetime": "2018-11-27T14:02:35.646Z",
  "status": {
    "value": "CREATED",
    "changedDateTime": "2018-11-27T14:02:35.646Z",
    "identificationType": "NONE"
  },
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "account": "9123456789"
    }
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "commission": {
    "value": "2.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:02:35.646Z",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Putin",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
}

The successful response has format of the PaymentInfo object.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Execute payment

Description: Executes unpaid payment by its ID and returns information about it

Support in API versions: All versions

HTTP Request: POST {payout.api.url}/v{version}/agents/{agentId}points/{pointId}/payments/{paymentId}/execute

Parameters

Request

POST /partner/payout/v1/agents/acme/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6/execute HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com
Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string
paymentId path Required. Unique payment ID string

Response

Response

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:06:17.108Z",
  "expirationDatetime": "2018-11-27T14:06:17.108Z",
  "status": {
    "value": "IN_PROGRESS",
    "changedDateTime": "2018-11-27T14:06:17.108Z",
    "identificationType": "NONE"
  },
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "phone": "9123456789"
    }
  },
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "commission": {
    "value": "2.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:06:17.109Z",
    "extraCharge": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Putin",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
}

The successful response has format of the PaymentInfo object.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Payment request cancellation (Reject payment)

Description: Rejects unpaid payment by its ID and returns information about it

Support in API versions: All versions

HTTP Request: POST {payout.api.url}/v{version}/agents/{agentId}points/{pointId}/payments/{paymentId}/reject

Parameters

Request

POST /partner/payout/v1/agents/acme/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6/reject HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com
Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string
paymentId path Required. Unique payment ID string

Response

Response

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:07:05.652Z",
  "expirationDatetime": "2018-11-27T14:07:05.652Z",
  "status": {
    "value": "CREATED",
    "changedDateTime": "2018-11-27T14:07:05.652Z",
    "identificationType": "NONE"
  },
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "phone": "9123456789"
    }
  },
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "commission": {
    "value": "2.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:07:05.652Z",
    "extraCharge": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Putin",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
}

The successful response has format of the PaymentInfo object.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Payment request enrichment (Update payment)

Description: Adds missing data to payment request for its execution

Support in API versions: All versions

HTTP Request: PATCH {payout.api.url}/v{version}/agents/{agentId}points/{pointId}/payments/{paymentId}

Parameters

Request

PATCH /partner/payout/v1/agents/acme/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6 HTTP/1.1
Accept: application/json
Content-Type: application/json-patch+json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

[
  {
    "op": "ADD",
    "path": "string",
    "from": "string",
    "value": {}
  }
]
Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string
paymentId path Required. Unique payment ID string
body body Required. supplemented data according to [RFC 6902]  

Response

Response

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:07:05.652Z",
  "expirationDatetime": "2018-11-27T14:07:05.652Z",
  "status": {
    "value": "CREATED",
    "changedDateTime": "2018-11-27T14:07:05.652Z",
    "identificationType": "NONE"
  },
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "phone": "9123456789"
    }
  },
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "commission": {
    "value": "2.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:07:05.652Z",
    "extraCharge": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Putin",
    "something": "something the counter-party needs"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "SIMPLIFIED"
}

The successful response has format of the PaymentInfo object.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Get all payments

Description: Finds payments by its date

Support in API versions: All versions

HTTP Request: GET {payout.api.url}/v{version}/agents/{agentId}/points/{pointId}/payments

Parameters

Request

GET /partner/payout/v1/agents/acme/points/00001/payments?limit=10 HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com
Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string
limit query Limit number of payments returned by request integer
offset query The number of payments to skip integer
from query Only payments created after this date will be returned string
to query Only payments created before this date will be returned string

Response

Response

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

[
  {
    "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
    "creationDateTime": "2018-11-27T13:44:34.034Z",
    "expirationDatetime": "2018-11-27T13:44:34.034Z",
    "status": {
      "value": "CREATED",
      "changedDateTime": "2018-11-27T13:44:34.034Z",
      "identificationType": "NONE"
    },
    "recipientDetails": {
      "providerCode": "MTS",
      "fields": {
        "phone": "9123456789"
      }
    },
    "amount": {
      "value": "200.00",
      "currency": "RUB"
    },
    "commission": {
      "value": "2.00",
      "currency": "RUB"
    },
    "customer": {
      "account": "#12345",
      "email": "usermail@mail.mail",
      "phone": "9123456789"
    },
    "source": {
      "paymentType": "WITH_EXTRA_CHARGE",
      "paymentToolType": "CASH",
      "paymentTerminalType": "ATM_CASH_IN",
      "paymentDate": "2018-11-27T13:44:34.034Z",
      "extraCharge": {
        "value": "2.00",
        "currency": "RUB"
      }
    },
    "customFields": {
    "cashier": "Putin",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
    },
    "callbackUrl": "https://domain/path",
    "identificationType": "NONE"
  }
]

The successful response has format of the PaymentInfo object.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Find payment

Description: Finds payment by its ID and returns information about it

Support in API versions: All versions

HTTP Request: GET {payout.api.url}/v{version}/agents/{agentId}/points/{pointId}/payments/{paymentId}

Parameters

Request

GET /partner/payout/v1/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6 HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com
Parameter Position Description Type
agentId path Required. Unique identifier of the agent string
pointId path Required. Unique identifier of payment acceptance site string
paymentId path Required. Unique payment ID string

Response

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:00:56.973Z",
  "expirationDatetime": "2018-11-27T14:00:56.973Z",
  "status": {
    "value": "READY",
    "changedDateTime": "2018-11-27T14:00:56.973Z",
  },
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "phone": "9123456789"
    }
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "commission": {
    "value": "2.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:00:56.973Z",
    "extraCharge": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Putin",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path",
  "identificationType": "NONE"
}

The successful response has format of the PaymentInfo object.

Response with HTTP error code (4xx, 5xx) includes CommonError object. For details see API Error Processing.

Confirmation webhook to partner

Description: Sends a notification about the payment results to the counter-party's server (to callbackUrl)

HTTP Request: POST {callbackUrl}

Parameters

Request

POST /path/webhook HTTP/1.1
Content-Type: application/json
QIWI-Signature: 2cc6b2e0cd00f701d9d5510a6e5d4a6a67f9e5a61d7f8e4a203d3ae81b9­ae2b
Host: example.com

{
  "agentId": "acme",
  "pointId": "00001",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
    "value": "FAILD",
    "changedDateTime": "2018-12-14T10:43:18.574Z",
    "errorCode": "INTERNAL_ERROR",
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  }
}
Parameter Position Description Type
callbackUrl path Required. Call address from PaymentCreationParams string
paymentId path Required. Unique payment ID string
pointId path Required. Unique identifier of payment acceptance site string
QIWI-Signature header Required. Webhook signature. To verify, construct string by template: {paymentId}|{status.value}|{amount.value}|{amount.currency} where {path} takes value of the path parameter in JSON payload. Compute HMAC of SHA256 hash function with constructed string as data and your secret key as key. string
body body Required. WebhookPaymentInfo

The method is initialized only if the callbackUrl element of PaymentCreationParams object was provided at the time of payment creation.

Response

Response body is not analyzed.

HTTP request-specific response codes:

Code Description
XXX Any code other than 200 is considered an error. The system will continue to repeat the notification

Payout API data models

Customer

Optional object unambiguously describing the payer (does not contain data identifying the payer according to the legislation of the Russian Federation).

Parameter Type Description
account String Payer account's number etc
email String Payer's e-mail
phone String Payer's phone number

Document

General description of the identity document.

Parameter Type Description
one of Required. Passport
ForeignPassport
Visa
MigrationCard
ResidencePermit
RefugeeCertificate
one of the listed types of documents

DocumentSimplified

General description of the identity document (simplified form).

Parameter Type Description
one of Required. PassportSimplified one of the listed types of documents

ForeignPassport

Foreign citizen's passport.

Parameter Type Description
serial String Document Series
number String Required. Document number
issuer String Issued by
issueDate String Required. Date of issue or effective date (in YYYY-MM-DD format)
expiryDate String Valid until (in YYYY-MM-DD format)

Identification

Optional identification data of the payer.

Parameter Type Description
one of IdentificationFull
IdentificationSimple
one of the listed types

IdentificationFull

Data on full identification of the payer.

Parameter Type Description
type Required. IdentificationType FULL only
person Required. Person Full details of the payer
document Required. Document Main identity document
extraDocuments array of Document objects Additional identity documents

IdentificationSimple

Data on simplified identification of the payer.

Parameter Type Description
type Required. IdentificationType SIMPLIFIED only
person Required. PersonSimplified Simplified data on the payer
document Required. DocumentSimplified Simplified data on the identity document

IdentificationType

Type of identification required or provided.

Parameter Type Description
value String Required. Identification provided
Enum
"NONE"
"FULL"
"SIMPLIFIED"

MigrationCard

Migration card.

Parameter Type Description
serial String Required. Series
number String Required. Number
arrivalDate String Required. Arrival date (in YYYY-MM-DD format)
departureDate String Required. Date of expected departure (in YYYY-MM-DD format)

Passport

Full details of the passport of the Russian Federation citizen.

Parameter Type Description
serial String Required. Series
number String Required. Number
issuer String Required. Issued by
issueDate String Required. Date of issue (in YYYY-MM-DD format)
divisionCode String Required. Sub-division code (in NNN-NNN format)

PassportSimplified

Simplified data of the passport of the Russian Federation citizen.

Parameter Type Description
serial String Required. Series
number String Required. Number

PaymentCreationParams

Payment creation object.

{
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "phone": "9123456789"
    }
  },
  "amount": {
    "value": "20000.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:02:35.589+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "https://domain/path",
  "identification": {}
}
Parameter Type Description
recipientDetails RecipientDetails Required. Object describing the payment recipient
amount Money Required. Object describing the payment amount
customer Customer Object describing the payer
source Source Object describing the payment instrument
customFields map[String, String] A list of additional data the payment can be accompanied by
callbackUrl String Method call address Notification
identification Identification Identification data describing the payer according to the legislation of the Russian Federation

PaymentInfo

The object of payment existing in the system.

{
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "acсount": "9123456789"
    }
  },
  "amount": {
    "value": "20000.00",
    "currency": "RUB"
  },
  "customer": {
    "account": "#12345",
    "email": "usermail@mail.mail",
    "phone": "9123456789"
  },
  "source": {
    "paymentType": "WITH_EXTRA_CHARGE",
    "paymentToolType": "CASH",
    "paymentTerminalType": "ATM_CASH_IN",
    "paymentDate": "2018-11-27T14:02:35.589+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "https://domain/path",
  "identificationType": "NONE"
}
Parameter Type Description
paymentId String Required. Unique payment ID
creationDateTime Date Required. Payment creation date
expirationDatetime Date Required. Payment expiration date
status PaymentStatus Required. Payment status
recipientDetails RecipientDetails Required. Object describing the payment recipient
amount Money Required. Object describing the payment amount
commission Money Object describing the payment commissions
customer Customer Object describing the payer
source Source Object describing the payment instrument
customFields map[String, String] List of additional data that accompanied the payment
callbackUrl String Method call address Notification
identificationType IdentificationType Required. Identification provided

PaymentStatus

Information about the current status of the payment.

"status": {
    "value": "IN_PROGRESS",
    "changedDateTime": "2018-11-27T14:06:17.108+03:00",
  }
"status": {
  "value": "FAILED",
  "changedDateTime": "2018-11-27T14:06:17.108+03:00",
  "errorCode": "BILLING_DECLINED",
  "errorMessage": "Параметр платежа указан неверно."
    }
Parameter Type Description
value String Required. Payment status.
Enum
"CREATED" created, but not ready for payment
"READY" created and ready for payment
"FAILED"
"IN_PROGRESS" in the process of execution (status not fixed)
"COMPLETED" executed
"EXPIRED"
changedDateTime Date Required. Time of the status change.
identificationType IdentificationType Identification level required for payment
errorCode String Error code.
Enum
"INTERNAL_ERROR" error without explanation
"POINT_LIMIT_EXCEED" payment limits exceeded for agent or point
"INSUFFICIENT_FUNDS" forbidden amount or currency of payment
"IDENTIFICATION_FAILED" payer identification failed
"BILLING_DECLINED" provider billing rejected the payment
errorMessage String Detailed description of errorCode
identificationTypeRequired IdentificationType Identification level required for payment
fraudApproveRequired boolean Default value false. true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж успешно исполнен. Фактическое неисполнение платежа кассиру и клиенту не раскрывается (платеж приостанавливается)
clientApproveRequired boolean Default value false. При значении true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж имеет потенциально подозрительную окраску. Клиент может отказаться от проведения платежа или подтвердить его исполнение

Person

Full data on the payer (without documents).

Parameter Type Description
fullName PersonFullName Required. Full Name
birthDate String Required. Date of birth
citizenship String Required. Citizenship
birthPlace String Place of birth
registrationAddress String Place of registration
residentialAddress String Residential address

PersonFullName

Full name of the payer.

Parameter Type Description
firstName String Required. Name
lastName String Required. Last name
middleName String Patronymic or Second name (not necessarily only in case of its absence)

PersonSimplified

Simplified data on the payer (without documents).

Parameter Type Description
fullName PersonFullName Required.
birthDate String Required. Date of birth
citizenship String Required. Citizenship

RecipientDetails

  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789"
    }
  }
Parameter Type Description
providerCode String Required. Recipient code
Enum
bank-card-russia Payouts to cards (Russia)
bank-card-token Payouts to cards by token
self-employed-bank-card Payments to cards for self-employed people
self-employed-card-token Payments to cards by token for self-employed people
self-employed-bank-card-tax-payment Payments to cards with tax payment for self-employed people
self-employed-bank-card-qmm Payments to QIWI Mir Metal cards for self-employed people
qiwi-wallet Payments to the QIWI wallet
wl-topup Replenishment of White Label client account
bank-card-ruslom Payments to cards for scrap metals sale
bank-card-ruslom-qmm Payments to QIWI Mir Metal cards for scrap metal sale
sbp-b2c Payments to Fast Payments System
sbp-mfo Payments to Fast Payments System with name verification (for microfinance organizations)
fields map[String, String] Required. Payment options

Description of payment providers

Payment to bank card (Russia only) providerCode: "bank-card-russia"

Parameter Type Description
pan string Required. Recipient's card number
cardholder_name string Recipient's name
cardholder_lastname string Recipient's surname
description string Description of the service

An example of the recipientDetails block for paying to a bank card

{
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234564543654321"
    }
  }
}

Payment to bank card using the token providerCode: "bank-card-token"

Parameter Type Description
account string Required. Card number token
cardholder_name string Recipient's name
cardholder_lastname string Recipient's surname
description string Description of the service

An example of the recipientDetails block for paying to a bank card by token

{
  "recipientDetails": {
    "providerCode": "bank-card-token",
    "fields": {
      "account": "8198425371822184"
    }
  }
}

Payment to bank card for self-employed person providerCode: "self-employed-bank-card"

Parameter Type Description
account string Required. Recipient's card number
description string Required. Description of the rendered service
inn string Required. INN of the self-employed
incomeType string Required. Source of income
name string Recipient's name
last name string Recipient's surname
customerInn string INN of the organization paying for the service
customerOrganization string Name of the organization paying for the service

An example of the recipientDetails block for payment to the bank card of the self-employed

{
  "recipientDetails": {
    "providerCode": "self-employed-bank-card",
    "fields": {
      "inn": "111111111111",
      "account": "4111111111111111",
      "incomeType": "FROM_LEGAL_ENTITY",
      "description": "Payment",
      "name": "Recipient's name",
      "lastname": "Recipient's last name",
      "customerInn": "7777777777",
      "customerOrganization": "Name of the organization paying for the service"
    }
  }
}

Payment to bank card for self-employed person using the token providerCode: "self-employed-card-token"

Parameter Type Description
account string Required. Card token
description string Required. Description of the rendered service
inn string Required. INN of the self-employed
incomeType string Required. Source of income
name string Recipient's name
last name string Recipient's surname
customerInn string INN of the organization paying for the service
customerOrganization string Name of the organization paying for the service

An example of the recipientDetails block for paying to a self-employed person's bank card using a token

{
  "recipientDetails": {
    "providerCode": "self-employed-card-token",
    "fields": {
      "inn": "111111111111",
      "account": "Card token",
      "incomeType": "FROM_LEGAL_ENTITY",
      "description": "Payment",
      "name": "Recipient's name",
      "lastname": "Recipient's last name",
      "customerInn": "7777777777",
      "customerOrganization": "Name of the organization paying for the service"
    }
  }
}

Payment to bank card of the self-employed person with the tax payment providerCode: "self-employed-bank-card-tax-payment"

Parameter Type Description
account string Required. Recipient's card number
description string Required. Description of the rendered service
inn string Required. INN of the self-employed
incomeType string Required. Source of income
name string Recipient's name
last name string Recipient's surname
customerInn string INN of the organization paying for the service
customerOrganization string Name of the organization paying for the service

An example of the recipientDetails block for payment to a self-employed person's bank card with the payment of tax

{
  "recipientDetails": {
    "providerCode": "self-employed-bank-card-tax-payment",
    "fields": {
      "inn": "111111111111",
      "account": "4111111111111111",
      "incomeType": "FROM_LEGAL_ENTITY",
      "description": "Payment",
      "name": "Recipient's name",
      "lastname": "Recipient's last name",
      "customerInn": "7777777777",
      "customerOrganization": "Name of the organization paying for the service"
    }
  }
}

Payment to Qiwi Mir Metal bank card for self-employed person providerCode: "self-employed-bank-card-qmm"

Parameter Type Description
account string Required. Recipient's card number (only Qiwi Mir Metal cards)
description string Required. Description of the rendered service
inn string Required. INN of the self-employed
incomeType string Required. Source of income
name string Recipient's name
last name string Recipient's surname
customerInn string INN of the organization paying for the service
customerOrganization string Name of the organization paying for the service

An example of the recipientDetails block for payment to the QIWI Mir Metal bank card of the self-employed person

{
  "recipientDetails": {
    "providerCode": "self-employed-bank-card-qmm",
    "fields": {
      "inn": "111111111111",
      "account": "1234564543654321",
      "incomeType": "FROM_LEGAL_ENTITY",
      "description": "Payment",
      "name": "Recipient's name",
      "lastname": "Recipient's last name",
      "customerInn": "7777777777",
      "customerOrganization": "Name of the organization paying for the service"
    }
  }
}

Payment to QIWI Wallet providerCode: "qiwi-wallet"

Parameter Type Description
account string Required. Mobile phone number

An example of the recipientDetails block for payouts to a Qiwi wallet

{
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789"
    }
  }
}

White Label Topup providerCode: "wl-topup"

Parameter Type Description
account string Required. Client ID in WL
product_id string Required. Product ID in WL

An example of the recipientDetails block for replenishing a White Label client's account

{
  "recipientDetails": {
    "providerCode": "wl-topup",
    "fields": {
      "account": "21646",
      "product_id": "company-id"
    }
  }
}

Payment to bank card for scrap metal sale providerCode: "bank-card-ruslom"

An example of the recipientDetails block for payment to bank card for scrap metal sale

{
  "providerCode": "bank-card-ruslom",
  "fields": {
      "pan": "1234564543654321",
      "lastname": "Recipient's last name",
      "name": "Recipient's first name",
      "patronymic": "Recipient's middle name",
      "acceptanceCertificate": "Acceptance certificate ID"
  }
}
Parameter Type Description
pan string Required. Recipient's card number
lastname string Required. Recipient's last name
name string Required. Recipient's first name
patronymic string Recipient's middle name
acceptanceCertificate string Required. Acceptance certificate ID

Payment to Qiwi Mir Metal bank card for scrap metal sale providerCode: "bank-card-ruslom-qmm"

An example of the recipientDetails block for payment to bank card for scrap metal sale

{
  "providerCode": "bank-card-ruslom-qmm",
  "fields": {
      "pan": "1234564543654321",
      "lastname": "Recipient's last name",
      "name": "Recipient's first name",
      "patronymic": "Recipient's middle name",
      "acceptanceCertificate": "Acceptance certificate ID"
  }
}
Parameter Type Description
pan string Required. Recipient's card number (only Qiwi Mir Metal cards)
lastname string Required. Recipient's last name
name string Required. Recipient's first name
patronymic string Recipient's middle name
acceptanceCertificate string Required. Acceptance certificate ID

Payment to Fast Payments System providerCode: "sbp-b2c"

An example of recipientDetails object for payment to Fast Payments System client

{
  "providerCode": "sbp-b2c",
  "fields": {
    "account": "79098087755",
    "bankId": "100000000001"
  }
}
Parameter Type Description
account string Required. Recipient's identifier (phone number in international format without + sign)
bankId string Required. Recipient's bank identifier in Fast Payments System. See the list of banks for Fast Payments System payments in xlsx (download) or csv format (download)

Payment to Fast Payments System with name verification (for microfinance organizations) providerCode: "sbp-mfo"

An example of recipientDetails object for payment to Fast Payments System client with name verification

{
  "providerCode": "sbp-mfo",
  "fields": {
    "phone": "79098087755",
    "bankId": "100000000001",
    "lastName": "Иванов",
    "firstName": "Иван",
    "middleName": "Иванович"
  }
}
Parameter Type Description
phone string Required. Recipient's identifier (phone number in international format without + sign)
bankId string Required. Recipient's bank identifier in Fast Payments System. See the list of banks for Fast Payments System payments in xlsx (download) or csv format (download)
lastName string Required. Recipient's last name
firstName string Required. Recipient's first name
middleName string Recipient's middle name (if available)

RefugeeCertificate

Refugee certificate details.

Parameter Type Description
serial String Required. Document series
number String Required. Document number
issuer String Required. Document issued by
issueDate String Required. Date of issue (in YYYY-MM-DD format)
validThrough String Required. Valid until (in YYYY-MM-DD format)

ResidencePermit

Residence permit details.

Parameter Type Description
serial String Required. Document series
number String Required. Document number
issuer String Required. Document issued by
issueDate String Required. Date of issue (in YYYY-MM-DD format)
validThrough String Required. Valid until (in YYYY-MM-DD format)

Source

Payment source information.

{
  "paymentType": "WITH_EXTRA_CHARGE",
  "paymentToolType": "CASH",
  "paymentTerminalType": "ATM_CASH_IN",
  "paymentDate": "2018-12-06T14:08:46.598+03:00",
  "extraCharge": {
    "value": "200.00",
    "currency": "RUB"
  },
  "chargeOffCurrency": "USD"
}
Parameter Type Description
paymentType String Required. Enum:
"NO_EXTRA_CHARGE" no extra commission charged in excess of payment
"WITH_EXTRA_CHARGE" with extra commission over payment
paymentToolType String Required. Enum:
"CASH"
"BANK_ACCOUNT"
"BANK_CARD"
"BANK_CARD_OWN" Bank card issued by this Bank
"ELECTRONIC_FUNDS" EMF
paymentTerminalType String Required. Enum:
"ATM_CASH_IN" ATM with CASH_IN
"ATM"
"AUTO_PAYMENTS"
"CASH_DESK"
"POS_TERMINAL"
"MOBILE_BANKING"
"INTERNET_BANKING"
"ELECTRONIC_WALLET"
"SELF_SERVICE_TERMINAL"
"IVR_CHANNELS"
paymentDate Date  
extraCharge Money Commission taken in excess of the payment if "paymentType": "WITH_EXTRA_CHARGE"
chargeOffCurrency String Currency of the debit account, indicates the currency of the account from which agent's funds must be debited
ISO 4217 ALFA3 Currency code

Visa

Visa to stay in Russia.

{
  "serial": "A12",
  "number": "12345",
  "visaId": "1234",
  "issueDate": "2018-12-06",
  "entryFrom": "2018-12-06",
  "stayUntil": "2018-12-06"
}
Parameter Type Description
serial String Required. Visa series
number String Required. Visa number
visaId String Required. Visa ID
issueDate String Required. Visa issue date, in YYYY-MM-DD format
entryFrom String Required. Visa valid from, in YYYY-MM-DD format
stayUntil String Required. Visa valid until, in YYYY-MM-DD format

WebhookPaymentInfo

{
  "agentId": "acme",
  "pointId": "00001",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
      "value": "COMPLETED",
      "changedDateTime": "2018-11-27T13:44:34.034+03:00",
      "identificationType": "NONE"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId":"1000200300",
  }
}
Parameter Type Description
agentId String Required. Unique identifier of agent
pointId String Required. Unique identifier of payment acceptance site
paymentId String Required. Unique payment ID
status PaymentStatus Required.
amount Money Required.

Common data models

Money

Money field description

{
  "value": "200.00",
  "currency": "RUB"
}
Parameter Type Description
value String Required. Value in units of exchange with 2 digits after point
Pattern ^([0-9]+)?[.][0-9]{2}$
currency String Required. ISO 4217 ALFA3 Currency code

Limit

Payment limits.

{
  "currency": "643",
  "min": "100.00",
  "max": "5000.00"
}
Parameter Type Description
currency String Required. ISO ALFA3 Currency code
min String Minimum amount allowed
max String Maximum amount allowed

API Errors Processing

Response codes

Top-level request processing errors, according to the REST architecture, are transmitted in the HTTP status code [RFC 2068].

Sample Payout error response

HTTP/1.1 403 Unauthorized
Content-Type: application/json

{
    "serviceName": "string",
    "errorCode": "INTERNAL_ERROR",
    "userMessage": "Message to user (in Russian)",
    "description": "Error description",
    "traceId": "string",
    "dateTime": "2018-11-27T14:24:42+03:00",
    "cause": {
        "property1": [
        "string"
        ],
        "property2": [
        "string"
        ]
    }
}

Sample Forms error response

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
     "errors" : [
        {
           "message" : "Message to user (in Russian)",
           "parameter" : "account",
           "state" : "Invalid",
           "value" : "123123"
        },
        {
            "parameter": "otherFieldName",
            "state": "Missing"
        }
     ],
     "message" : "Message to user (in Russian)"
}

Within this Protocol, the following options of HTTP codes are applied:

Code Description
200 Successful or conditionally successful
400 The request parameters are not valid, the request is not processed
401 The token(certificate) is not provided or is invalid
403 Insufficient rights to run the specified request
404 Object (e.g. payment) with these IDs is not found

Detailed decoding of the result of the request processing is transferred to the field errorCode of the requested (returned) object.

If the API has processed the request but the requested (returned) object cannot be formed, the following object is returned:

FormsError

{

   "errors" : [
     {
       "message" : "Неверный номер счета",
       "parameter" : "account",
       "state" : "Invalid",
       "value" : "42301840000000000001"
     }
   ],
   "message" : "Ошибка валидации"
}
Parameter Type Description
type String Type of error (if available)
errors FormsErrors Array of Forms Error elements
message String Required. Common error description

Element FormsErrors

 {
    "message" : "Неверный номер счета",
    "parameter" : "account",
    "state" : "Invalid",
    "value" : "42301840000000000001"
 }
Parameter Type Description
message String Required. Error description
parameter String Required. Parameter with error
state String State of parameter
value String Required. Wrong value of parameter

CommonError

  {
    "serviceName": "XXX",
    "errorCode": "internal.error",
    "userMessage": "Message to user (in Russian)",
    "description": "Error description",
    "traceId": "1236654998241657",
    "dateTime": "2018-12-06T14:08:46.598+03:00",
    "cause": {
      "msg1": ["amount>1500000"]
    }
  }
Parameter Type Description
serviceName String Required. ID of the service that generated an error (not analyzed)
errorCode String Required. Error code
userMessage String Required. Error description to display to the client
description String Required. Error description
traceId String Required. Internal identifier
dateTime Date Required. Time of error occurrence
cause map[String, array[String]] Error details, if available
If there are several details, their array shall be formed

Values of errorCode

Value of errorCode field has domain structure with . separator (dot), a system level caused the error is downgraded from left to right.

Authorization errors

Validation errors

Payment processing errors on the side of provider

Financial and law risks verification errors

General errors