Вопросы
bss@qiwi.com
NAV Navbar
Пример

Введение


Универсальное API выплат в сторону любых получателей платежей (провайдеров)

Среди возможных получателей доступны:

Универсальное API построено на вызовах методов двух различных программных интерфейсов. Forms API и Payout API.


Встречающиеся в документе термины и сокращения

Токен: Символьная строка для аутентификации контрагента согласно стандарту OAuth 2.0 [RFC 6749] [RFC 6750]
API: Application Programming Interface - набор готовых методов, предоставляемых приложением (системой) для использования во внешних программных продуктах
JSON: JavaScript Object Notation - текстовый формат обмена данными, основанный на JavaScript [RFC 7159]
path: Параметры передаются как часть пути в URL
query: Параметры передаются как параметры URL запроса (после "?") header: Параметры передаются в HTTP заголовке запроса
body: Параметры передаются в теле запроса

Использование

Диаграмма использования методов API

Базовая диаграмма последовательности

Методы Forms API описаны в разделе Методы Forms API
Методы Payout API описаны в разделе Методы Payout API

Вариант реализации методов API на кассе

Ниже рассматривается вариант реализации приема оплаты на кассе контрагента с использованием данного API

Сценарий шага 1. Проверка возможности проведения платежа

Заинтересованное лицо:

Основное действующее лицо:

Действующие лица:

Цель:

Триггер:

Основной сценарий:

  1. Кассир находит получателя платежа в системе
    Используются методы Запрос дерева каталога провайдеров или Запрос списка провайдеров
  2. Система запрашивает данные для оплаты
    Используются методы Формы провайдера
  3. Кассир вводит реквизиты платежа и идентификационные данные, с помощью системы убеждается в полноте и корректности введенных данных и начинает проверку возможности оплаты
  4. Система передает в API все реквизиты платежа и API подтверждает возможность проведение оплаты
    Используется метод Создание заявки на платеж
  5. Кассир сообщает клиенту о возможности проведения платежа и переходит к сценарию шага 2.

Альтернативный сценарий:

Сценарий шага 2. Проведение платежа.

Заинтересованное лицо:

Основное действующее лицо:

Действующие лица:

Цель:

Триггер:

Основной сценарий:

  1. Кассир принимает денежные средства от Клиента
  2. Кассир инициирует в Системе процесс оплаты разрешенного в сценарии шага 1 платежа.
  3. Система проводит оплату разрешенного в сценарии шага 1 платежа
    Используется метод Исполнение заявки на платеж
  4. Система выполняет печать кассового чека
  5. Кассир предоставляет чек об оказанной услуге Клиенту

Альтернативный сценарий:

Варианты основного сценария:

Авторизация

Авторизация при вызовах методов Payout API

GET https://{payout.api.url}/some/method HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>

Запросы контрагента при вызовах методов Payout API авторизуются посредством предоставленного в запросе и известного только контрагенту токена.
Токен указывается в заголовке Authorization: Bearer См [RFC 6749] [RFC 6750]

Так же возможна авторизация путем предъявления цифрового сертификата формата X.509 v3. [RFC 5280]
В этом случае на стороне клиента заголовок Authorization: Bearer не формируется.

Дополнительная авторизация при вызовах методов Forms API

GET https://{forms.api.url}/some/method HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
X-Application-Id: <X-Application-Id-String>
X-Application-Secret: <X-Application-Secret-String>

Запросы контрагента при вызовах методов Forms API аналогичны авторизации для методов Payout API. Но дополнительно должны быть сопровождены в заголовках идентификаторами определяющими версию вызываемой аппликации X-Application-Id и кодом доступа к ней X-Application-Secret

Указанные значения предоставляются контрагенту отдельно.

Работа с методами и данными

API использует REST-архитектуру.

Согласно указанной архитектуре в настоящем API используются следующие HTTP методы (HTTP Request):

Большинство методов обеспечивают физическую или логическую идемпотентность (когда клиенты могут делать один и тот же вызов неоднократно при одном и том же результате). Не смотря на то, что идемпотентные операции производят один и тот же результат на сервере, ответ сам по себе может не быть тем же самым (например, состояние платежа может измениться между запросами).

Методы GET реализованы как операции только для чтения, что делает их идемпотентными. Однако это тоже не означает, что сервер должен возвращать тот же самый результат каждый раз. Так как состояние запрашиваемого объекта (платежа) может меняться.

Данные в методах передаются следующими способами

Возвращаемые данные передаются как элементы JSON объектов.

Если посылаемый запрос в теле сопровождается JSON объектом необходимо использовать заголовок Content-Type: application/json

Аналогично, чтобы определить, какой тип представления необходим на стороне клиента, используется HTTP-заголовок Accept: application/json

Методы Forms API


Формы провайдера

Description: Применяется для получения формы интерфейса провайдера
HTTP Request: GET {forms.api.url}/providers/{id}/form

Запрос

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

Параметры

Параметр Положение Описание Обязательность Тип
id path Идентификатор провайдера Yes string

Ответ

Пример ответа

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
                  }
                ]
              }
            }
          ]
        }
      }
    ]
  }
}
Поле Тип Описание
id string Идентификатор провайдера
content/elements Массив Elements интерфейсная форма
content/terms Terms Объект класса, описывающий условия платежа (комиссии, лимиты на платеж и т.д.)

Онлайн-запрос данных

Description: Применяется для получения данных онлайн обработки данных по провайдеру
HTTP Request: POST {forms.api.url}/refs/{id}/containers

Параметры

Запрос

POST {forms.api.url}/refs/somebank/containers HTTP/1.1
Accept: application/json
Content-type: application/json
Authorization: Bearer <Token-String>
X-Application-Id: <X-Application-Id-String>
X-Application-Secret: <X-Application-Secret-String>

{
    "account": "42301810000000000001"
}
Параметр Положение Описание Обязательность Тип
id path Идентификатор запроса Yes string

Тело запроса содержит набор объектов со следующей структурой:

Параметр Тип Описание
Имя параметра берется из массива params объекта "type": "ref" в массиве elements string Значение параметра определено в интерфейсе

Применение

Онлайн проверка вызывается если поле в форме определено как поле с дополнительной онлайн обработкой "type":"ref"

