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

Введение


Payout-payment API — это универсальное API выплат в сторону любых получателей платежей (провайдеров). Среди возможных получателей доступны:

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

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

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

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

Пример реализации приема оплаты на кассе контрагента с использованием API.

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

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

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

Действующие сущности:

Цель сценария:

Какое событие запускает сценарий:

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

  1. Кассир находит получателя платежа в системе.

    Используются методы Запрос дерева каталога провайдеров или Запрос списка провайдеров.

  2. Система запрашивает данные для оплаты.

    Используются методы Формы провайдера.

  3. Кассир вводит реквизиты платежа и идентификационные данные, с помощью системы убеждается в полноте и корректности введенных данных и начинает проверку возможности оплаты.
  4. Система передает в API все реквизиты платежа и API подтверждает возможность проведение оплаты.

    Используется метод Создание заявки на платеж.

  5. Кассир сообщает клиенту о возможности проведения платежа и переходит к сценарию Проведение платежа.

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

Проведение платежа

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

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

Действующие сущности:

Цель сценария:

Какое событие запускает сценарий:

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

  1. Кассир принимает денежные средства от Клиента.
  2. Кассир инициирует в Системе процесс оплаты разрешенного в сценарии шага 1 платежа.
  3. Система проводит оплату разрешенного в сценарии шага 1 платежа.

    Используется метод Исполнение заявки на платеж.

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

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

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

Авторизация

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

GET /partner/payout/some/method HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Запросы контрагента при вызовах методов Payout API авторизуются по известному только контрагенту токену.

Токен указывается в HTTP-заголовке Authorization: Bearer. См. [RFC 6749] [RFC 6750]

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

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

GET /partner/sinap/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>
Host: api.qiwi.com

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

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

Версионирование

Версионирование при вызовах методов Payout API

В Payout API поддерживается версионирование методов. URL для вызова метода содержит суффикс, определяющий требуемую версию метода:

http[s]://<хост>[:<порт>][/сервис]/v<версия>/<method>

Поддерживаются две версии Payout API1 и 2. В описании методов явно указываются версии API для использования.

GET /partner/payout/v1/some/method HTTP/1.1
Host: api.qiwi.com

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

API использует REST-архитектуру. В API используются следующие HTTP-методы (HTTP Request):

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

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

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

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

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

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

Точки доступа к API

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


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

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

Производственная среда


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

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

Методы Forms API


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

Запрос

GET /partner/sinap/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>
Host: api.qiwi.com

Применяется для получения формы интерфейса провайдера.

GET {forms.api.url}/providers/{id}/form

Параметры

Имя Положение Описание Обязательность Тип
id path Идентификатор провайдера 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 Объект класса, описывающий условия платежа (комиссии, лимиты на платеж и т.д.)

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект FormsErrors. Подробнее см. раздел Обработка ошибок API.

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

Применяется для получения данных онлайн обработки данных по провайдеру.

POST {forms.api.url}/refs/{id}/containers

Параметры

Запрос

POST /partner/sinap/refs/some-bank/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>
Host: api.qiwi.com

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

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

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

Применение

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

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

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

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

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

Параметр Обязательность Тип Описание
type константа "ref" Тип элемента, требующего онлайн обработку
title string Заголовок поля
message string Сообщение о проверке
id string Идентификатор для запроса
params 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"
      }
    }
  ]
}

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

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект FormsErrors. Подробнее см. раздел Обработка ошибок API.

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

Класс Content

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

Класс Terms

Объект класса описывает условия платежа:

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

Класс SumConstraint

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

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

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

SumConstraint.type = "FixedSumConstraint"

Параметр Обязательность Тип Описание
type String "FixedSumConstraint" — сумма не может быть изменена
sum × Money Сумма к оплате

SumConstraint.type = "EditableSumConstraint"

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

Класс Elements

Массив объектов класса Elements интерфейсной формы. Каждый объект класса содержит параметры. Их набор зависит от обязательного параметра "type" объекта, который может принимать значения:

Elements.type = "field"

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

Elements.type = "dependency"

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

Elements.type = "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 Блок условий проверки.

Класс Condition

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

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

Condition.type = "predicate"

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

Condition.type = "and"

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

Класс Predicate

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

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

Predicate.type = "regex"

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

Predicate.type = "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.type = "info"

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

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

Widget.type = "text"

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

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

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

Widget.type = "date"

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

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

Widget.type = "radio"

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

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

Widget.type = "list"

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

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

Widget.type = "switch"

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

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

Класс Expansion

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

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

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

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


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

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

GET /partner/payout/v1/agents/acme/points/00001/providers/directory/?expand=true HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

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

GET /partner/payout/v1/agents/acme/points/00001/providers/directory/money-transfer?expand=false  HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Возвращает каталог провайдеров.

Поддержка в версиях API: Все версии.

GET {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/providers/directory/{providerCode}

Параметры

Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента string
pointId path Уникальный идентификатор точки приема платежа string
providerCode path Уникальный мнемонический идентификатор провайдера/узла × string
expand query Возвращать только запрошенный {providerCode}, с одним уровнем принадлежащих ему узлов × 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": []
                    }
                ]
            }
        ]
    }

Ответ на запрос дочерних для узла "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": []
       }
   ]
}

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

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

Дополнение

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

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

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

Запрос

GET /partner/payout/v1/agents/acme/points/00001/providers HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Возвращает всех провайдеров в виде плоского списка.

Поддержка в версиях API: Все версии.

