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 Required Type
id path Provider ID Yes 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 Required Type
id path Request Id Yes 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 Required Type Description
type Yes const "ref" Element type which is requiring online processing
title Yes string Field heading
message Yes string Checking message
id Yes string ID to request
params Yes string 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 Required Type Description
id Yes String Provider ID(If it differs from Form ID, Payment must be created on this ID)
type Yes String Scheme type of provider payment. Possible values:
"DefaultPayoutTerms" - The only payment scheme
sumConstraint No SumConstraint Restrictions of payment value

SumConstraint

Class object describing restrictions of payment value:

{
   "type": "FixedSumConstraint",
   "sum" : {
      "currency": "643",
      "amount":"123.45"
    }
}
Parameter Required Type Description
type Yes one of
"FixedSumConstraint"
"EditableSumConstraint"		 Type of restriction
"FixedSumConstraint" - Amount cant be changed
"EditableSumConstraint" - Amount can be changed
sum No Money Amount to pay.
Can be used only to "FixedSumConstraint"
suggestedSum No Money Recommended amount to pay.
Can be used only to "EditableSumConstraint"
limit No 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes string
providerCode path Unique identifier of the provider/host (Default is root) No 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		 No 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 Required Type
providerCode Unique identifier of the provider Yes string
name Provider name (in Russian) Yes string
payable 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) Yes boolean
form Means that there is a form to this element that can be required from Forms API Yes boolean
parents The providerCode array of hosts this element belongs to Yes [string]
children Recursive array of elements belonging to this element No [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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes 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 Required Type
providerCode Unique identifier of the provider Yes string
name Provider name (in Russian) Yes string
form Means that there is a form to this element that can be required from Forms API Yes 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of the payment acceptance point Yes string
providerCode path Unique identifier of the provider Yes 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of the payment acceptance point Yes 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of the payment acceptance point Yes 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes string
paymentId path Unique payment ID (eg UID) Yes string
body body Payment creation object Yes 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes string
paymentId path Unique payment ID Yes 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes string
paymentId path Unique payment ID Yes 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes string
paymentId path Unique payment ID Yes string
body body supplemented data according to [RFC 6902] Yes  

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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes string
limit query Limit number of payments returned by request No integer
offset query The number of payments to skip No integer
from query Only payments created after this date will be returned No string
to query Only payments created before this date will be returned No 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 Required Type
agentId path Unique identifier of the agent Yes string
pointId path Unique identifier of payment acceptance site Yes string
paymentId path Unique payment ID Yes 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 Required Type
callbackUrl path Call address from PaymentCreationParams Yes  
paymentId path Unique payment ID Yes string
pointId path Unique identifier of payment acceptance site Yes string
QIWI-Signature header Request signature, to verify you need to construct string by template: {paymentId}\|{status.value}\|{amount.value}\|{amount.currency} where {path} takes value of the path parameter in JSON payload, | means character '|'. Compute HMAC with SHA256 hash function with constructed string as data and your secret key as key. Yes string
body body   Yes 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 Required Type Description
account No String Payer account's number etc
email No String Payer's e-mail
phone No String Payer's phone number

Document

General description of the identity document

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

DocumentSimplified

General description of the identity document (simplified form).

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

ForeignPassport

Foreign citizen's passport

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

Identification

Identification data of the payer

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

IdentificationFull

Data on full identification of the payer

Parameter Required Type Description
type Yes IdentificationType "FULL" only
person Yes Person Full details of the payer
document Yes Document Main identity document
extraDocuments No array[Document] Additional identity documents

IdentificationSimple

Data on simplified identification of the payer

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

IdentificationType

Type of identification required or provided

Parameter Required Type Description
значение Yes String Identification provided
Enum
"NONE"
"FULL"
"SIMPLIFIED"

MigrationCard

Migration card

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

Passport

Full details of the passport of the Russian Federation citizen

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

PassportSimplified

Simplified data of the passport of the Russian Federation citizen

Parameter Required Type Description
serial Yes String Series
number Yes String 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 Required Type Description
recipientDetails Yes RecipientDetails Object describing the payment recipient
amount Yes Money Object describing the payment amount
customer No Customer Object describing the payer
source No Source Object describing the payment instrument
customFields No map[String, String] A list of additional data the payment can be accompanied by
callbackUrl No String Method call address Notification
identification No 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 Required Type Description
paymentId Yes String Unique payment ID
creationDateTime Yes Date Payment creation date
expirationDatetime Yes Date Payment expiration date
status Yes PaymentStatus Payment status
recipientDetails Yes RecipientDetails Object describing the payment recipient
amount Yes Money Object describing the payment amount
commission No Money Object describing the payment commissions
customer No Customer Object describing the payer
source No Source Object describing the payment instrument
customFields No map[String, String] List of additional data that accompanied the payment
callbackUrl No String Method call address Notification
identificationType Yes IdentificationType 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 Required Type Description
value Yes String Статус
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 Yes Date  
identificationType No IdentificationType Identification level required for payment
errorCode No 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 No String Detailed description of errorCode
identificationTypeRequired No IdentificationType Identification level required for payment
fraudApproveRequired No boolean Default value false. true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж успешно исполнен. Фактическое неисполнение платежа кассиру и клиенту не раскрывается (платеж приостанавливается)
clientApproveRequired No boolean Default value false. При значении true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж имеет потенциально подозрительную окраску. Клиент может отказаться от проведения платежа или подтвердить его исполнение

Person

Full data on the payer (without documents)

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

PersonFullName

Full name of the payer

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

PersonSimplified

Simplified data on the payer (without documents)

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

RecipientDetails

  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789"
    }
  }