Результатом запроса может быть:

Пример поля, для которого применяется данный метод

{
    "id":"somebank",
    "type":"ref",
    "title":"Проверить номер счета",
    "message":"Необходимо проверить номер счета",
    "params":[{
        "field":"account",
        "triggerReload": true
        }
      ]
}

Структура "ref" является частью структуры массива Elements

Параметр Обязательность Тип Описание
type Yes константа "ref" Тип элемента требующего онлайн обработку
title Yes string заголовок поля
message Yes string сообщение о проверке
id Yes string Идентификатор для запроса
params Yes string массив для отправки запроса. Содержит объекты параметров: пара "field" - name (имя параметра из родительского объекта field) и пара "triggerReload" - true/false (если true, то при изменении значения параметра name пользователем поле должно автоматически обновиться с новым значением)

Ответ

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

{
  "elements": [
    {
      "type": "field",
      "view": {
        "title": "Рекомендуемый минимальный платеж",
        "prompt": "Рекомендуемый минимальный платеж",
        "widget": {
          "type": "info"
        }, "value": "3510.00"
      }
    }
  ]
}

Возвращаемый ответ в случае успешной проверки возвращает массив, который содержит:

Или возвращает ошибку в формате FormsError

Модели данных Forms API

Класс Content

Базовый контейнер, содержит объект класса Elements с элементами страниц.

Класс Terms

Объект класса, описывающий условия платежа

{
  "type": "DefaultPayoutTerms",
  "id": "mosoblgaz-podolsk"
}
Параметр Обязательность Тип Описание
id Yes String идентификатор провайдера(если отличается от идентификатора формы, то сам платеж необходимо выполнять именно на этот идентификатор)
type Yes String тип схемы оплаты провайдера. Возможные значения:
"DefaultPayoutTerms" - Единственная схема оплаты
sumConstraint No SumConstraint Ограничения на сумму платежа

Класс SumConstraint

Объект класса, описывающий ограничения на сумму платежа

{
   "type": "FixedSumConstraint",
   "sum" : {
      "currency": "RUB",
      "value":"123.45"
    }
}

Параметры завситят от обязательного параметра "type", объекта, который может принимать следующие значения:

SumConstraint "FixedSumConstraint"

Параметр Обязательность Тип Описание
type Yes String "FixedSumConstraint" - сумма не может быть изменена
sum No Money Cумма к оплате.

SumConstraint "EditableSumConstraint"

Параметр Обязательность Тип Описание
type Yes String "EditableSumConstraint" - сумма может быть изменена
suggestedSum No Money Рекмендованная сумма к оплате.
limit No Limit Лимитированные ограничения на сумму платежа

Массив Elements

Массив объектов класса Elements интерфейсной формы. Каждый объект массива данного класса содержит параметры.

Параметры зависят от обязательного параметра "type", объекта, который может принимать следующие значения:

Элемент Elements "field"

Параметр Тип Описание
type String "field" - элемент для безусловного отображения
name String Имя переменной, соответствующей элементу формы.
validator Validator Условия проверки значения name.
view  View Параметры отображения элемента формы.
Если отсутствует, то элемент является скрытым
value String Значение отображаемого поля, если элемент статический, или значения по умолчанию, если он может изменяться.
sensitiveData boolean Если true - данные в поле конфиденциальные (требуется маскирование на экране, на чеке, в логах и т.д.)
hideFromConfirmationScreen boolean Определяет скрывать (true) или показывать (false) данное поле с его описанием на экране подтверждения и/или предварительной проверки.
semantics Semantic (необязательно) Объект класса, описывающий семантику поля (например для дополнительной валидации/помощи при вводе).

Элемент Elements "dependency"

Параметр Тип Описание
type String "dependency" - элемент с условиями отображения
condition Condition Условия отображения элемента формы.
content Content Описание элемента дополнительной интерфейсной формы которую необходимо обработать если условие condition выполнены.

Элемент Elements "ref"

Параметр Тип Описание
type String "ref" - элемент, порождающий онлайн-проверку
id String Идентификатор онлайн-запроса /refs.
message String Сообщение о проверке.
title String Заголовок поля.
params Массив Массив для отправки в запросе /refs. Содержит объекты с параметрами "field" - <name> и "triggerReload" - true/false (если true, то при изменении значения параметра <name> пользователем на интерфейсной форме объект должен автоматически обновиться с новым значением)

Пример с type "ref" приведен в описании метода Онлайн-запрос данных

Класс Semantic

Опциональная семантика поля. Может быть использована для дополнительной валидации/помощи при вводе, или другой обработки в зависимости от реализации на стороне контрагента.

{
  "semantics": {
  "type": "LastName"
  }
}
Параметр Тип Описание
type String Enum:
"FirstName" - Имя
"LastName" - Фамилия
"MiddleName" - Отчество
"OwnerFirstName" - Имя плательщика
"OwnerLastName" - Фамилия плательщика
"OwnerMiddleName" - Отчество плательщика
"BirthDate" - Дата рождения
"Email" - Адрес электроной почты
"Phone" - Неомер телефона
"WalletPhone" - Номер кошелька
"CardNumber" - Номер карты

Класс Validator

Блок условий проверки значения переменной <name>. Параметры:

{
  "type":"predicate",
  "predicate":{
    "type" : "regex",
    "pattern" : "^(\d{16}|\d{18}|\d{19})$"
  },
  "message":"Проверьте номер карты"
}
Параметр Тип Описание
type String Тип проверки. Возможные значения:
"predicate" - логическое условие или совокупность логических условий
message String сообщение, если значение не прошло проверку
predicate Predicate блок условий проверки (только для type "predicate").

Класс Condition

{
    "type": "predicate",
    "field": "account_type",
    "predicate": {
        "type": "regex",
        "pattern": "^\d{10,11}$"
    }
}

Параметры завситят от обязательного параметра "type", объекта, который может принимать следующие значения:

Condition "predicate"

Параметр Тип Описание
type String "predicate" - проверка значения поля через логические условия
predicate Predicate  
field String Поле, которое проверяется. Если проверка успешна, то элемент формы отображается.

Condition "and"

Параметр Тип Описание
type String "and" - проверка значений нескольких полей с оператором "И"
conditions array Объект содержит пары:
"field" - <name> - название поля
"type" - "validity" - тип проверки (найти объект Validator для этого поля и проверить)

