Feedback
bss@qiwi.com
NAV Navbar
Samples

Introduction

About…

Universal API of payments towards any payment recipients (providers)

Among the possible recipients are:

Terms and abbreviations used in the document

Token: Character line for counterparty 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

API methods usage diagram

Basic sequence diagram

Forms API methods are described in Forms API section
Payout API methods are described in Payout API section

Option to implement API methods at the checkout

Below, the option of realization of the payment at the checkout of the counterparty with API use is described

Step 1 scenario. Payment possibility check

Stakeholder:

Primary Actor:

Actors:

Trigger:

Main success scenario:

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

Extensions:

Step 2 Scenario. Making payment.

Stakeholder:

Primary Actor:

Actors:

Target:

Trigger:

Main success scenario:

  1. The cashier receives funds from the Client
  2. The Cashier initiates the payment process allowed in the payment step 1 scenario in the System.
  3. The systems makes a payment permitted in step 1 scenario Method 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 https://{payout.api.url}/some/method HTTP/1.1
Accept: application/json
Authorization: Bearer mF_9.B5f-4.1JqM

When calling the Payout API methods, counterparty requests are authorized by the token provided in the request and known only to the counterparty.
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 metods

GET https://{forms.api.url}/some/method HTTP/1.1
Accept: application/json
X-Application-Id: 83cca1c0-49f2-417a-bd88-2803058dfd77
X-Application-Secret: 2924502d-f1e4-4f06-96ed-cdce126cf499

The requests of the counterparty 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

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

Forms API methods

Provider form

Description: Used to get provider form
HTTP Request: GET {forms.api.url}/providers/{id}/form

Request

GET {forms.api.url}/providers/mosoblgaz-podolsk/form HTTP/1.1
Accept: application/json
X-Application-Id: <X-Application-Id-String>
X-Application-Secret: <X-Application-Secret-String>

Parameters

Parameter Position Description Requried Type
id path Provider ID Yes string

Response

Response example

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

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

Referece request about field

Description: Used to get online data processing on provider field HTTP Request: POST {forms.api.url}/refs/{id}/containers

Parameters

Request

POST {forms.api.url}/refs/somebank/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>

{
    "account": "42301810000000000001"
}
Parameter Position Description Requried Type
id path Request Id Yes string

Request body contaits set of objects with this sructure:

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

Using

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

Request result can be:

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

Structure "ref" is part of array Elements

Parameter Obligation Type Dscription
type Yes const "ref" Element type which is requiring online proccesing
title Yes string Field heading
message Yes string Checking message
id Yes string ID to request
params Yes string Array to request. Contains object parameteres: pair "field" - name (parameter name from parent object field) and pair "triggerReload" - true/false (if true, when parameter value "name" is chaned 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:

Or it returns error in format FormsError

Data models Forms API

Content

Basic container contains class object Elements with page elements.

Terms

Class object describing payment condition

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

SumConstraint

Class object describing restrictions of payment value

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

Elements array

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

Parameter Type Description
type String Type of interface element.</br> Possible values
"field" - Element to unconditional display
"dependency" - Element with display conditions
"ref" - Element, generating online-checking
name String Variable name, that is appropriate to element form. Only to type "field"
validator Validator Checking condition of "name" value. Only to type "field".
view  View Display parameteres of element form. Only to type "field".
/If it is missing, element is hidden
value String Value of diplaying 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 oject, describing field semantic (to extra validation/help inputting). Только для type "field".
condition Condition Display conditions of element form. Only to type "dependency".
content Content Element despcription of extra interface form which is needed to be proccessed if condition "condition" is done . Only to type "dependency".
id String Online-request ID /refs. Only to type "ref".
message String Message about checkng. Only to type "ref".
title String Field heading. Only to type "ref".
params Массив Array to sending in request /refs. Contains objects with "field" parameteres - <name> и "triggerReload" - true/false (if true, while changing parameter <name> value by user, on iterface form object must be automatically update with new value)
Only to type "ref".

Example with type "ref" is shown in the method description Онлайн-запрос данных

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>. Parameteres:

"validator":{
  "type":"predicate",
  "predicate":{},
  "message":"Проверьте номер карты"
}
Parameter Type Description
type String Chekcing type. Possible values:
predicate - Logical condition or set of logical conditions
message String Message, if the value hasn't comleted the checking
predicate Predicate Block of checking conditions (Only to 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 cheking 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": {}
}
Parmeter 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

Exampe 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 Elemet 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 choises
mask String Mask for input
for "text" only
keyboard String Recomended keyboard type (if acceptable) - "numeric", "text" (by default).
for "text" only
stripStaticSymbols boolean Need to remove all statyc sybols befor 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) dislayed
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}/agents/{agentId}/points/{pointId}/providers/directory/{providerCode}