GET {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/providers

Параметры

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

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

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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

Запрос

GET /partner/payout/v1/agents/acme/points/00001/providers/qiwi-wallet HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Возвращает расширенную информацию о провайдере.

Поддержка в версиях API: Все версии.

GET {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/providers/{providerCode}

Параметры

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

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

Запрос баланса (версия 1)

Запрос

GET /partner/payout/v1/agents/acme/points/00001/balance HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Возвращает доступный для проведения платежей баланс.

Поддержка в версиях API: версия 1.

GET {payout.api.url}/v1/agents/{agentId}/points/{pointId}/balance

Параметры

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

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

Запрос баланса (версия 2)

Запрос

GET /partner/payout/v2/agents/acme/points/00001/balance HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com

Возвращает доступный для проведения платежей баланс в разрезе валют.

Поддержка в версиях API: версия 2.

GET {payout.api.url}/v2/agents/{agentId}/points/{pointId}/balance

Параметры

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

Ответ

Ответ

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

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

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

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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


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

Регистрация платежа и подготовка его для дальнейшего исполнения.

Поддержка в версиях API: Все версии.

PUT {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/payments/{paymentId}

Параметры

Пример заявки на платеж МТС

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

{
  "recipientDetails": {
    "providerCode": "MTS",
    "fields": {
      "account": "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.589+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
}

Пример заявки на выплату на банковскую карту

{
 "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
       "pan": "123456******4321"
    }
  },
  "amount": {
    "value": "10.00",
    "currency": "RUB"
  },
  "source": {
    "paymentType": "NO_EXTRA_CHARGE",
    "paymentToolType": "BANK_ACCOUNT",
    "paymentTerminalType": "INTERNET_BANKING"
  }
}

Пример заявки на выплату на КИВИ Кошелек

{
  "recipientDetails": {
    "providerCode":"qiwi-wallet",
    "fields": {
      "account":"номер кошелька"
      }
  },
  "amount": {
    "value":"200.00",
    "currency":"RUB"
  },
  "customer": {
    "account":"#12345",
    "email":"usermail@mail.mail",
    "phone":"**********"
  },
  "source": {
    "paymentType":"NO_EXTRA_CHARGE",
    "paymentToolType":"BANK_ACCOUNT",
    "paymentTerminalType":"INTERNET_BANKING"
  }
}
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента string
pointId path Уникальный идентификатор точки приема платежа string
paymentId path Уникальный идентификатор платежа string
body body Объект создания платежа PaymentCreationParams

В теле запроса передается объект PaymentCreationParams, заполненный в ПО контрагента:

Ответ

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

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:02:35.646+03:00",
  "expirationDatetime": "2018-11-27T14:02:35.646+03:00",
  "status": {
    "value": "READY",
    "changedDateTime": "2018-11-27T14:02:35.646+03:00",
    "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-27T14:02:35.646+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Иванов",
    "something": "Что-то нужное контрагенту",
    "something-other": "Еще что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE",
  "billingDetails": {
    "transactionId":"1000200300",
  }
}

Успешный ответ в формате объекта PaymentInfo.

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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

Исполнение ранее подготовленного и зарегистрированного платежа.

Поддержка в версиях API: Все версии.

POST {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/payments/{paymentId}/execute

Параметры

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

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

Ответ

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

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:06:17.108+03:00",
  "expirationDatetime": "2018-11-27T14:06:17.108+03:00",
  "status": {
    "value": "IN_PROGRESS",
    "changedDateTime": "2018-11-27T14:06:17.108+03:00",
    "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.109+03:00",
    "extraCharge": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Иванов",
    "something": "Что-то нужное контрагенту",
    "something-other": "Еще что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "NONE"
  "billingDetails": {
    "transactionId":"1000200300",
    "rrn": "abcDE123"
  }
}

Успешный ответ в формате объекта PaymentInfo.

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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

Дополнение заявки на платеж недостающими для ее исполнения данными.

Поддержка в версиях API: Все версии.

PATCH {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/payments/{paymentId}

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

Параметры

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

PATCH /partner/payout/v1/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>
Host: api.qiwi.com

[
    {
        "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 /partner/payout/v1/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>
Host: api.qiwi.com

[
  {"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/citizenship", "value": "SU"},
  {"op": "add", "path": "/identification/person/contact/phone", "value": "+79261231212"},
  {"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 Уникальный идентификатор агента string
pointId path Уникальный идентификатор точки приема платежа string
paymentId path Уникальный идентификатор платежа string
body body Дополняемые данные согласно [RFC 6902]  

Ответ

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

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:07:05.652+03:00",
  "expirationDatetime": "2018-11-27T14:07:05.652+03:00",
  "status": {
    "value": "READY",
    "changedDateTime": "2018-11-27T14:07:05.652+03:00",
    "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.652+03:00",
    "extraCharge": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Иванов",
    "something": "Что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "IdentificationType": "SIMPLIFIED"
}

Успешный ответ в формате объекта PaymentInfo.

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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

Возвращает информацию о всех платежах за текущую дату.

Поддержка в версиях API: Все версии.

GET {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/payments

Параметры

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

GET /partner/payout/v1/agents/acme/points/00001/payments HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-String>
Host: api.qiwi.com
Параметр Положение Описание Обязательность Тип
agentId path Уникальный идентификатор агента string
pointId path Уникальный идентификатор точки приема платежа string
limit query Limit number of payments returned by request × integer
offset query The number of payments to skip × integer
from query Only payments created after this date will be returned × string
to query Only payments created before this date will be returned × string

Ответ

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

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

[
  {
    "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
    "creationDateTime": "2018-11-27T13:44:34.034+03:00",
    "expirationDatetime": "2018-11-27T13:44:34.034+03:00",
    "status": {
      "value": "COMPLETED",
      "changedDateTime": "2018-11-27T13:44:34.034+03:00",
      "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.034+03:00",
      "extraCharge": {
        "value": "2.00",
        "currency": "RUB"
      }
    },
    "customFields": {
      "cashier": "Иванов",
      "something": "Что-то нужное контрагенту",
      "something-one": "Еще что-то нужное контрагенту"
    },
    "callbackUrl": "https://domain/path",
    "identificationType": "NONE"
  }
]

Успешный ответ в формате массива объектов PaymentInfo.

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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

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

Поддержка в версиях API: Все версии.

GET {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/payments/{paymentId}

Параметры

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

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

Ответ

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

{
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "creationDateTime": "2018-11-27T14:00:56.973+03:00",
  "expirationDatetime": "2018-11-27T14:00:56.973+03:00",
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2018-11-27T14:00:56.973+03:00",
  },
  "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.973+03:00",
    "extraCharge": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  "customFields": {
    "cashier": "Иванов",
    "something": "Что-то нужное контрагенту",
    "something-one": "Еще что-то нужное контрагенту"
  },
  "callbackUrl": "https://domain/path",
  "identificationType": "NONE"
}

Успешный ответ в формате объекта PaymentInfo.

Ответ с HTTP-кодом ошибки (4xx, 5xx) содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

Одобрение клиентом заявки на платеж

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

Поддержка в версиях API: Все версии.

POST {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/payments/{paymentId}/client-approve

Параметры

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

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

Запрос используется когда в объекте PaymentStatus значение параметра clientApproveRequired присутствует и равно true.

Ответ

Успешный ответ в формате объекта PaymentInfo.

Если платеж не найден или не требует одобрения, ответ содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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

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

Поддержка в версиях API: Все версии.

POST {payout.api.url}/v{версия}/agents/{agentId}/points/{pointId}/payments/{paymentId}/fraud-approve

Параметры

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

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

Запрос используется когда в объекте PaymentStatus значение параметра fraudApproveRequired присутствует и равно true.

Ответ

Успешный ответ в формате объекта PaymentInfo.

Если платеж не найден или не требует одобрения, ответ содержит объект CommonError. Подробнее см. раздел Обработка ошибок API.

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

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

POST {callbackUrl}

Параметры

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

POST /path/webhook HTTP/1.1
Content-Type: application/json
QIWI-Signature: 2cc6b2e0cd00f701d9d5510a6e5d4a6a67f9e5a61d7f8e4a203d3ae81b9­ae2b
Host: example.com

{
  "agentId": "acme",
  "pointId": "00001",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
      "value": "COMPLETED",
      "changedDateTime": "2018-11-27T13:44:34.034+03:00",
      "identificationType": "NONE"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId":"1000200300",
  }
}
Параметр Положение Описание Обязательность Тип
QIWI-Signature header Подпись запроса. Для проверки сформируйте строку по шаблону: {agentId}|{pointId}|{paymentId}|{status.value}|{amount.value}|{amount.currency} где {param} обозначает значение соответствующего параметра path в JSON-теле уведомления, | обозначает символ |. Далее вычислите HMAC с SHA256 хэш-функцией от сформированной строки и вашего секретного ключа как ключа шифрования. string
body body Описание результата платежа WebhookPaymentInfo

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

Ответ

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

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

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

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


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

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

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

Уровень идентификации определяет перечень полей, необходимый для предоставления в платеже. Поля описываются в классах 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.589+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "",
  "identification": {  <= сведения об идентификации плательщика
    "type": "SIMPLIFIED",
    "person": {
      "fullName": {
        "firstName": "Михаил",
        "lastName": "Олимпийский",
        "middleName": "Потапович"
      },
      "birthDate": "1977-12-19",
      "citizenship": "SU",
      "contact": {
        "phone": "+79123456789"
      }
    },
    "document": {
      "type": "PASSPORT_SIMPLIFIED",
      "serial": "XXII",
      "number": "030880",
      "issueDate": "2012-01-01"
    }
  }
}

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

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

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

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

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

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

Для исполнения платежа уровень предоставленной идентификации должен быть равен или выше уровня требуемой.

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

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

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

GET /partner/sinap/providers/identification-full/form HTTP/1.1
Accept: application/json
X-Application-Id: <X-Application-Id-String>
X-Application-Secret: <X-Application-Secret-String>
Host: api.qiwi.com

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

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

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

По результатам обработки формы получается набор полей и значений.

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

Используйте эти данные для создания объекта класса Identification при предоставлении идентификации.

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


Класс BalanceInfo

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

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

Класс BillingDetails

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

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

Класс Customer

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

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

Класс Document

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

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

Класс DocumentSimplified

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

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

Класс ForeignPassport

Описание паспорта иностранного гражданина.

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

Класс Identification

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

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

Класс IdentificationFull

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

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

Класс IdentificationSimple

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

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

Класс IdentificationType

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

Параметр Обязательность Тип Описание
значение 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 × String Минимальная граница денежной суммы (включительно)
max × String Максимальная граница денежной суммы (включительно)
identificationType × IdentificationType Уровень идентификации, распространяющийся на указанный диапазон денежной суммы

Класс MigrationCard

Описание миграционной карты.

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

Класс Parameter

  "parameter": {
    "extKey": "account",
    "required": true,
    "description": "Qiwi Wallet User Account"
  }
Параметр Обязательность Тип Описание
extKey String Код параметра
required String Признак обязательности (да / нет)
description String Описание параметра
validationPattern × String Шаблон заполнения

Класс Passport

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

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

Класс PassportSimplified

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

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

Класс 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.589+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "https://domain/path",
  "identification": {},
  "pointInfo": {
    "deviceIp": "255.255.255.255",
    "clientSoftware": "API Client v1",
    "clientDateTime": "2020-02-17T09:01:39+03:00",
    "employeeId": "emp_0001",
    "deviceId": "device_0001"
  }
}
Параметр Обязательность Тип Описание
recipientDetails RecipientDetails Объект, описывающий получателя платежа
amount Money Объект, описывающий сумму платежа
customer × Customer Объект, описывающий плательщика
source × Source Объект, описывающий инструмент платежа
customFields × map[String, String] Перечень дополнительных данных, которыми можно сопроводить платеж
callbackUrl × String Адрес вызова для метода Уведомление
identification × Identification Идентификационные данные, описывающие плательщика согласно законодательству РФ
pointInfo × PointInfo Объект, описывающий данные точки, с которой совершается платеж

Класс PaymentInfo

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

{
  "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.589+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "https://domain/path",
  "identificationType": "NONE",
  "pointInfo": {
    "deviceIp": "255.255.255.255",
    "clientSoftware": "API Client v1",
    "clientDateTime": "2020-02-17T09:01:39+03:00",
    "employeeId": "emp_0001",
    "deviceId": "device_0001"
  }
}
Параметр Обязательность Тип Описание
paymentId String Уникальный идентификатор платежа
creationDateTime Date Дата создания платежа
expirationDatetime Date Дата окончания жизни платежа
status PaymentStatus  
recipientDetails RecipientDetails Объект, описывающий получателя платежа
amount Money Объект, описывающий сумму платежа
commission × Money  
customer × Customer Объект, описывающий плательщика
source × Source  
customFields × map[String, String] Перечень дополнительных данных, которыми был сопровожден платеж
callbackUrl × String Адрес вызова для метода Уведомление
identificationType × IdentificationType Предоставленная идентификация
billingDetails × BillingDetails Дополнительная информация со стороны получателя (провайдера)
pointInfo × PointInfo Объект, описывающий данные точки, с которой совершается платеж

Класс PaymentStatus

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

"status": {
  "value": "IN_PROGRESS",
  "changedDateTime": "2018-11-27T14:06:17.108+03:00"
  }

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

"status": {
  "value": "FAILED",
  "changedDateTime": "2018-11-27T14:06:17.108+03:00",
  "errorCode": "BILLING_DECLINED",
  "errorMessage": "Параметр платежа указан неверно."
    }
Параметр Обяз. Тип Описание
value String Статус.
Enum
"CREATED" создан, но не готов к оплате
"READY" создан и готов к оплате
"FAILED" неуспешен
"IN_PROGRESS" в процессе исполнения
"COMPLETED" исполнен
"EXPIRED" просрочен
changedDateTime Date Дата последнего изменения объекта платежа
errorCode × String Код ошибки.
Enum
"INTERNAL_ERROR" ошибка без объяснения
"POINT_LIMIT_EXCEED" превышены лимиты по агенту/точке
"INSUFFICIENT_FUNDS" платеж на указанный размер платежа или валюту запрещен
"IDENTIFICATION_FAILED" идентификация плательщика не пройдена
"BILLING_DECLINED" платеж отклонен биллингом получателя
errorMessage × String Детальная расшифровка errorCode
identificationTypeRequired × IdentificationType Требуемый для платежа уровень идентификации
fraudApproveRequired × boolean По умолчанию false. При значении true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж успешно исполнен. Фактическое неисполнение платежа кассиру и клиенту не раскрывается (платеж приостанавливается)
clientApproveRequired × boolean По умолчанию false. При значении true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж имеет потенциально подозрительную окраску. Клиент может отказаться от проведения платежа или подтвердить его исполнение

Класс PersonContacts

Контактные данные плательщика.

{
  "phone": "79123456789"
}
Параметр Обязательность Тип Описание
phone String Номер телефона

Класс Person

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

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

Класс PersonFullName

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

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

Класс PersonSimplified

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

Параметр Обязательность Тип Описание
fullName PersonFullName  
birthDate String Дата рождения
citizenship String Гражданство
contact × PersonContacts Контактные данные плательщика

Класс PointInfo

Объект, описывающий данные точки, с которой был совершен платеж.

{
  "deviceIp": "255.255.255.255",
  "clientSoftware": "API Client v1",
  "clientDateTime": "2020-02-17T09:01:39+03:00",
  "employeeId": "emp_0001",
  "deviceId": "device_0001"
}
Параметр Обязательность Тип Описание
deviceIp × String IP-адрес устройства, с которого выполняется платеж
clientSoftware × String Название и версия ПО, с которого инициируется платеж
clientDateTime × Date Время на ПО, с которого инициируется платеж
employeeId × String Идентификатор сотрудника, инициирующего платеж
deviceId × String Идентификатор устройства, инициирующего платеж и находящегося в точке pointId

Класс Provider

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

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

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

Класс ProviderBrief

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

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

Параметр Обязательность Тип Описание
providerCode string Уникальный мнемонический идентификатор провайдера
name string Наименование провайдера
form 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"
      }
    ]
  },
  "parameters": [
    {
      "extKey": "account",
      "required": true,
      "description": "Qiwi Wallet User Account"
    }
  ]
}

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

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

Класс RecipientDetails

{
  "providerCode": "qiwi-wallet",
  "fields": {
    "account": "79123456789"
  }
}
Параметр Обязательность Тип Описание
providerCode String Код получателя
Enum
bank-card-russia Выплаты на карты (Россия) Выплаты на карты по токену
self-employed-bank-card Выплаты на карты самозанятым
self-employed-card-token Выплаты на карты самозанятым по токену
self-employed-bank-card-tax-payment Выплаты на карты самозанятым с уплатой налога
qiwi-wallet Выплаты на QIWI Кошелёк
wl-topup Пополнение счета клиента продукта White Label
bank-card-ruslom Выплаты на банковские карты за металлолом
bank-card-ruslom-qmm Выплаты на банковские карты QIWI Mir Metal за металлолом
sbp-b2c Выплаты на СБП
sbp-mfo Выплаты на СБП с проверкой ФИО для МФО
fields map[String, String] Параметры платежа (набор параметров зависит от кода получателя)

Описание платежных провайдеров

Выплаты на банковские карты (Россия) "providerCode": "bank-card-russia"

Блок recipientDetails для выплаты на банковскую карту

{
  "providerCode": "bank-card-russia",
  "fields": {
    "pan": "1234564543654321"
  }
}
Параметр Описание Обязательность Тип
pan Номер карты получателя string
cardholder_name Имя получателя × string
cardholder_lastname Фамилия получателя × string
description Описание оказанной услуги × string

Выплаты на банковские карты по токену "providerCode": "bank-card-token"

Блок recipientDetails для выплаты на банковскую карту по токену

{
  "providerCode": "bank-card-token",
  "fields": {
    "account": "8198425371822184"
  }
}
Параметр Описание Обязательность Тип
account Токен номера карты string
cardholder_name Имя получателя × string
cardholder_lastname Фамилия получателя × string
description Описание оказанной услуги × string

Выплаты на банковские карты самозанятым "providerCode": "self-employed-bank-card"

Блок recipientDetails для выплаты на банковскую карту самозанятого

{
  "providerCode": "self-employed-bank-card",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}
Параметр Описание Обязательность Тип
account Номер карты получателя string
description Описание оказанной услуги string
inn ИНН самозанятого string
incomeType Источник дохода string
name Имя получателя × string
lastname Фамилия получателя × string
customerInn ИНН организации, оплачивающей услугу × string
customerOrganization Наименование организации, оплачивающей услугу × string

Выплаты на банковские карты самозанятым по токену providerCode: "self-employed-card-token"

Блок recipientDetails для выплаты на банковскую карту самозанятого по токену

{
  "providerCode": "self-employed-card-token",
  "fields": {
    "inn": "111111111111",
    "account": "Токен номера карты",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}
Параметр Описание Обязательность Тип
account Токен номера карты string
description Описание оказанной услуги string
inn ИНН самозанятого string
incomeType Источник дохода string
name Имя получателя × string
lastname Фамилия получателя × string
customerInn ИНН организации, оплачивающей услугу × string
customerOrganization Наименование организации, оплачивающей услугу × string

Выплаты на банковские карты самозанятым с уплатой налога providerCode: "self-employed-bank-card-tax-payment"

Блок recipientDetails для выплаты на банковскую карту самозанятого с уплатой налога

{
  "providerCode": "self-employed-bank-card-tax-payment",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}
Параметр Описание Обязательность Тип
account Номер карты получателя string
description Описание оказанной услуги string
inn ИНН самозанятого string
incomeType Источник дохода string
name Имя получателя × string
lastname Фамилия получателя × string
customerInn ИНН организации, оплачивающей услугу × string
customerOrganization Наименование организации, оплачивающей услугу × string

Выплаты на QIWI Кошелёк providerCode: "qiwi-wallet"

Блок recipientDetails для выплаты на QIWI Кошелёк

{
  "providerCode": "qiwi-wallet",
  "fields": {
    "account": "79123456789"
  }
}
Параметр Описание Обязательность Тип
account Номер телефона string

Пополнение баланса White Label providerCode: "wl-topup"

Блок recipientDetails для пополнения счета клиента White Label

{
  "providerCode": "wl-topup",
  "fields": {
    "account": "21646",
    "product_id": "company-id"
  }
}
Параметр Описание Обязательность Тип
account Идентификатор клиента в WL string
product_id Идентификатор продукта в WL string

Выплаты на банковскую карту за металлолом "providerCode": "bank-card-ruslom"

Блок recipientDetails для выплаты на банковскую карту за металлолом

{
  "providerCode": "bank-card-ruslom",
  "fields": {
      "pan": "1234564543654321",
      "lastname": "Фамилия получателя",
      "name": "Имя получателя",
      "patronymic": "Отчество получателя",
      "acceptanceCertificate": "Номер приемо-сдаточного акта"
  }
}
Параметр Описание Обязательность Тип
pan Номер карты получателя string
lastname Фамилия получателя string
name Имя получателя string
patronymic Отчество получателя × string
acceptanceCertificate Номер приемо-сдаточного акта string

Выплаты на банковскую карту Qiwi Mir Metal за металлолом "providerCode": "bank-card-ruslom-qmm"

Блок recipientDetails для выплаты на банковскую карту Qiwi Mir Metal за металлолом

{
  "providerCode": "bank-card-ruslom-qmm",
  "fields": {
      "pan": "1234564543654321",
      "lastname": "Фамилия получателя",
      "name": "Имя получателя",
      "patronymic": "Отчество получателя",
      "acceptanceCertificate": "Номер приемо-сдаточного акта"
  }
}
Параметр Описание Обязательность Тип
pan Номер карты получателя (только карты Qiwi Mir Metal) string
lastname Фамилия получателя string
name Имя получателя string
patronymic Отчество получателя × string
acceptanceCertificate Номер приемо-сдаточного акта string

Выплаты на СБП "providerCode": "sbp-b2c"

Блок recipientDetails для выплаты на счет клиента СБП

{
  "providerCode": "sbp-b2c",
  "fields": {
    "account": "79098087755",
    "bankId": "100000000001"
  }
}
Параметр Описание Обязательность Тип
account Идентификатор получателя (номер телефона в международном формате без знака +) string
bankId Идентификатор банка получателя в СБП. См. список банков, доступных для выплаты на СБП, в формате xlsx (скачать) или csv (скачать) string

Выплаты на СБП c проверкой ФИО (для МФО) "providerCode": "sbp-mfo"

Блок recipientDetails для выплаты на счет клиента СБП с проверкой ФИО (для МФО)

{
  "providerCode": "sbp-mfo",
  "fields": {
    "phone": "79098087755",
    "bankId": "100000000001",
    "lastName": "Иванов",
    "firstName": "Иван",
    "middleName": "Иванович"
  }
}
Параметр Описание Обязательность Тип
phone Идентификатор получателя (номер телефона в международном формате без знака +) string
bankId Идентификатор банка получателя в СБП. См. список банков, доступных для выплаты на СБП, в формате xlsx (скачать) или csv (скачать) string
lastName Фамилия получателя string
firstName Имя получателя string
middleName Отчество получателя (если есть) × string

Класс RefugeeCertificate

Описание удостоверения беженца.

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

Класс ResidencePermit

Описание вида на жительство.

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

Класс Source

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

{
  "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"
}
Параметр Обязательность Тип Описание
paymentType String Enum:
"NO_EXTRA_CHARGE" без комиссий взятой сверх платежа
"WITH_EXTRA_CHARGE" с комиссией сверх платежа
paymentToolType String Enum:
"CASH" наличные
"BANK_ACCOUNT" банковский счет
"BANK_CARD" банковская карта
"BANK_CARD_OWN" банковская карта эмитированная данным банком
"ELECTRONIC_FUNDS" электронные денежные средства
paymentTerminalType 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 × Date  
extraCharge × Money Комиссия взятая сверх платежа, если "paymentType": "WITH_EXTRA_CHARGE"
chargeOffCurrency × String Валюта счета списания, обозначает валюту счета, с которого необходимо списывать денежные средства у агента

Класс Visa

Описание визы на пребывание в РФ.

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

Класс WebhookPaymentInfo

{
  "agentId": "acme",
  "pointId": "00001",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
      "value": "COMPLETED",
      "changedDateTime": "2018-11-27T13:44:34.034+03:00",
      "identificationType": "NONE"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId":"1000200300",
  }
}
Параметр Обязательность Тип Описание
agentId String Уникальный идентификатор агента
pointId String Уникальный идентификатор точки приема платежа
paymentId String Уникальный идентификатор платежа
status PaymentStatus  
amount Money  
billingDetails × BillingDetails Дополнительная информация со стороны получателя (провайдера)

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


Класс Money

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

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

Класс AmountLimit

Ограничения на сумму платежа в указанной валюте.

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

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

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

Класс Limit

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

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

Класс Contact

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

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

Параметр Обязательность Тип Описание
address × string Почтовый адрес
phoneNumber × 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".

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


Коды ответов

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

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

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

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

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

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

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

В протоколе применяются следующие HTTP-коды:

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

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

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

В случае ошибок из перечня 5xx возможен неформатный ответ.

При получении ошибки из перечня 5xx в результате обработки платежных запросов, особенно запроса Исполнение платежа, уточняйте результат обработки методом Статус платежа.

FormsError

{

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

Элемент FormsErrors

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

CommonError

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

Допустимые errorCode

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

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

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

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

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

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