Класс Predicate

Объект содержит логические условия проверки.

Параметры зависят от обязательного параметра "type", который может принимать следующие значения:

Predicate "regex"

{
  "type" : "regex",
  "pattern" : "^2$|^5$"
}
Параметр Тип Описание
type String "regex" - проверка через регулярное выражение
pattern String Содержит регулярное выражение для проверки значения

Predicate "and"

{
  "type": "and",
  "subpredicates": [
    {
      "type": "regex",
      "pattern": "^\\d{16,20}$"
    },
    {
      "type": "regex",
      "pattern": "^4"
    }
  ]
}
Параметр Тип Описание
type String "and" - совокупность логических условий с оператором "И"
subpredicates array [Predicate] Проверка всех условий в массиве, комбинированных логическим оператором "И"

Класс View

{
  "title": "Номер счета",
  "prompt": "Номер счета",
  "widget": {}
}
Параметр Тип Описание
title String Заголовок элемента формы
prompt String Всплывающая подсказка
info String Дополнительная информация об элементе. Может скрываться под справочной кнопкой. В тексте может использоваться язык Markdown
widget Widget Тип элемента формы и его свойства

Класс Widget

Пример widget с элементами radio

{
  "type": "radio",
  "choices": [{
      "value": "1",
      "title": "Номер карты"
  },
  {
      "value": "2",
      "title": "Номер счета"
  }]
}

Пример widget с текстом

{
    "type": "text",
    "mask": "dddd dddd dddd dddd?dd",
    "keyboard": "numeric"
}

Параметры зависят от обязательного параметра "type", объекта, который может принимать следующие значения:

Widget "info"

Отображаемое и неизменяемое (статическое) поле

Параметр Тип Описание
type String "info" - статический текст, определяется в родительском View

Widget "text"

Стандартное поле ввода

Параметр Тип Описание
type String "text" - поле ввода, определяется в родительском View
mask String Маска ввода в поле (см. ниже)
keyboard String Тип рекомендованной клавиатуры ввода - "numeric", "text" (по умолчанию).
stripStaticSymbols boolean Признак проверки значения с маской. Если равен true, то перед проверкой маскированного значения нужно убрать все статические символы.

Каждая маска поля в представляет собой строку, составленную из символов трёх видов:

Widget "date"

Поле ввода даты

Параметр Тип Описание
type String "date" - поле ввода даты
format String Формат ввода даты
allowsFutureDate boolean допустима ли дата позднее текущей

Widget "radio"

Элемент предназначен для списка позиций. Выбрана может быть только одна из них.

Параметр Тип Описание
type String "radio" - список выбираемых позиций в виде кнопок
expansion Expansion Описание списка скрываемых позиций.
choices Массив элементов Choices Описание списка позиций.

Widget "list"

Элемент предназначен для списка позиций. Отображение в виде кнопок с пролистыванием.

Параметр Тип Описание
type String "list" - список выбираемых позиций в виде списка
choices Массив элементов Choices Описание списка позиций.

Widget "switch"

Выбор из двух возможных значений. Например чекбокс или переключатель.

Параметр Тип Описание
type String "switch" - список выбираемых позиций в виде списка
offValue String Значение, если чекбокс (переключатель) выключен
onValue String Значение, если чекбокс (переключатель) включен

Класс Expansion

Параметр Тип Описание
threshold number Количество отображаемых позиций (кнопок)
title String Заголовок для скрытия позиций. Если количество позиций в массиве "choices" больше, чем указано в threshold, то они скрываются под этим заголовком.

Элемент класса Choices

Параметр Тип Описание
title String Название позиции (кнопки) в интерфейсе
value Number Числовое значение, соответствующее выбору позиции - присваивается переменной из объекта элемента формы

Сервисные методы Payout API


Запрос дерева каталога провайдеров

Description: Запрос каталога провайдеров
HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/providers/directory/{providerCode}

Запрос всего каталога

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

Запрос дочерних для узла "money-transfer" провайдеров/категорий/узлов.

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

Параметры

Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string
providerCode path Уникальный мнемонический идентификатор провайдера/узла No string
expand query Возвращать только запрошенный {providerCode}, с одним уровнем принадлежащих ему узлов No string

Ответ

Ответ на запрос всего каталога

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

Успешный ответ содержит дерево элементов доступных провайдеров/узлов, в формате объекта Provider

Ответ на запрос дочерних для узла money-transfer провайдеров и категорий.

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

{
   "providerCode" : "money-transfer",
   "name": "Денежные переводы",
   "payable" : false,
   "form": false,
   "parents": ["root"],
   "children": [
       {
           "providerCode" : "contact",
           "name": "Денежные переводы Контакт",
           "payable" : false,
           "form": true,
           "parents": ["money-transfer"],
           "children": []
       },
       {
           "providerCode" : "unistream",
           "name": "Денежные переводы Юнистрим",
           "payable" : true,
           "form": true,
           "parents": ["money-transfer"],
           "children": []
       }
   ]
}

Дополнение

Комбинации form и payable:

form payable Описание
true true Платежный элемент, для которого есть форма в Forms API
true false Не платежный элемент, для которого есть форма в Forms API, по результатам обработки которой возможно получение платежного идентификатора узла
false true Платежный элемент, для которого не предусмотрена форма в Forms API. Данный вид платежного элемента:
- или не подразумевает работу с плательщиком напрямую и задания им параметров, где параметры жестко фиксированы и согласованы отдельно,
- или данный узел получается из формы описанной в предыдущем пункте
false false Не платежный элемент. Например узел, содержащий в себе другие элементы

Запрос списка провайдеров

Description: Запрос всех провайдеров в виде плоского списка
HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/providers

Запрос

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

Параметры

Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string

Ответ

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

Ответ

Успешный ответ содержит последовательный массив элементов провайдеров объекта ProviderBrief

Отличие от предыдущего метода в том, что выводятся только список доступных провайдеров в которые можно производить оплату. Поэтому параметры элементов сокращены до необходимого минимума.

Запрос информации о провайдере

Description: Запрос расширенной информации о провайдере
HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/providers/{providerCode}

Запрос

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