Request of the entire catalog

GET {payout.api.url}/agents/acme/points/00001/providers/?expand=true HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>

Query of a child host of “money-transfer” providers/categories/hosts

GET {payout.api.url}/agents/acme/points/00001/providers/directory/money-transfer?expand=false  HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>

Parameters

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

Response

The answer 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": []
                    }
                ]
            }
        ]
    }

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

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

Response 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": []
       }
   ]
}

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: Request of all providers in the form of a flat list HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/providers

Request

GET {payout.api.url}/agents/acme/points/00001/providers HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>

Parameters

Parameter Position Description Requried Type
pointId path Unique identifier of payment acceptance site Yes string

Response

Response

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

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

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

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

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

Payout API payment methods

Create payment

Description: Registration of payment and its preparation for further execution
HTTP Request: PUT {payout.api.url}/agents/{agentId}points/{pointId}/payments/{paymentId}

Parameters

Request

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

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

PaymentCreationParams object is passed in the request field filled by the counterparty software. Data for the formation of the object are taken from the software system of the counterparty. The data of the enclosed object recipientDetails from SINAP forms.

Response

Example of a successful response body

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

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

The response format of the PaymentInfo object

Execute payment

Description: Execute unpaid payment by its id and returns information about it HTTP Request: POST {payout.api.url}/agents/{agentId}points/{pointId}/payments/{paymentId}/execute

Parameters

Request

POST {payout.api.url}/agents/acme/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6/execute HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Parameter Position Description Requried Type
paymentId path Unique payment ID Yes string
pointId path Unique identifier of payment acceptance site Yes string

Response

Response

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

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

The response format of the PaymentInfo object

Payment request cancellation (Reject payment)

Description: Rejects unpaid payment by its id and returns information about it
HTTP Request: POST {payout.api.url}/agents/{agentId}points/{pointId}/payments/{paymentId}/reject

Parameters

Request

POST {payout.api.url}/agents/acme/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6/reject HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Parameter Position Description Requried Type
paymentId path Unique payment ID Yes string
pointId path Unique identifier of payment acceptance site Yes string

Response

Response

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

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

The response format of the PaymentInfo object

Payment request enrichment (Update payment)

Description: Addition of payment request with missing data for its execution
HTTP Request: PATCH {payout.api.url}/agents/{agentId}points/{pointId}/payments/{paymentId}

Параметры

Request

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

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

Response

The response format of the PaymentInfo object

Response

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

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

Get all payments

Description: Finds payments by its date HTTP Request: GET {payout.api.url}/agents/{agentId}points/{pointId}/payments

Параметры

Request

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

Response

The response format of the PaymentInfo objects array

Response

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

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

Find payment

Description: Finds payment by its ID and returns information about it HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/payments/{paymentId}

Parameters

Request

GET {payout.api.url}/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6 HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Parameter Position Description Requried Type
paymentId path Unique payment ID Yes string
pointId path Unique identifier of payment acceptance site Yes string

Response

The response format of the PaymentInfo object

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

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

Conformation webhook sent to client server

Description: Sending a notification about the payment results to the counterparty's server (to callbackUrl) HTTP Request: POST {callbackUrl}/webhook/points/{pointId}/payments/{paymentId}/confirm

Parameters

Request

POST https://domain/path/webhook/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6/confirm HTTP/1.1
Content-Type: application/json
QIWI-Signature: 2cc6b2e0cd00f701d9d5510a6e5d4a6a67f9e5a61d7f8e4a203d3ae81b9­ae2b 

