QIWI
Feedback
bss@qiwi.com
NAV Navbar
Samples

General Information

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

sequenceDiagram participant agent as Agent participant forms as Forms API participant payouts as Payout API Note over agent,payouts: Preparation for payment agent->>payouts: Request of available providers activate payouts payouts-->>agent: List of available providers deactivate payouts agent->>forms: Request of provider forms activate forms forms-->>agent: Forms information deactivate forms Note over agent,payouts: Payment registration agent->>payouts: Request for payment creation activate payouts alt Validation failed payouts-->>agent: Payment is not possible else Validation completed payouts-->>agent: Payment registered deactivate payouts end Note over agent,payouts: Payment agent->>payouts: Execution of payment activate payouts payouts-->>agent: Result of payment deactivate payouts opt Payment notification payouts->>agent: Payment result notification activate agent agent-->>payouts: Notification processing result deactivate agent end

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, 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 HTTP Request: GET {payout.api.url}/v1/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 HTTP Request: GET {payout.api.url}/v1/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 HTTP Request: GET {payout.api.url}/v1/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"
    }
  }
}

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

Description: Retrieves the balance available for making payments 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.

Payout API payment methods

Create payment

Description: Registers a payment and its preparation for further execution

HTTP Request: PUT {payout.api.url}/v1/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"
}
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"
  },
  "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": "Ivanov",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path"
}

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

HTTP Request: POST {payout.api.url}/v1/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"
  },
  "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": "Ivanov",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path"
}

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

HTTP Request: POST {payout.api.url}/v1/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"
  },
  "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": "Ivanov",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path"
}

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: Gets a list of recent payments. Without specifying the from and to filters, payments are searched for the last 50 days.

HTTP Request: GET {payout.api.url}/v1/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, default 20 integer
offset query The number of payments to skip, default 0 integer
from query Search interval start date in YYYY-MM-DD format string
to query Search interval end date in YYYY-MM-DD format 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"
    },
    "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": "Ivanov",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
    },
    "callbackUrl": "https://domain/path"
  }
]

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": "Ivanov",
    "something": "something the counter-party needs",
    "something-else": "something else the counter-party needs"
  },
  "callbackUrl": "https://domain/path"
}

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

PaymentCreationParams

Payment creation object.

{
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "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"
}
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

PaymentInfo

The object of payment existing in the system.

{
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "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"
}
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

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.
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
"BILLING_DECLINED" provider billing rejected the payment
errorMessage String Detailed description of errorCode
fraudApproveRequired boolean Default value false. true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж успешно исполнен. Фактическое неисполнение платежа кассиру и клиенту не раскрывается (платеж приостанавливается)
clientApproveRequired boolean Default value false. При значении true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж имеет потенциально подозрительную окраску. Клиент может отказаться от проведения платежа или подтвердить его исполнение

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
self-employed-sbp Payment to the Faster Payments System (SBP) with tax registration
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 the Faster Payments System
sbp-mfo Payments to the Faster Payments System (SBP) with name verification (for microfinance organizations)
sbp-recycling Payments to the Faster Payments System (SBP) for recycling payments with required description
legal-entity-bank-account Payments to legal entity bank account
fields map[String, String] Required. Payment options

Description of payment providers

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

An example of the "recipientDetails" object for paying to a bank card

{
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234564543654321"
    }
  }
}
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

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

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

{
  "recipientDetails": {
    "providerCode": "bank-card-token",
    "fields": {
      "account": "8198425371822184"
    }
  }
}
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

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

An example of the "recipientDetails" object 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"
    }
  }
}
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

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

An example of the "recipientDetails" object 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"
    }
  }
}
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

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

An example of the "recipientDetails" object 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"
    }
  }
}
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

Payment to bank card of the self-employed person for recyclable materials providerCode: "self-employed-bank-card-recycling"

An example of the "recipientDetails" object for payment to a self-employed person's bank card for scrapmetal