Параметры

Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string
providerCode path Код получателя Yes string

Ответ

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

{
  "name": "Qiwi кошелек",
  "legalName": "КИВИ Банк (АО)",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "identificationLevels": {
    "RUB": [
      {
        "min": "1.00",
        "max": "15000.00",
        "identificationType": "NONE"
      },
      {
        "min": "15000.01",
        "max": "600000.00",
        "identificationType": "SIMPLIFIED"
      }
    ]
  }
}

Ответ

Успешный ответ содержит полную информация о провайдере, установленных у него лимитах платежа и требуемых уровнях идентификации в формате объекта ProviderInfo

Запрос баланса

Description: Запрос доступного для проведения платежей баланса
HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/balance

Запрос

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

Параметры

Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string

Ответ

Ответ

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

{
  "balance": {
    "value": "200.00",
    "currency": "RUB"
  },
  "overdraft": {
    "value": "200.00",
    "currency": "RUB"
  },
  "available": {
    "value": "400.00",
    "currency": "RUB"
  }
}

Успешный ответ содержит информацию о доступном для проведения платежа балансе в формате BalanceInfo

Платежные методы Payout API


Создание заявки на платеж

Description: Регистрация платежа и подготовка его для дальнейшего исполнения
HTTP Request: PUT {payout.api.url}/agents/{agentId}/points/{pointId}/payments/{paymentId}

Параметры

Пример запроса

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": "79123456789"
    }
  },
  "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"
}
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string
paymentId path Уникальный идентификатор платежа Yes string
body body Объект создания платежа Yes PaymentCreationParams

В теле запроса передается объект PaymentCreationParams, заполненный ПО контрагента. Данные для формирования объекта берутся из системы ПО контрагента. Данные вложенного объекта recipientDetails из форм SINAP.

Ответ

Ответ в формате объекта PaymentInfo

Пример тела успешного ответа

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": "READY",
    "changedDateTime": "2018-11-27T14:02:35.646Z",
    "identificationType": "NONE"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "acсount": "79123456789"
    }
  },
  "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": "Иванов",
    "something": "Что-то нужное контрагенту",
    "somethingone": "Еще что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE",
  "billingDetails": {
    "transactionId":"1000200300",
  }
}

Исполнение заявки на платеж (Исполнение платежа)

Description: Исполнение ранее подготовленного и зарегистрированного платежа
HTTP Request: POST /v1/points/{pointId}/payments/{paymentId}/execute

Параметры

Пример запроса

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>
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string
paymentId path Уникальный идентификатор платежа Yes string

Ответ

Ответ в формате объекта PaymentInfo

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": "qiwi-wallet",
    "fields": {
      "account": "79123456789"
    }
  },
  "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": "Иванов",
    "something": "Что-то нужное контрагенту",
    "somethingone": "Еще что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
  "billingDetails": {
    "transactionId":"1000200300",
    "rrn": "abcDE123"
  }
}

Отмена заявки на платеж

Description: Отмена регистрации ранее подготовленного и зарегистрированного платежа
HTTP Request: POST {payout.api.url}/agents/{agentId}/points/{pointId}/payments/{paymentId}/reject

Параметры

Пример запроса

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>
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string
paymentId path Уникальный идентификатор платежа Yes string

Ответ

Ответ в формате объекта PaymentInfo

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": "FULL"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789"
    }
  },
  "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": "Иванов",
    "something": "Что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
}

Обогащение заявки на платеж

Description: Дополнение заявки на платеж недостающими для ее исполнения данными HTTP Request: PATCH {payout.api.url}/agents/{agentId}/points/{pointId}/payments/{paymentId}

В настоящее время запрос используется для обогащения идентификационными данными. Подробности в разделе Идентификация плательщика.

Параметры

Пример запроса с добавления в платеж объекта целиком

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": "/identification",
        "values": {
            "type": "SIMPLIFIED",
            "person": {
                "fullName": {
                    "firstName": "Михаил",
                    "lastName": "Олимпийский",
                    "middleName": "Потапович"
                },
                "birthDate": "1977-12-19",
                "citizenship": "SU"
            },
            "document": {
                "type": "PASSPORT_SIMPLIFIED",
                "serial": "XXII",
                "number": "030880"
            }
        }
    }
]

Пример запроса с добавление в платеж объекта по полям.

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": "/identification/type", "value": "SIMPLIFIED"},
  {"op": "add", "path": "/identification/person/fullName/firstName", "value": "Михаил"},
  {"op": "add", "path": "/identification/person/fullName/lastName", "value": "Олимпийский"},
  {"op": "add", "path": "/identification/person/fullName/middleName", "value": "Потапович"},
  {"op": "add", "path": "/identification/person/birthDate", "value": "1977-12-19"},
  {"op": "add", "path": "/identification/person/itizenship", "value": "SU"},
  {"op": "add", "path": "/identification/document/type", "value": "PASSPORT_SIMPLIFIED"},
  {"op": "add", "path": "/identification/document/serial", "value": "XXII"},
  {"op": "add", "path": "/identification/document/number", "value": "030880"}
]
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string
paymentId path Уникальный идентификатор платежа Yes string
body body дополняемые данные согласно [RFC 6902] Yes  

Ответ

Ответ в формате объекта PaymentInfo

Пример ответа

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": "READY",
    "changedDateTime": "2018-11-27T14:07:05.652Z",
    "identificationType": "SIMPLIFIED"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789"
    }
  },
  "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": "Иванов",
    "something": "Что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "SIMPLIFIED"
}

Получить все платежи

Description: Ищет и возвращает информацию о всех платежах за текущую дату
HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/payments

Параметры

Пример запроса

GET {payout.api.url}/agents/acme/points/00001/payments HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа 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

Ответ

Ответ в формате массива объектов PaymentInfo

Пример успешного ответа

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": "COMPLETED",
      "changedDateTime": "2018-11-27T13:44:34.034Z",
      "identificationType": "NONE"
    },
    "recipientDetails": {
      "providerCode": "qiwi-wallet",
      "fields": {
        "account": "79123456789"
      }
    },
    "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": "Иванов",
      "something": "Что-то нужное контрагенту",
      "somethingone": "Еще что-то нужное контрагенту"
    },
    "callbackUrl": "https://domain/path",
    "identificationType": "NONE"
  }
]