{
  "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 Requried Type
callbackUrl path Call address from PaymentCreationParams Yes  
paymentId path Unique payment ID Yes string
pointId path Unique identifier of payment acceptance site Yes string
QIWI-Signature header Request signature, to verify you need to construct string by template: "{paymentId}|{status.value}|{amount.value}|{amount.currency}" there {path} means take value at path in JSON payload, | means character '|'. And compute HMAC with SHA256 hash function with constructed string as data and your secret key as key. Yes string
body body   Yes WebhookPaymentInfo

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

Response

Response body is not analyzed

HTTP request-specific response codes

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

Payout API data models

Customer

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

Parameter Required Type Description
account No String Номер счета/договора и т.п.
email No String Емейл плательщика
phone No String Телефон плательщика

Document

General description of the identity document

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

DocumentSimplified

General description of the identity document (simplified form)

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

ForeignPassport

Foreign citizen's passport

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

Identification

Identification data of the payer

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

IdentificationFull

Data on full identification of the payer

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

IdentificationSimple

Data on simplified identification of the payer

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

IdentificationType

Type of identification required or provided

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

MigrationCard

Migration card

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

Passport

Full details of the passport of the Russian Federation citizen

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

PassportSimplified

Simplified data of the passport of the Russian Federation citizen

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

PaymentCreationParams

Payment creation object

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

PaymentInfo

The object of payment existing in the system

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

PaymentStatus

Information about the current status of the payment

"status": {
    "value": "IN_PROGRESS",
    "changedDateTime": "2018-11-27T14:06:17.108Z",
  }
Parameter Required Type Description
value Yes String Статус
Enum
"CREATED" created, but not ready for payment
"READY" created and ready for payment
"FAILED"
"IN_PROGRESS" in the process of execution (status not fixed)
"COMPLETED" executed
changedDateTime Yes Date  
error No CommonError  
identificationType No IdentificationType Identification level required for payment

Person

Full data on the payer (without documents)

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

PersonFullName

Full name of the payer

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

PersonSimplified

Simplified data on the payer (without documents)

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

RecipientDetails

  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "acсount": "9123456789"
    }
Parameter Required Type Description
providerCode Yes String Recipient code
Fields Yes map[String, String] Payment options

RefugeeCertificate

Refugee certificate

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

ResidencePermit

Residence permit

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

Source

Payment source information

{
  "paymentType": "WITH_EXTRA_CHARGE",
  "paymentToolType": "CASH",
  "paymentTerminalType": "ATM_CASH_IN",
  "paymentDate": "2018-12-06T14:08:46.598Z",
  "extraCharge": {
    "value": "200.00",
    "currency": "RUB"
  }
}
Parameter Required Type Description
paymentType Yes String Enum:
"NO_EXTRA_CHARGE" no extra commission charged in excess of payment
"WITH_EXTRA_CHARGE" with extra commission over payment
paymentToolType Yes String Enum:
"CASH"
"BANK_ACCOUNT"
"BANK_CARD"
"BANK_CARD_OWN" Bank card issued by this Bank
"ELECTRONIC_FUNDS" EMF
paymentTerminalType Yes String Enum:
"ATM_CASH_IN" ATM with CASH_IN
"ATM"
"AUTO_PAYMENTS"
"CASH_DESK"
"POS_TERMINAL"
"MOBILE_BANKING"
"INTERNET_BANKING"
"ELECTRONIC_WALLET"
"SELF_SERVICE_TERMINAL"
"IVR_CHANNELS"
paymentDate No Date  
extraCharge No Money Commission taken in excess of the payment if "paymentType": "WITH_EXTRA_CHARGE"

Visa

Visa to stay in Russia

{
  "serial": "A12",
  "number": "12345",
  "visaId": "1234",
  "issueDate": "2018-12-06",
  "entryFrom": "2018-12-06",
  "stayUntil": "2018-12-06"
}
Parameter Required Type Description
serial Yes String series
number Yes String number
visaId Yes String  
issueDate Yes String in YYYY-MM-DD format
entryFrom Yes String in YYYY-MM-DD format
stayUntil Yes String in YYYY-MM-DD format

WebhookPaymentInfo

Parameter Required Type Description
paymentId Yes String Unique payment ID
status Yes PaymentStatus  
amount Yes Money  

Common data models

Money

Money field description

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

Limit

Payment limits

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

Errors

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:42Z",
    "cause": {
        "property1": [
        "string"
        ],
        "property2": [
        "string"
        ]
    }
}

Sample Forms error response

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

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

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

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

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

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

FormsError

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

Element FormsErrors

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

CommonError

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

Test environment

API Authorization Encryption URL
{payout.api.url} Token RSA https://api-test.qiwi.com/partner/payout/v1/
{forms.api.url} Certificate RSA https://private-api-test.qiwi.com/partner/payout/v1/
{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/v1/
{forms.api.url} Certificate GOST https://private-api-gost-test.qiwi.com/partner/payout/v1/
{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/
Samples