Introduction
About…
Universal API of 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 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
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:
- Customer (Client)
Primary Actor:
- Cashier
Actors:
- API (Payout API & Forms API)
-
System (Counterparty 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:
- The cashier finds the payee in the system
Request a tree of the providers directory or Request a list of providers methods are used - The system requests payment details
Provider Form methods are used - 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
- The system sends to API all payment details and API confirms the possibility of payment
Payment creation method is used - 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
- 3b. When forming the verification of the possibility of payment, it is necessary to enter the identification data (the amount above 15,000 or p2p payment)
- 3b1. The cashier identifies the payer by means of ID or completes the process
- 3b2. The cashier shall enter identification data in addition to the payment details.
- 3b3. The system adds identification data to payment request Payment request enrichment method is used.
- 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 (Counterparty system that realized the interface with API)
Target:
- Make a payment
Trigger:
- The Customer transfers funds to the Cashier for payment.
Main success scenario:
- The cashier receives funds from the Client
- The Cashier initiates the payment process allowed in the payment step 1 scenario in the System.
- The systems makes a payment permitted in step 1 scenario Method Payment request execution is used
- The system prints the cash receipt
- 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 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 methods
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):
- 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
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 | Required | Type |
---|---|---|---|---|
id | path | Provider ID | Yes | string |
Response
Response example
HTTP/1.1 200 OK
Content-Type: application/json
{
"id": "mosoblgaz-podolsk",
"content": {
"terms": {
"type": "DefaultPayoutTerms",
"id": "mosoblgaz-podolsk"
},
"elements": [
{
"type": "field",
"name": "sinap-form-version",
"value": "payout::mosoblgaz-podolsk, 1"
},
{
"type": "field",
"name": "account",
"validator": {
"type": "predicate",
"predicate": {
"type": "regex",
"pattern": "^\\d{12}$"
},
"message": "Некорректное значение"
},
"view": {
"title": "Номер лицевого счёта",
"prompt": "Номер лицевого счёта",
"widget": {
"type": "text",
"stripStaticSymbols": false
},
"hint": "12 цифр"
},
"sensitiveData": false,
"hideFromConfirmationScreen": false
},
{
"type": "field",
"name": "payment_type",
"validator": {
"type": "predicate",
"predicate": {
"type": "regex",
"pattern": "^1$|^2$|^3$"
},
"message": ""
},
"view": {
"title": "Тип платежа",
"prompt": "Тип платежа",
"widget": {
"type": "list",
"choices": [
{
"value": "1",
"title": "Оплата за газ"
},
{
"value": "2",
"title": "Оплата за тех обслуживание"
},
{
"value": "3",
"title": "Прочее"
}
]
}
},
"value": "1",
"hideFromConfirmationScreen": false
},
{
"type": "dependency",
"condition": {
"type": "predicate",
"field": "payment_type",
"predicate": {
"type": "regex",
"pattern": "^1$"
}
},
"content": {
"elements": [
{
"type": "field",
"name": "_has_counter",
"view": {
"title": "Указать счётчики",
"prompt": "Указать счётчики",
"widget": {
"type": "switch",
"offValue": "0",
"onValue": "1"
}
},
"value": "1",
"hideFromConfirmationScreen": false
},
{
"type": "dependency",
"condition": {
"type": "predicate",
"field": "_has_counter",
"predicate": {
"type": "regex",
"pattern": "^1$"
}
},
"content": {
"elements": [
{
"type": "field",
"name": "counter",
"validator": {
"type": "predicate",
"predicate": {
"type": "regex",
"pattern": "\\d+"
},
"message": "Некорректное значение"
},
"view": {
"title": "Текущие показания счетчика",
"prompt": "Текущие показания счетчика",
"widget": {
"type": "text",
"stripStaticSymbols": false
}
},
"sensitiveData": false,
"hideFromConfirmationScreen": false
},
{
"type": "field",
"name": "counter_date",
"validator": {
"type": "predicate",
"predicate": {
"type": "regex",
"pattern": "\\d+"
},
"message": "Некорректное значение"
},
"view": {
"title": "Дата снятия показаний",
"prompt": "Дата снятия показаний",
"widget": {
"type": "date",
"format": "ddMMyyyy",
"allowsFutureDate": false
}
},
"sensitiveData": false,
"hideFromConfirmationScreen": false
}
]
}
}
]
}
}
]
}
}
Field | Type | Description |
---|---|---|
id | string | Provider Id |
content/elements | Array Elements | Form |
content/terms | Terms | Class Object 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 | Required | Type |
---|---|---|---|---|
id | path | Request Id | Yes | string |
Request body contains set of objects with this structure:
Parameter | Type | Description |
---|---|---|
Parameter name is given from array "params" object "type":"ref" in array elements | string | Parameter value determined in interface |
Using
Online check is requested if form field determined like field with extra online processing "type":"ref"
Request result can be:
- 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":"somebank", "type":"ref", "title":"Проверить номер счета", "message":"Необходимо проверить номер счета", "params":[{ "field":"account", "triggerReload": true } ] } ~~~
Structure "ref" is part of array Elements
Parameter | Obligation | Type | Description |
---|---|---|---|
type | Yes | const "ref" | Element type which is requiring online processing |
title | Yes | string | Field heading |
message | Yes | string | Checking message |
id | Yes | string | ID to request |
params | Yes | string | Array to request. Contains object parameters: pair "field" - name (parameter name from parent object field) and pair "triggerReload" - true/false (if true, when parameter value "name" is changed by user, field must be automatically update with new value) |
Response
HTTP/1.1 200 OK
Content-Type: application/json
{
"elements": [
{
"type": "field",
"view": {
"title": "Minimum recommended payment",
"prompt": "Minimum recommended payment",
"widget": {
"type": "info"
}, "value": "3510.00"
}
}
]
}
If successful, the response contains:
- 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.
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 parameters of element form. Only to type "field". /If it is missing, element is hidden |
value | String | Value of displayed field (if this element is static). Only to type "field". |
sensitiveData | boolean | If true - data in field is confidential (masking is needed on screen, receipt, logs, etc.) Only to type "field". |
semantics | Semantic | (unnecessary) Class object, describing field semantic (to extra validation/help inputting). Только для type "field". |
condition | Condition | Display conditions of element form. Only to type "dependency". |
content | Content | Element description of extra interface form which is needed to be processed if condition "condition" is done . Only to type "dependency". |
id | String | Online-request ID /refs. Only to type "ref". |
message | String | Message about checking. Only to type "ref". |
title | String | Field heading. Only to type "ref". |
params | Массив | Array to sending in request /refs. Contains objects with "field" parameters - <name> и "triggerReload" - true/false (if true, while changing parameter <name> value by user, on interface form object must be automatically update with new value) Only to type "ref". |
Example with type "ref" is shown in the method description Онлайн-запрос данных
Semantic
Optional field semantic (to extra validation/help inputting)
"semantics": {
"type": "LastName"
}
Parameter | Type | Description |
---|---|---|
type | String | Enum: "FirstName" "LastName" "MiddleName" "OwnerFirstName" "OwnerLastName" "OwnerMiddleName" "BirthDate" "Email" "Phone" "WalletPhone" |
Validator
Condition block of checking variable value <name>. Parameters:
"validator":{
"type":"predicate",
"predicate":{},
"message":"Проверьте номер карты"
}
Parameter | Type | Description |
---|---|---|
type | String | Checking type. Possible values: predicate - Logical condition or set of logical conditions |
message | String | Message, if the value hasn't completed the checking |
predicate | Predicate | Block of checking conditions (Only 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 checking is successful, element form is displaying. Only to type "predicate" |
Predicate
Object contains logical checking conditions.
{
"pattern" : "^2$|^5$",
"type" : "regex"
}
Parameter | Type | Description |
---|---|---|
type | string | Checking type. Possible values: regex - Checking with regular expression and - set of logical conditions with "AND" operator |
pattern | String или array | string Applied with type "regex". Contains regular expression to check value array Applied with type "and". Contains a set of several "predicate" objects. Checking all conditions in array, that are combined by logical operator, specified in type |
View
{
"title": "Номер счета",
"prompt": "Номер счета",
"widget": {}
}
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 choices |
mask | String | Mask for input for "text" only |
keyboard | String | Recommended keyboard type (if acceptable) - "numeric", "text" (by default). for "text" only |
stripStaticSymbols | boolean | Need to remove all static symbols before check value if "true" for "text" only. |
expansion | Expansion | Defines hidden list items for "radio" only |
choices | Array of Choices | List of choices for "radio" or "list" only |
Expansion
Parameter | Type | Description |
---|---|---|
threshold | number | number of items (buttons) displayed |
title | String | Title of hidden items (buttons). If total count of items more then "threshold" |
Choices array
Each array object of this class contains parameters
Parameter | Type | Description |
---|---|---|
title | String | Position (button) title |
value | Number | Value of selected item to processing |
Payout API service methods
Request a tree of providers catalogue
Description: Request of providers catalogue HTTP Request: GET {payout.api.url}/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 | Required | Type |
---|---|---|---|
providerCode | Unique identifier of the provider | Yes | string |
name | Provider name (in Russian) | Yes | string |
payable | Means that the element is not a payment one and it is not possible to create a payment for it (for example, it is a host) | Yes | boolean |
form | Means that there is a form to this element that can be required from Forms API | Yes | boolean |
parents | The providerCode array of hosts this element belongs to |
Yes | [string] |
children | Recursive array of elements belonging to this element | No | [like this object] |
Response 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
- Each element of the tree has an attribute
form
andpayable
with boolean values form
with true means that there is a form to this element that can be required frompayable
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 {id}) see the Forms API
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 | Required | 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 | Required | Type |
---|---|---|---|
providerCode | Unique identifier of the provider | Yes | string |
name | Provider name (in Russian) | Yes | string |
form | Means that there is a form to this element that can be required from Forms API | Yes | boolean |
The difference from the previous method is that only a list of available providers you can pay to is displayed. Therefore, the parameters of the elements are reduced to the required minimum.
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 | Required | 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 | Required | 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 | Required | 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 | Required | 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 | Required | 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 | Required | 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"
}
Confirmation 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: 2cc6b2e0cd00f701d9d5510a6e5d4a6a67f9e5a61d7f8e4a203d3ae81b9ae2b
{
"agentId": "acme",
"pointId": "00001",
"paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
"status": {
"value": "FAILD",
"changedDateTime": "2018-12-14T10:43:18.574Z",
"errorCode": "INTERNAL_ERROR",
},
"amount": {
"value": "200.00",
"currency": "RUB"
}
}
Parameter | Position | Description | Required | Type |
---|---|---|---|---|
callbackUrl | path | Call address from PaymentCreationParams | Yes | |
paymentId | path | Unique payment ID | Yes | string |
pointId | path | Unique identifier of payment acceptance site | Yes | string |
QIWI-Signature | header | Request signature, to verify you need to construct string by template: {paymentId}\|{status.value}\|{amount.value}\|{amount.currency} where {path} takes value of the path parameter in JSON payload, | means character '|'. Compute HMAC with SHA256 hash function with constructed string as data and your secret key as key. |
Yes | string |
body | body | Yes | WebhookPaymentInfo |
The method is initialized only if the callbackUrl
element of PaymentCreationParams object was provided at the time of payment creation
Response
Response body is not analyzed
HTTP request-specific response codes
Code | Description |
---|---|
XXX | Any code other than 200 is considered an error. The system will continue to repeat the notification |
Payout API data models
Customer
Optional object unambiguously describing the payer (does not contain data identifying the payer according to the legislation of the Russian Federation)
Parameter | Required | Type | Description |
---|---|---|---|
account | No | String | Номер счета/договора и т.п. |
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 documents |
IdentificationSimple
Data on simplified identification of the payer
Parameter | Required | Type | Description |
---|---|---|---|
type | Yes | IdentificationType | "SIMPLIFIED" only |
person | Yes | PersonSimplified | Simplified data on the payer |
document | Yes | DocumentSimplified | Simplified data on the identity document |
IdentificationType
Type of identification required or provided
Parameter | Required | Type | Description |
---|---|---|---|
значение | Yes | String | Identification provided Enum "NONE" "FULL" "SIMPLIFIED" |
MigrationCard
Migration card
Parameter | Required | Type | Description |
---|---|---|---|
serial | Yes | String | Series |
number | Yes | String | Number |
arrivalDate | Yes | String | Arrival date (in YYYY-MM-DD format) |
departureDate | Yes | String | Date of expected departure (in YYYY-MM-DD format) |
Passport
Full details of the passport of the Russian Federation citizen
Parameter | Required | Type | Description |
---|---|---|---|
serial | Yes | String | Series |
number | Yes | String | Number |
issuer | Yes | String | Issued by |
issueDate | Yes | String | Date of issue (in YYYY-MM-DD format) |
divisionCode | Yes | String | Sub-division code (in NNN-NNN format) |
PassportSimplified
Simplified data of the passport of the Russian Federation citizen
Parameter | Required | Type | Description |
---|---|---|---|
serial | Yes | String | Series |
number | Yes | String | Number |
PaymentCreationParams
Payment creation object
{
"recipientDetails": {
"providerCode": "MTS",
"fields": {
"phone": "9123456789"
}
},
"amount": {
"value": "20000.00",
"currency": "RUB"
},
"customer": {
"account": "#12345",
"email": "usermail@mail.mail",
"phone": "9123456789"
},
"source": {
"paymentType": "WITH_EXTRA_CHARGE",
"paymentToolType": "CASH",
"paymentTerminalType": "ATM_CASH_IN",
"paymentDate": "2018-11-27T14:02:35.589+03:00",
"extraCharge": {
"value": "200.00",
"currency": "RUB"
}
},
"callbackUrl": "https://domain/path",
"identification": {}
}
Parameter | Required | Type | Description |
---|---|---|---|
recipientDetails | Yes | RecipientDetails | Object describing the payment 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.589+03:00",
"extraCharge": {
"value": "200.00",
"currency": "RUB"
}
},
"callbackUrl": "https://domain/path",
"identificationType": "NONE"
}
Parameter | Required | Type | Description |
---|---|---|---|
paymentId | Yes | String | Unique payment ID |
creationDateTime | Yes | Date | Payment creation date |
expirationDatetime | Yes | Date | Payment expiration date |
status | Yes | PaymentStatus | Payment status |
recipientDetails | Yes | RecipientDetails | Object describing the payment beneficiary |
amount | Yes | Money | Object describing the payment amount |
commission | No | Money | Object describing the payment commissions |
customer | No | Customer | Object describing the payer |
source | No | Source | Object describing the payment instrument |
customFields | No | map[String, String] | List of additional data that accompanied the payment |
callbackUrl | No | String | Method call address Notification |
identificationType | Yes | IdentificationType | Identification provided |
PaymentStatus
Information about the current status of the payment
"status": {
"value": "IN_PROGRESS",
"changedDateTime": "2018-11-27T14:06:17.108+03:00",
}
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.598+03:00",
"extraCharge": {
"value": "200.00",
"currency": "RUB"
},
"chargeOffCurrency": "USD"
}
Parameter | Required | Type | Description |
---|---|---|---|
paymentType | Yes | String | Enum: "NO_EXTRA_CHARGE" no extra commission charged in excess of payment "WITH_EXTRA_CHARGE" with extra commission over payment |
paymentToolType | Yes | String | Enum: "CASH" "BANK_ACCOUNT" "BANK_CARD" "BANK_CARD_OWN" Bank card issued by this Bank "ELECTRONIC_FUNDS" EMF |
paymentTerminalType | Yes | String | Enum: "ATM_CASH_IN" ATM with CASH_IN "ATM" "AUTO_PAYMENTS" "CASH_DESK" "POS_TERMINAL" "MOBILE_BANKING" "INTERNET_BANKING" "ELECTRONIC_WALLET" "SELF_SERVICE_TERMINAL" "IVR_CHANNELS" |
paymentDate | No | Date | |
extraCharge | No | Money | Commission taken in excess of the payment if "paymentType": "WITH_EXTRA_CHARGE" |
chargeOffCurrency | No | String | Currency of the debit account, indicates the currency of the account from which agent's funds must be debited ISO 4217 ALFA3 Currency code |
Visa
Visa to stay in Russia
{
"serial": "A12",
"number": "12345",
"visaId": "1234",
"issueDate": "2018-12-06",
"entryFrom": "2018-12-06",
"stayUntil": "2018-12-06"
}
Parameter | Required | Type | Description |
---|---|---|---|
serial | Yes | String | series |
number | Yes | String | number |
visaId | Yes | String | |
issueDate | Yes | String | in YYYY-MM-DD format |
entryFrom | Yes | String | in YYYY-MM-DD format |
stayUntil | Yes | String | in YYYY-MM-DD format |
WebhookPaymentInfo
Parameter | Required | Type | Description |
---|---|---|---|
agentId | Yes | String | Unique identifier of agent |
pointId | Yes | String | Unique identifier of payment acceptance site |
paymentId | Yes | String | Unique payment ID |
status | Yes | PaymentStatus | |
amount | Yes | Money |
Common data models
Money
Money field description
{
"value": "200.00",
"currency": "RUB"
}
Parameter | Required | Type | Description |
---|---|---|---|
value | Yes | String | Value in units of exchange with 2 digits after point Pattern ^([0-9]+)?[.][0-9]{2}$ |
currency | Yes | String | ISO 4217 ALFA3 Currency code |
Limit
Payment limits
{
"currency": "643",
"min": "100.00",
"max": "5000.00"
}
Parameter | Required | Type | Description |
---|---|---|---|
currency | Yes | String | ISO ALFA3 Currency code |
min | No | String | Minimum amount allowed |
max | No | String | Maximum amount allowed |
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:42+03:00",
"cause": {
"property1": [
"string"
],
"property2": [
"string"
]
}
}
Sample Forms error response
HTTP/1.1 400 Bad Request
Content-Type: application/json
{
"errors" : [
{
"message" : "Message to user (in Russian)",
"parameter" : "account",
"state" : "Invalid",
"value" : "123123"
},
{
"parameter": "otherFieldName",
"state": "Missing"
}
],
"message" : "Message to user (in Russian)"
}
Within this Protocol, the following options of HTTP codes are applied:
Code | Description |
---|---|
200 | Successful or conditionally successful |
400 | The request parameters are not valid, the request is not processed |
401 | The token(certificate) is not provided or is invalid |
403 | Insufficient rights to run the specified request |
404 | Object (e.g. payment) with these IDs is not found |
Detailed decoding of the result of the request processing is transferred to the field errorCode
of the requested (returned) object.
If the API has processed the request but the requested (returned) object cannot be formed, the following object is returned:
- CommonError Для методов Pauout API
- FormsError Для методов Forms API
FormsError
{
"errors" : [
{
"message" : "Неверный номер счета",
"parameter" : "account",
"state" : "Invalid",
"value" : "42301840000000000001"
}
],
"message" : "Ошибка валидации"
}
Parameter | Required | Type | Description |
---|---|---|---|
type | No | String | Type of error (if available) |
errors | No | FormsErrors | Array of Forms Error elements |
message | Yes | String | Common error description |
Element FormsErrors
{
"message" : "Неверный номер счета",
"parameter" : "account",
"state" : "Invalid",
"value" : "42301840000000000001"
}
Parameter | Required | Type | Description |
---|---|---|---|
message | Yes | String | Error description |
parameter | Yes | String | Parameter with error |
state | No | String | State of parameter |
value | Yes | String | Wrong value of parameter |
CommonError
{
"serviceName": "XXX",
"errorCode": "INSUFFICIENT_FUNDS",
"userMessage": "Message to user (in Russian)",
"description": "Error description",
"traceId": "1236654998241657",
"dateTime": "2018-12-06T14:08:46.598+03:00",
"cause": {
"msg1": ["amount>1500000"]
}
}
Parameter | Required | Type | Description |
---|---|---|---|
serviceName | 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
To call API methods in test environment, use the following endpoints:
API Section | Authorization | Encryption | URL |
---|---|---|---|
{payout.api.url} | Token | RSA | https://api-test.qiwi.com/partner/payout/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/ |
Production environment
To call API methods in production environment, use the following endpoints:
API Section | Authorization | Encryption | URL |
---|---|---|---|
{payout.api.url} | Token | RSA | https://api.qiwi.com/partner/payout/v1/ |
{payout.api.url} | Certificate | RSA | https://private-api.qiwi.com/partner/payout/v1/ |
{forms.api.url} | Token | RSA | https://api.qiwi.com/partner/sinap/ |
{forms.api.url} | Certificate | RSA | https://private-api.qiwi.com/partner/sinap/ |
{payout.api.url} | Token | GOST | https://api-gost.qiwi.com/partner/payout/v1/ |
{payout.api.url} | Certificate | GOST | https://private-api-gost.qiwi.com/partner/payout/v1/ |
{forms.api.url} | Token | GOST | https://api-gost.qiwi.com/partner/sinap/ |
{forms.api.url} | Certificate | GOST | https://private-api-gost.qiwi.com/partner/sinap/ |