Поиск платежа и получение его статуса

Description: Поиск платежа и возврат информации о найденном платеже
HTTP Request: GET {payout.api.url}/agents/{agentId}/points/{pointId}/payments/{paymentId}

Параметры

Пример запроса

GET {payout.api.url}/agents/acme/points/00001/payments/c0d85b0b-a528-9c66-4a15-cb7a12eda9d6 HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента Yes string
pointId path Уникальный идентификатор точки приема платежа Yes string
paymentId path Уникальный идентификатор платежа Yes string

Ответ

Ответ в формате объекта PaymentInfo

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": "COMPLETED",
    "changedDateTime": "2018-11-27T14:00:56.973Z",
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789"
    }
  },
  "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": "Иванов",
    "something": "Что-то нужное контрагенту",
    "somethingone": "Еще что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "identificationType": "NONE"
}

Уведомление о результатах платежа

Description: Отправка уведомления о результатах платежа на сервер контрагента
HTTP Request: POST {webhook.api.url}/webhook/points/{pointId}/payments/{paymentId}/confirm

Параметры

Пример запроса

POST https://{webhook.api.url}/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"
  }
}
Параметр Положение Описание Обязательность Тип
paymentId path Уникальный идентификатор платежа Yes string
pointId path Уникальный идентификатор точки приема платежа 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

Метод инициализируется только в том случае, если в момент создания платежа был предоставлен элемент callbackUrl объекта PaymentCreationParams

Ответ

Тело ответа не анализируется

Специфичные для запроса HTTP коды ответов

Code Описание
XXX Любой код отличный от 200 рассматривается как ошибка. Система продолжит повторять уведомление

Идентификация плательщика


Согласно федеральному закону О противодействии легализации (отмыванию) доходов, полученных преступным путем, и финансированию терроризма" от 07.08.2001 N 115-ФЗ и другим подзаконным документам регулирующим проведение платежей - для исполнения платежа может потребоваться предоставление контрагентом данных, идентифицирующих плательщика.

Уровни идентификации

В настоящее время поддерживаются три уровня идентификации (по мере их полноты) :

  1. "NONE" - идентификации не требуется
  2. "SIMPLIFIED" - требуется упрощенная идентификация
  3. "FULL" - требуется полная идентификация

Уровень идентификации соответственно определяет перечень полей, необходимый для предоставления в платеже и описывается в классах IdentificationSimple для упрощенной и IdentificationFull для полной идентификации.

Предоставление идентификации

Предоставление идентификации после создания платежа

Платеж может быть дополнен идентификационными данными после создания платежа.
Для этого используется запрос Обогащение заявки на платеж.

Определение необходимого уровня идентификации описано ниже

Предоставление идентификации при создании платежа

Пример объекта PaymentCreationParams сопровожденного идентификационными данными

{
  "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": "",
  "identification": {
    "type": "SIMPLIFIED",
    "person": {
      "fullName": {
        "firstName": "Михаил",
        "lastName": "Олимпийский",
        "middleName": "Потапович"
      },
      "birthDate": "1977-12-19",
      "citizenship": "SU"
    },
    "document": {
      "type": "PASSPORT_SIMPLIFIED",
      "serial": "XXII",
      "number": "030880"
    }
  }
}

В случае, если Контрагент заранее знает, что создаваемый платеж потребует той или иной уровень идентификации - то указанная информация может быть предоставлена сразу при создании платежа, и указана в объекте Identification класса PaymentCreationParams

Необходимый уровень идентификации

Пример объекта status у платежа требующего полную идентификацию

{
  "status": {
    "value": "CREATED",
    "changedDateTime": "2018-11-27T13:44:34.034Z",
    "identificationType": "FULL"
  }
}

Минимально необходимый уровень для проведения платежа сообщается при создании заявки на платеж в объекте identificationType класса status класса paymentInfo.

Уже предоставленный уровень идентифкация сообщается в объекте identificationType объекта paymentInfo

Для исполнения платежа уровень предоставленной идентификации должен быть равен или выше уровня требуемой. Платеж не сможет быть исполнен (не получит статус "READY") до тех пор, пока уровень предоставленной идентификации ниже, чем уровень требуемой.

Форма для ввода необходимого для идентификации набора полей

Контрагент, для автоматизации ввода данных кассиром, может использовать специализированные формы Forms API

Для каждого уровня идентификации существует соответствующая форма квазипровайдера

Уровень идентификации identificationType id провайдера Forms API
Упрощенная SIMPLIFIED identification-simplified
Полная FULL identification-full

Запрос формы для полной идентификации

GET https://*/providers/identification-full/form HTTP/1.1
Accept: application/json
X-Application-Id: <X-Application-Id-String>
X-Application-Secret: <X-Application-Secret-String>

По результатам обработки формы получается набор полей и значений.
Имя каждого поля использует нотацию [RFC 6901] применяемую в [RFC 6902] и определяет конкретный объект класса Identification и значение, определяющее содержимое этого объекта.

Эти данные следует использовать для Предоставления идентификации (создания объекта класса Identification)

Модели данных Payout API


Класс BalanceInfo

Объект описывающий доступный для проведения платежей баланс

Параметр Обязательность Тип Описание
balance No Money Доступный баланс
overdraft No Money Разрешенное превышение баланса
available Yes Money Общий доступный лимит

Класс BillingDetails

Объект описывающий дополнительную информацию со стороны биллинга получателя (провайдера)

Параметр Обязательность Тип Описание
transactionId No String Номер платежа на стороне получателя
rrn No String Код акцептования платежа на стороне получателя
accountNumber No String Номер счета(или другой дополнительный параметр) для подтверждения платежа
accountInfo No String Дополнительная информация со стороны получателя
receiptUrl No String Ссылка на интернет ресурс получателя, содержащая информацию о платеже

Класс Customer

Необязательный объект дополнительно описывающий плательщика (не содержит данных идентифицирующих плательщика согласно законодательству РФ)

Параметр Обязательность Тип Описание
account No String Номер счета/договора и т.п.
email No String Емейл плательщика
phone No String Телефон плательщика

Класс Document

Общее описание документа удостоверяющего личность

