General Information

About API

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

Among the possible recipients are:

• Mobile communication of Russia and abroad
• E-wallets
• Providers of Internet and fixed mobile service
• Accounts and cards opened with banks of the Russian Federation
• Travel and ticketing agencies Housing utilities and public services
• Others

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

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:

• Customer (Client)

Primary Actor:

• Cashier

Actors:

• API (Payout API & Forms API)
• System (Counter-party system that realized the interface with API)

Target:

• Get permission to make a client's payment

Trigger:

• The client contacts the cashier to pay for the service and provides the payment details and the amount.

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:

• 1а. The cashier does not find the recipient of the service
• 1a1. The cashier refuses a Customer in payment of services
• 3a. The cashier did not enter all the information for payment or the entered parameters contain invalid values
• 3a1. The system informs about an error
• 3а2. The cashier makes corrections or completes the process
• 4a. Payment parameters are not verified
• 4a1. The system informs about an error
• 4а2. The Customer provides new data, and the Cashier starts the payment process first or completes the process
• 4c. Unable to contact API or system authorization error in API
• 4c1. The system informs about an error
• 4c2. The Cashier informs the Customer about the inability to make payment
• 4d. The amount to be paid does not correspond to the order (travel services for example)
• 4d1. The system reports the required amount to be paid
• 4d2. The Cashier adjusts the amount to be paid with the Customer's permission and the process continues from step 3
• 4e. Any failure result, except for incorrect amount.
• 4e1. The system informs about the error and the process stops

Step 2 Scenario. Making payment

Stakeholder:

• Customer (Client)

Primary Actor:

• Cashier

Actors:

• API (Payout API & Forms API)
• System (Counter-party system that realized the interface with API)

Target:

• Make a payment

Trigger:

• The Customer transfers funds to the Cashier for payment.

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:

• 1а. Sufficient funds have not been provided.
• 1а1. The Cashier refuses a Client in payment of services
• 3а. The system receives a refusal from the API to make a payment
• 3а1. The system informs about an error
• 3а2. The Cashier returns the funds to the Customer
• 3b. The system receives a message from the API that the payment is queued for execution, the payment is suspended on the API side due to lack of funds on the Participant's account, the system authorization error in the API or failed to contact the API
• 3b1. The system puts the payment in the queue and with an interval of at least 120s repeats the process from step 3
  Method Payment request execution is used
• b2. The system informs the Cashier about successful payment

Main scenario options:

• 3’. The system accepts queued payment as successful
• 4’. The Cashier prints the itinerary receipt (when paying for travel services)

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):

• PUT - methods that create new objects and assign an identifier to it on the client side
• POST - methods that perform an action over an existing object
• PATCH - methods that modify an existing object
• GET - methods to request information about an existing object (objects)

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

• As URL request elements.

  The position of such data is designated as 'path' and uniquely determines the object with which the work takes place (payment ID, forms, etc.).

• As request parameters.

  The position of such data is denoted as ‘query’ and determines the specificity of the query type.

• As JSON elements of the object passed in the request body.

  The position of such data is denoted as ‘body’ and defines the details of the created object. Only applicable to PUT and PATCH methods.

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:

Production environment

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

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

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
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}

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

Request body contains set of objects with this structure:

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 checking result (if checking is not completed, payment with this data can not be formed)
• Forming new interface elements, that are depending on field being checked
• Predefined constraints of payment value, that are depending on field being checked

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

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:

• Object class array Еlements. At this point appears extra elements to elements which is previously obtained in the form query.
• Element terms class Тerms (not necessary) At this point answer determines the restrictions of payment defined earlier by terms.
• Also it can contain them both.

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

SumConstraint

Class object describing restrictions of payment value:

{
   "type": "FixedSumConstraint",
   "sum" : {
      "currency": "643",
      "amount":"123.45"
    }
}

Elements array

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

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

Validator

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

"validator":{
  "type":"predicate",
  "predicate":{},
  "message":"Проверьте номер карты"
}

Condition

"condition": {
    "type": "predicate",
    "field": "account_type",
    "predicate": {
        "type": "regex",
        "pattern": "2"
    }
}

Predicate

Object contains logical checking conditions.

{
  "pattern" : "^2$|^5$",
  "type" : "regex"
}

View

{
  "title": "Номер счета",
  "prompt": "Номер счета",
  "widget": {}
}

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

Expansion

Choices array

Each array object of this class contains parameters:

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

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:

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

Addition

• Each element of the tree has an attribute form and payable with boolean values
• form with true means that there is a form to this element that can be required from
• payable with true means that the element describes the actual payment service
• The form ID providerCode to request it in Forms API (it matches the ID of the merchant) see the Forms API

form & payable combinations

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

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:

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

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

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

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

• Data for the formation of the object are taken from the software system of the partner.
• The data of the enclosed object recipientDetails are prepared using Forms API.

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

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

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

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

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

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:

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).

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

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

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": "Параметр платежа указан неверно."
    }

RecipientDetails

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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": "Иванович"
  }
}

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

Payment to legal entity bank account providerCode: "legal-entity-bank-account"

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

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

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",
  }
}

Common data models

Money

Money field description

{
  "value": "200.00",
  "currency": "RUB"
}

Limit

Payment limits.

{
  "currency": "643",
  "min": "100.00",
  "max": "5000.00"
}

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:

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:

• CommonError for Payout API methods.
• FormsError for Forms API methods.

FormsError

{

   "errors" : [
     {
       "message" : "Неверный номер счета",
       "parameter" : "account",
       "state" : "Invalid",
       "value" : "42301840000000000001"
     }
   ],
   "message" : "Ошибка валидации"
}

Element FormsErrors

 {
    "message" : "Неверный номер счета",
    "parameter" : "account",
    "state" : "Invalid",
    "value" : "42301840000000000001"
 }

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"]
    }
  }

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

• auth.failed

  Authorization error: token or certificate not provided or not found.

• auth.forbidden

  Access is forbidden: no access rights to the resource.

Validation errors

• payout.bad.request

  Incorrect request: required parameters not present or not valid.

• payout.resource.exists

  Resource already exists: resource with requested ID exists.

• payout.point.not-found

  Point not found: point with requested ID not found.

• payout.payment.not-found

  Payment not found: payment with requested ID not found.

• payout.provider.not-found

  Provider not found: provider with requested ID not found.

• validation.error

  Request validation error (incorrect JSON body).

Payment processing errors on the side of provider

• payout.provider.forbidden

  Provider forbidden: payments to the specified provider forbidden.

• payout.provider.unavailable

  Provider unavailable: payments to the specified provider temporarily impossible.

• payout.billing.declined

  Payment declined: a reject of payment received from the specified provider.

• payout.billing.timeout

  Request timeout: no response from the specified provider within the standard amount of time.

Financial and law risks verification errors

• payout.fraud.violated

  Payment forbidden: violated rules of financial or fraud monitoring.

• payout.legislation.prohibited

  Payment forbidden: payment forbidden according to Russian Federation law requirements.

General errors

• payout.insufficient_funds

  Not enough funds: insufficient funds on the partner's balance.

• payout.internal.error

  Internal error.

• internal.error

  Internal error.