Parameter Required Type Description
providerCode Yes String 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 Yes map[String, String] Payment options

Description of payment providers

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

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

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 Description Required Type
account Card number token Yes string
cardholder_name Recipient's name No string
cardholder_lastname Recipient's surname No string
description Description of the service No string

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 Description Required Type
account Recipient's card number Yes string
description Description of the rendered service Yes string
inn INN of the self-employed Yes string
incomeType Source of income Yes string
name Recipient's name No string
last name Recipient's surname No string
customerInn INN of the organization paying for the service No string
customerOrganization Name of the organization paying for the service No string

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 Description Required Type
account Card token Yes string
description Description of the rendered service Yes string
inn INN of the self-employed Yes string
incomeType Source of income Yes string
name Recipient's name No string
last name Recipient's surname No string
customerInn INN of the organization paying for the service No string
customerOrganization Name of the organization paying for the service No string

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 Description Required Type
account Recipient's card number Yes string
description Description of the rendered service Yes string
inn INN of the self-employed Yes string
incomeType Source of income Yes string
name Recipient's name No string
last name Recipient's surname No string
customerInn INN of the organization paying for the service No string
customerOrganization Name of the organization paying for the service No string

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 Description Required Type
account Recipient's card number (only Qiwi Mir Metal cards) Yes string
description Description of the rendered service Yes string
inn INN of the self-employed Yes string
incomeType Source of income Yes string
name Recipient's name No string
last name Recipient's surname No string
customerInn INN of the organization paying for the service No string
customerOrganization Name of the organization paying for the service No string

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 Description Required Type
account Mobile phone number Yes string

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 Description Required Type
account Client ID in WL Yes string
product_id Product ID in WL Yes string

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 Description Required Type
pan Recipient's card number ✓ string
lastname Recipient's last name ✓ string
name Recipient's first name ✓ string
patronymic Recipient's middle name × string
acceptanceCertificate Acceptance certificate ID ✓ string

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 Description Required Type
pan Recipient's card number (only Qiwi Mir Metal cards) ✓ string
lastname Recipient's last name ✓ string
name Recipient's first name ✓ string
patronymic Recipient's middle name × string
acceptanceCertificate Acceptance certificate ID ✓ string

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 Description Required Type
account Recipient's identifier (phone number in international format without + sign) ✓ string
bankId 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) ✓ string

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 Description Required Type
phone Recipient's identifier (phone number in international format without + sign) ✓ string
bankId 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) ✓ string
lastName Recipient's last name ✓ string
firstName Recipient's first name ✓ string
middleName Recipient's middle name (if available) × string

RefugeeCertificate

Refugee certificate

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

ResidencePermit

Residence permit

Parameter Required Type Description
serial Yes String series
number Yes String number
issuer Yes String issued by
issueDate Yes String Date of issue (in YYYY-MM-DD format)
validThrough Yes String 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 Required Type Description
paymentType Yes String Enum:
"NO_EXTRA_CHARGE" no extra commission charged in excess of payment
"WITH_EXTRA_CHARGE" with extra commission over payment
paymentToolType Yes String Enum:
"CASH"
"BANK_ACCOUNT"
"BANK_CARD"
"BANK_CARD_OWN" Bank card issued by this Bank
"ELECTRONIC_FUNDS" EMF
paymentTerminalType Yes String 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 No Date  
extraCharge No Money Commission taken in excess of the payment if "paymentType": "WITH_EXTRA_CHARGE"
chargeOffCurrency No 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 Required Type Description
serial Yes String series
number Yes String number
visaId Yes String  
issueDate Yes String in YYYY-MM-DD format
entryFrom Yes String in YYYY-MM-DD format
stayUntil Yes String 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 Required Type Description
agentId Yes String Unique identifier of agent
pointId Yes String Unique identifier of payment acceptance site
paymentId Yes String Unique payment ID
status Yes PaymentStatus  
amount Yes Money  

Common data models

Money

Money field description

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

Limit

Payment limits

{
  "currency": "643",
  "min": "100.00",
  "max": "5000.00"
}
Parameter Required Type Description
currency Yes String ISO ALFA3 Currency code
min No String Minimum amount allowed
max No 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 Required Type Description
type No String Type of error (if available)
errors No FormsErrors Array of Forms Error elements
message Yes String Common error description

Element FormsErrors

 {
    "message" : "Неверный номер счета",
    "parameter" : "account",
    "state" : "Invalid",
    "value" : "42301840000000000001"
 }
Parameter Required Type Description
message Yes String Error description
parameter Yes String Parameter with error
state No String State of parameter
value Yes String 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 Required Type Description
serviceName Y String ID of the service that generated an error (not analyzed)
errorCode Y String  
userMessage Y String Error description to display to the client
description Y String Error description
traceId Y String Internal identifier
dateTime Y Date Time of error occurrence
cause N 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

Samples