Параметр Обязательность Тип Описание
one of Yes Passport
ForeignPassport
Visa
MigrationCard
ResidencePermit
RefugeeCertificate
один из перечисленных видов документов

Класс DocumentSimplified

Общее описание документа удостоверяющего личность (упрощенная форма)

Параметр Обязательность Тип Описание
one of Yes PassportSimplified один из перечисленных видов документов

Класс ForeignPassport

Паспорт иностраннного гражданина

Параметр Обязательность Тип Описание
type Yes String константа "FOREIGN_PASSPORT"
serial No String Серия документа
number Yes String Номер документа
issuer No String Кем выдан
issueDate Yes String Когда выдан или дата начала действия (в формате YYYY-MM-DD)
expiryDate No String Дата окончания действия (в формате YYYY-MM-DD)

Класс Identification

Идентификационные данные плательщика

Параметр Обязательность Тип Описание
one of No IdentificationFull
IdentificationSimple
 

Класс IdentificationFull

Данные о полной идентификации плательщика

Параметр Обязательность Тип Описание
type Yes IdentificationType константа "FULL"
person Yes Person Полные данные о плательщике
document Yes Document Основной документ
extraDocuments No array[Document] Дополнительные документы

Класс IdentificationSimple

Данные об упрощённой идентификации плательщика

Параметр Обязательность Тип Описание
type Yes IdentificationType константа "SIMPLIFIED"
person Yes PersonSimplified Упрощенные данные о плательщике
document Yes DocumentSimplified Упрощенные данные о документе удостоверяющим личность

Класс IdentificationType

Вид требуемой или предоставленной идентификации

Параметр Обязательность Тип Описание
значение Yes String Предоставленная идентификация
Enum
"NONE" нет
"FULL" полная
"SIMPLIFIED" упрощенная

Класс IdentificationLevel

Требуемый для указанной суммы уровень идентификации

{
  "RUB":[
    {
      "min": "1.00",
      "max": "15000.00",
      "identificationType": "NONE"
    },
    {
      "min": "15000.01",
      "max": "600000.00",
      "identificationType": "SIMPLIFIED"
    }
  ]
}

Объект ключ:значение, где в качестве ключа выступает объект типа currency, а в качества значение выступает массив объектов с приведенными ниже параметрами:

Параметр Обязательность Тип Описание
min No String Минимальная граница денежной суммы (включительно)
max No String Максимальная граница денежной суммы (включительно)
identificationType No IdentificationType Уровень идентификации, распространяющийся на указанный диапазон денежной суммы

Класс MigrationCard

Миграционная карта

Параметр Обязательность Тип Описание
type Yes String константа "MIGRATION_CARD"
serial Yes String Серия
number Yes String Номер
arrivalDate Yes String Дата прибытия (в формате YYYY-MM-DD)
departureDate Yes String Дата предполагаемого убытия (в формате YYYY-MM-DD)

Класс Passport

Полные данные паспорта РФ

Параметр Обязательность Тип Описание
type Yes String константа "PASSPORT"
serial Yes String серия
number Yes String номер
issuer Yes String Кем выдан
issueDate Yes String Дата выдачи (в формате YYYY-MM-DD)
divisionCode Yes String Код подразделения (в формате NNN-NNN)

Класс PassportSimplified

Упрощенные данные паспорта РФ

Параметр Обязательность Тип Описание
type Yes String константа "PASSPORT_SIMPLIFIED"
serial Yes String серия
number Yes String номер

Класс PaymentCreationParams

Объект создания платежа

{
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79123456789"    }
  },
  "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": {}
}
Параметр Обязательность Тип Описание
recipientDetails Yes RecipientDetails Объект, описывающий получателя платежа
amount Yes Money Объект, описывающий сумму платежа
customer No Customer Объект, описывающий плательщика
source No Source Объект, описывающий инструмент платежа
customFields No map[String, String] Перечень дополнительных данных, которыми можно сопроводить платеж
callbackUrl No String Адрес вызова для метода Уведомление
identification No Identification Идентификационные данные, описывающие плательщика согласно законодательству РФ

Класс PaymentInfo

Объект существующего в системе платежа

{
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "acсount": "79123456789"
    }
  },
  "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"
}
Параметр Обязательность Тип Описание
paymentId Yes String Уникальный идентификатор платежа
creationDateTime Yes Date Дата создания платежа
expirationDatetime Yes Date Дата окончания жизни платежа
status Yes PaymentStatus  
recipientDetails Yes RecipientDetails Объект описывающий получателя платежа
amount Yes Money Объект описывающий сумму платежа
commission No Money  
gatewayError No CommonError  
customer No Customer Объект описывающий плательщика
source No Source  
customFields No map[String, String] Перечень дополнительных данных, которыми был сопровожден платеж
callbackUrl No String Адрес вызова для метода Уведомление
identificationType No IdentificationType Предоставленная идентификация
billingDetails No BillingDetails Дополнительная информация со стороны получателя (провайдера)

Класс PaymentStatus

Данные о текущем статусе платежа

"status": {
  "value": "IN_PROGRESS",
  "changedDateTime": "2018-11-27T14:06:17.108Z"
  }
"status": {
  "value": "FAILED",
  "changedDateTime": "2018-11-27T14:06:17.108Z",
  "errorCode": "BILLING_DECLINED",
  "errorMessage": "Параметр платежа указан неверно."
    }
Параметр Обязательность Тип Описание
value Yes String Статус
Enum
"CREATED" создан, но не готов к оплате
"READY" создан и готов к оплате
"FAILED" неуспешен
"IN_PROGRESS" в процессе исполнения
"COMPLETED" исполнен
"EXPIRED" просрочен
changedDateTime Yes Date Дата последнего изменения объекта платежа
errorCode No String
Enum
"INTERNAL_ERROR" ошибка без объяснения
"POINT_LIMIT_EXCEED" превышены лимиты по агенту/точке
"INSUFFICIENT_FUNDS" платеж на указанный размер платежа или валюту запрещен
"IDENTIFICATION_FAILED" идентификация плательщика не пройдена
"BILLING_DECLINED" платеж отклонен биллингом получателя
errorMessage No String Детальная расшифровка errorCode
identificationType No IdentificationType Требуемый для платежа уровень идентификации

Класс Person

Полные данные о плательщике (без документов)