{
  "recipientDetails": {
    "providerCode": "self-employed-bank-card-recycling",
    "fields": {
      "inn": "111111111111",
      "account": "4111111111111111",
      "incomeType": "FROM_LEGAL_ENTITY",
      "description": "Payment",
      "firstName": "Recipient's name",
      "middleName": "Recipient's last name",
      "lastName": "Recipient's last name",
      "customerInn": "7777777777",
      "customerOrganization": "Name of the organization paying for the service"
    }
  }
}
Parameter Type Description
account String Required. Recipient's card number
description String Required. Payment acceptance certificate or other description
inn String Required. INN of the self-employed
incomeType String Required. Source of income (FROM_LEGAL_ENTITY, FROM_INDIVIDUAL)
firstName String Required. Recipient's name
middleName String Recipient's middle name
lastName String Required. Recipient's surname
customerInn String INN of the organization paying for the service
customerOrganization String 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"

An example of the "recipientDetails" object 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"
    }
  }
}
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

Payment to the Faster Payments System (SBP) with tax registration providerCode: "self-employed-sbp"

An example of the "recipientDetails" object for payment to the Faster Payments System (SBP) with tax registration

{
  "recipientDetails": {
    "providerCode": "self-employed-sbp",
    "fields": {
      "inn": "111111111111",
      "account": "79098087755",
      "bankId": "100000000001",
      "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"
    }
  }
}
Parameter Type Description
account String Required. Recipient's identifier (phone number in international format without + sign)
bankId String Required. Recipient's bank identifier in the Faster Payments System (SBP). See the list of banks for the Faster Payments System (SBP) payments in xlsx (download) or csv format (download)
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

Payment to QIWI Wallet providerCode: "qiwi-wallet"

An example of the "recipientDetails" object for payouts to a Qiwi wallet

{
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789",
      "comment": "comment"
    }
  }
}
Parameter Type Description
account String Required. Mobile phone number
comment String Comment

White Label Topup providerCode: "wl-topup"

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

{
  "recipientDetails": {
    "providerCode": "wl-topup",
    "fields": {
      "account": "21646",
      "product_id": "company-id"
    }
  }
}
Parameter Type Description
account String Required. Client ID in WL
product_id String Required. Product ID in WL

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

An example of the "recipientDetails" object 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" object 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 Faster Payments System providerCode: "sbp-b2c"

An example of "recipientDetails" object for payment to the Faster Payments System (SBP) 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 the Faster Payments System (SBP). See the list of banks for the Faster Payments System (SBP) payments in xlsx (download) or csv format (download)

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

An example of "recipientDetails" object for payment to the Faster Payments System (SBP) 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 the Faster Payments System (SBP). See the list of banks for the Faster 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)

Payment to the Faster Payments System (SBP) for recycling payments with required description providerCode: "sbp-recycling"

An example of "recipientDetails" object for payment to the Faster Payments System (SBP) client for recycling payments with required description

{
  "providerCode": "sbp-recycling",
  "fields": {
    "phone": "79098087755",
    "bankId": "100000000001",
    "lastName": "Иванов",
    "firstName": "Иван",
    "middleName": "Иванович",
    "description": "ПСА 123"
  }
}
Parameter Type Description
phone String Required. Recipient's identifier (phone number in international format without + sign)
bankId String Required. Recipient's bank identifier in the Faster Payments System (SBP). See the list of banks for the Faster 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)
description String Required. Payment acceptance certificate or other description

An example of "recipientDetails" object for payment to bank account of legal entity

{
  "providerCode": "legal-entity-bank-account",
  "fields": {
    "account": "50537928100000002463",
    "bik": "304754657",
    "inn": "1111111111",
    "kpp": "389244830",
    "name": "Qiwi PLC",
    "remarks": "Payment for services #454"
  }
}
Parameter Type Description
account String Required. Recipient's bank account
bik String Required. Recipient's bank identification code
inn String Required. Recipient's organization INN
name String Required. Recipient's organization name
remarks String Required. Payment purpose
kpp String Recipient's organization KPP (required for LLC)

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

WebhookPaymentInfo

{
  "agentId": "acme",
  "pointId": "00001",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
      "value": "COMPLETED",
      "changedDateTime": "2018-11-27T13:44:34.034+03:00"
  },
  "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