Параметр Обязательность Тип Описание
fullName Yes PersonFullName ФИО
birthDate Yes String Дата рождения
citizenship Yes String Гражданство
birthPlace No String Место рождения
registrationAddress No String Место регистрации
residentialAddress No String Место фактического проживания

Класс PersonFullName

Полное имя плательщика

Параметр Обязательность Тип Описание
firstName Yes String Имя
lastName Yes String Фамилия
middleName No String Отчество (не обязательно только в случае его отсутствия)

Класс PersonSimplified

Упрощенные данные о плательщике (без документов)

Параметр Обязательность Тип Описание
fullName Yes PersonFullName  
birthDate Yes String Дата рождения
citizenship Yes String Гражданство

Класс Provider

{
   "providerCode" : "qiwi-wallet",
   "name": "Qiwi кошелек",
   "payable" : true,
   "form": true,
   "parents": ["money-transfer","e-money"],
   "children": []
 }

Данные об провайдере/узле

Параметр Обязательность Тип Описание
providerCode Yes string Уникальный мнемонический идентификатор провайдера
name Yes string Наименование провайдера
payable Yes boolean Означает, что элемент не является платежным и создание платежа для него не возможно (например является узлом)
form Yes boolean Означает, что к этому элементу есть форма, которую можно запросить из Forms API
parents Yes [string] Массив providerCode узлов, которому принадлежит этот элемент
children No [Provider] Рекурсивный массив элементов, которые принадлежат данному элементу

Класс ProviderBrief

{
   "providerCode" : "qiwi-wallet",
   "name": "Qiwi кошелек",
   "form": true
 }

Краткие данные о провайдере

Параметр Обязательность Тип Описание
providerCode Yes string Уникальный мнемонический идентификатор провайдера
name Yes string Наименование провайдера
form Yes boolean Означает, что к этому элементу есть форма, которую можно запросить из Forms API

Класс ProviderInfo

{
  "name": "Qiwi кошелек",
  "legalName": "КИВИ Банк (АО)",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "identificationLevels": {
    "RUB": [
      {
        "min": "1.00",
        "max": "15000.00",
        "identificationType": "NONE"
      },
      {
        "min": "15000.01",
        "max": "600000.00",
        "identificationType": "SIMPLIFIED"
      }
    ]
  }
}

Полная информация о провайдере, установленных у него лимитах платежа и требуемых уровнях идентификации.

Параметр Обязательность Тип Описание
name Yes string Наименование провайдера
legalName Yes string Юридическое наименование провайдера
amountLimits Yes set of amountLimit Набор разрешенных сумм для каждой из разрешенных валют
identificationLevels Yes set of identificationLevel Требуемые уровни идентификации для каждой из разрешенных валют
inn No string ИНН провайдера, если может быть указан
contact No Contact Контактные данные провайдера, если могут быть указаны

Класс RecipientDetails

  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "acсount": "79123456789"
    }
  }
Параметр Обязательность Тип Описание
providerCode Yes String Код получателя
Fields Yes map[String, String] Параметры платежа

Класс RefugeeCertificate

Удостоверение беженца

Параметр Обязательность Тип Описание
type Yes String константа "REFUGEE_CERTIFICATE"
serial Yes String серия
number Yes String номер
issuer Yes String кем выдан
issueDate Yes String Дата выдачи (в формате YYYY-MM-DD)
validThrough Yes String Действительно до (в формате YYYY-MM-DD)

Класс ResidencePermit

Вид на жительство

Параметр Обязательность Тип Описание
type Yes String константа "RESIDENCE_PERMIT"
serial Yes String серия
number Yes String номер
issuer Yes String кем выдан
issueDate Yes String Дата выдачи (в формате YYYY-MM-DD)
validThrough Yes String Действительно до (в формате YYYY-MM-DD)

Класс Source

Информация об источнике платежа

{
  "paymentType": "WITH_EXTRA_CHARGE",
  "paymentToolType": "CASH",
  "paymentTerminalType": "ATM_CASH_IN",
  "paymentDate": "2018-12-06T14:08:46.598Z",
  "extraCharge": {
    "value": "200.00",
    "currency": "RUB"
  }
}
Параметр Обязательность Тип Описание
paymentType Yes String Enum:
"NO_EXTRA_CHARGE" без комиссий взятой сверх платежа
"WITH_EXTRA_CHARGE" с комиссией сверх платежа
paymentToolType Yes String Enum:
"CASH" наличные
"BANK_ACCOUNT" банковский счет
"BANK_CARD" банковская карта
"BANK_CARD_OWN" банковская карта эммитированная данным банком
"ELECTRONIC_FUNDS" ЭДС
paymentTerminalType Yes String Enum:
"ATM_CASH_IN" Банкомат с CASH_IN
"ATM" Банкомат
"AUTO_PAYMENTS" Автоплатежи
"CASH_DESK" Касса
"POS_TERMINAL" POS терминал
"MOBILE_BANKING" Мобильный банкинг
"INTERNET_BANKING" Интернет банкинг
"ELECTRONIC_WALLET" ЭСП
"SELF_SERVICE_TERMINAL" Терминал самообслуживания
"IVR_CHANNELS" IVR каналы
paymentDate No Date  
extraCharge No Money Комиссия взятая сверх платежа, если "paymentType": "WITH_EXTRA_CHARGE"

Класс Visa

Виза на пребывание в РФ

{
  "type": "VISA",
  "serial": "A12",
  "number": "12345",
  "visaId": "1234",
  "issueDate": "2018-12-06",
  "entryFrom": "2018-12-06",
  "stayUntil": "2018-12-06"
}
Параметр Обязательность Тип Описание
type Yes String константа "VISA"
serial Yes String серия
number Yes String номер
visaId Yes String  
issueDate Yes String Дата выдачи в формате YYYY-MM-DD
entryFrom Yes String Дата начала действия в формате YYYY-MM-DD
stayUntil Yes String Дата окончания действия в формате YYYY-MM-DD

Класс WebhookPaymentInfo

Параметр Обязательность Тип Описание
paymentId Yes String Уникальный идентификатор платежа
status Yes PaymentStatus  
amount Yes Money  

Общие или пересекающиеся модели данных


Класс Money

Описание денежного поля

{
  "value": "200.00",
  "currency": "RUB"
}
Параметр Обязательность Тип Описание
value Yes String Денежная сумма
currency Yes String Код валюты

Класс AmountLimit

Лимитированные на валюту ограничения на сумму платежа

{
  "RUB":{
    "min": "100.00",
    "max": "5000.00"
  }
}

Объект ключ:значение, где в качестве ключа выступает объект типа currency, а в качества значение выступает объект с приведенными ниже параметрами:

Параметр Обязательность Тип Описание
min No String Минимальная разрешенная денежная сумма (включительно)
max No String Максимально разрешенная денежная сумма (включительно)

Класс Limit

Лимитированные ограничения на сумму платежа (с указанием валюты)

{
  "currency": "RUB",
  "min": "100.00",
  "max": "5000.00"
}
Параметр Обязательность Тип Описание
currency Yes String Код валюты
min No String Минимальная разрешенная денежная сумма (включительно)
max No String Максимально разрешенная денежная сумма (включительно)

Класс Contact

{
   "address" : "Россия, 117648, г. Москва, мкр. Чертаново Северное, д.1А, корп.1",
   "phoneNumber": "8 800 200-32-25"
 }

Краткие данные о контрагенте

Параметр Обязательность Тип Описание
address No string Почтовый адрес
phoneNumberme No string Телефонный номер

Типизированные поля

Данные поля указаны как String но имеют особую типизацию

String "paymentId"

Строка размерностью 36 символов после url-декодирования

Pattern .{1.36}

String "currency"

ISO 4217 ALFA3 Код валюты

Pattern ^[A-Z]{3}$

Пример: "RUB","USD"

String "currency value"

Числовое значение c разделителем "." (точка) и двумя цифрами после

Pattern ^([0-9]+)?[.][0-9]{2}$

Пример: "200.01", "0.10","10.00"

Document Date

Дата в формате YYYY-MM-DD

Пример: "2001-12-30"

Обработка ошибок


Коды ответов

Верхнеуровневые ошибки обработки запросов, согласно REST-архитектуре передаются в коде состояния HTTP [RFC 2068].

Пример ответа об ошибке Payout

HTTP/1.1 400 Unauthorized
Content-Type: application/json

{
    "serviceName": "string",
    "errorCode": "INTERNAL_ERROR",
    "userMessage": "Сообщение пользователю",
    "description": "Описание ошибки",
    "traceId": "string",
    "dateTime": "2018-11-27T14:24:42Z",
    "cause": {
        "property1": [
        "string"
        ],
        "property2": [
        "string"
        ]
    }
}

Пример ответа об ошибке Sinap

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

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

В рамках данного протокола применимы следующие варианты HTTP кодов:

Code Описание
200 Успешно или условно успешно
400 Параметры запроса не корректны, запрос не обработан
401 Токен не предоставлен или невалиден
403 Не достаточно прав для выполнения указанного запроса
404 Объект (например платеж) с такими идентификаторами не найден

Детальная расшифровка результата обработки запроса передается в поле errorCode запрошенного(возвращаемого) объекта.

В случае, если API обработала запрос, но запрошенный(возвращаемый) объект не может быть сформирован, возвращается следующий объект:

FormsError

{

   "errors" : [
     {
       "message" : "Неверный номер счета",
       "parameter" : "account",
       "state" : "Invalid",
       "value" : "42301840000000000001"
     }
   ],
   "message" : "Ошибка валидации"
}
Параметр Обязательность Тип Описание
type No String Тип ошибки (если доступно)
errors No FormsErrors Массив элементов информации об ошибке
message Yes String Описание ошибки

Элемент FormsErrors

 {
    "message" : "Неверный номер счета",
    "parameter" : "account",
    "state" : "Invalid",
    "value" : "42301840000000000001"
 }
Параметр Обязательность Тип Описание
message Yes String Текст ошибки
parameter Yes String Параметр, вызвавший ошибку
state No String Состояние параметра
value Yes String Значение параметра, вызвавшее ошибку

CommonError

  {
    "serviceName": "XXX",
    "errorCode": "internal.error",
    "userMessage": "Описание ошибки для отображения клиенту",
    "description": "Описание ошибки",
    "traceId": "1236654998241657",
    "dateTime": "2018-12-06T14:08:46+03:00",
    "cause": {
      "msg1": ["ammount>1500000"]
    }
  }
Параметр Обязательность Тип Описание
serviceName Yes String Идентификатор сервиса породившего ошибку (не анализируется)
errorCode Yes String  
userMessage Yes String Описание ошибки для отображения клиенту
description Yes String Описание ошибки
traceId Yes String Внутренний идентификатор
dateTime Yes Date Дата и время возникновения ошибки
cause No map[String, array[String]] Детали ошибки, если доступно
Если есть несколько деталей, то формируется их массив

Допустимые errorCode

Значение errorCode имеет доменную структуру с разделителем "." (точка) слева направо понижается уровень причины(системы) вызвавшей ошибку

Ошибки уровня авторизации

Ошибки уровня валидации

Ошибки уровня исполнения платежа на стороне получателя

Ошибки уровня проверок финансовых и законодательных рисков

Ошибки общего уровня

API может давать типы ошибок отличные от приведенных.

Тестовая среда


Для вызовов методов данного API в тестовой среде, в зависимости от раздела API и способа авторизации, используются следующие точки доступа:

Раздел API Авторизация Шифрование Точка доступа
{payout.api.url} Токен RSA https://api-test.qiwi.com/partner/payout/v1/
{payout.api.url} Сертификат RSA https://private-api-test.qiwi.com/partner/payout/v1/
{forms.api.url} Токен RSA https://api-test.qiwi.com/partner/sinap/
{forms.api.url} Сертификат RSA https://private-api-test.qiwi.com/partner/sinap/
{payout.api.url} Токен ГОСТ https://api-gost-test.qiwi.com/partner/payout/v1/
{payout.api.url} Сертификат ГОСТ https://private-api-gost-test.qiwi.com/partner/payout/v1/
{forms.api.url} Токен ГОСТ https://api-gost-test.qiwi.com/partner/sinap/
{forms.api.url} Сертификат ГОСТ https://private-api-gost-test.qiwi.com/partner/sinap/