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

Общие сведения

Payout 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

sequenceDiagram participant agent as Агент participant forms as Forms API participant payouts as Payout API Note over agent,payouts: Подготовка к платежу agent->>payouts: Запрос доступных провайдеров activate payouts payouts-->>agent: Список доступных провайдеров deactivate payouts agent->>forms: Запрос форм провайдера activate forms forms-->>agent: Информация о форме deactivate forms Note over agent,payouts: Регистрация платежа agent->>payouts: Создание заявки на платёж activate payouts alt Валидация не пройдена payouts-->>agent: Платёж невозможен else Валидация пройдена payouts-->>agent: Платёж зарегистрирован deactivate payouts end Note over agent,payouts: Платёж agent->>payouts: Исполнение платежа activate payouts payouts-->>agent: Результат проведения платежа deactivate payouts opt Уведомление о платеже payouts->>agent: Уведомление о результатах платежа activate agent agent-->>payouts: Результат обработки уведомления deactivate agent end

Вариант реализации методов 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 API — 1 и 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

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

GET {payout.api.url}/v1/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

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

GET {payout.api.url}/v1/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

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

GET {payout.api.url}/v1/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"
    }
  }
}

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

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

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

Запрос

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

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

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.

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

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

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

PUT {payout.api.url}/v1/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"
  },
  "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.

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

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

POST {payout.api.url}/v1/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"
  },
  "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.

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

Возвращает список последних платежей. Без указания фильтров from и to поиск платежей осуществляется за последние 50 дней.

GET {payout.api.url}/v1/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 Ограничение на число платежей, возвращаемое в ответе, по умолчанию 20 integer
offset query Число платежей, которое надо пропустить, по умолчанию 0 integer
from query Дата начала интервала поиска в формате YYYY-MM-DD string
to query Дата конца интервала поиска в формате YYYY-MM-DD 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"
    },
    "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"
  }
]

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

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

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

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

GET {payout.api.url}/v1/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"
}

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

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

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

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

POST {payout.api.url}/v1/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.

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

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

POST {payout.api.url}/v1/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"      
  },
  "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 рассматривается как ошибка. Система продолжит повторять уведомление

Модели данных 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 Телефон плательщика

Класс Parameter

  "parameter": {
    "extKey": "account",
    "required": true,
    "description": "Qiwi Wallet User Account"
  }
Параметр Тип Описание
extKey String Обязательный параметр. Код параметра
required String Обязательный параметр. Признак обязательности (да / нет)
description String Обязательный параметр. Описание параметра
validationPattern 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.589+03:00",
    "extraCharge": {
      "value": "200.00",
      "currency": "RUB"
    }
  },
  "callbackUrl": "https://domain/path",
  "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 Адрес вызова для метода Уведомление
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",
  "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 Адрес вызова для метода Уведомление
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" платеж на указанный размер платежа или валюту запрещен
"BILLING_DECLINED" платеж отклонен биллингом получателя
errorMessage String Детальная расшифровка errorCode
fraudApproveRequired boolean По умолчанию false. При значении true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж успешно исполнен. Фактическое неисполнение платежа кассиру и клиенту не раскрывается (платеж приостанавливается)
clientApproveRequired boolean По умолчанию false. При значении true клиенту (физическому лицу) и кассиру должно быть сообщено о том, что платеж имеет потенциально подозрительную окраску. Клиент может отказаться от проведения платежа или подтвердить его исполнение

Класс 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 Выплаты на карты (Россия)
bank-card-token Выплаты на карты по токену
self-employed-bank-card Выплаты на карты самозанятым
self-employed-card-token Выплаты на карты самозанятым по токену
self-employed-bank-card-tax-payment Выплаты на карты самозанятым с уплатой налога
self-employed-bank-card-qmm Выплаты на карты QIWI Mir Metal самозанятым
self-employed-sbp Выплаты по СБП самозанятым с регистрацией налога
qiwi-wallet Выплаты на QIWI Кошелёк
wl-topup Пополнение счета клиента продукта White Label
bank-card-ruslom Выплаты на банковские карты за металлолом
bank-card-ruslom-qmm Выплаты на банковские карты QIWI Mir Metal за металлолом
sbp-b2c Выплаты на СБП
sbp-mfo Выплаты на СБП с проверкой ФИО для МФО
sbp-recycling Выплаты на СБП по вторсырью
legal-entity-bank-account Выплаты на банковские счета юридических лиц
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 Наименование организации, оплачивающей услугу

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

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

{
  "providerCode": "self-employed-bank-card-recycling",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "firstName": "Имя получателя",
    "lastName": "Фамилия получателя",
    "middleName": "Отчество получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}
Параметр Тип Описание
account string Обязательный параметр. Номер карты получателя
description string Обязательный параметр. Номер приёмо-сдаточного акта или иное описание выплаты за услугу
inn string Обязательный параметр. ИНН самозанятого
incomeType enum Обязательный параметр. Источник дохода (FROM_LEGAL_ENTITY – юридическое лицо, FROM_INDIVIDUAL – физическое лицо)
firstName string Обязательный параметр. Имя получателя
lastName string Обязательный параметр. Фамилия получателя
middleName string Отчество получателя
customerInn string ИНН организации, оплачивающей услугу
customerOrganization string Наименование организации, оплачивающей услугу

Выплаты на карты QIWI Mir Metal самозанятым "providerCode": "self-employed-bank-card-qmm"

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

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

Выплаты по СБП самозанятым с регистрацией налога providerCode: "self-employed-sbp"

Блок recipientDetails для выплаты по СБП самозанятым с регистрацией налога

{
  "providerCode": "self-employed-sbp",
  "fields": {
    "inn": "111111111111",
    "account": "79098087755",
    "bankId": "100000000001",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}
Параметр Тип Описание
account string Обязательный параметр. Идентификатор получателя (номер телефона в международном формате без знака +)
bankId string Обязательный параметр. Идентификатор банка получателя в СБП. См. список банков, доступных для выплаты на СБП, в формате xlsx (скачать) или csv (скачать
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",
    "comment": "Комментарий"
  }
}
Параметр Тип Описание
account string Обязательный параметр. Номер телефона
comment string Комментарий

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

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

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

Выплаты на банковскую карту за металлолом "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 string Обязательный параметр. Номер карты получателя (только карты Qiwi Mir Metal)
lastname string Обязательный параметр. Фамилия получателя
name string Обязательный параметр. Имя получателя
patronymic string Отчество получателя
acceptanceCertificate string Обязательный параметр. Номер приемо-сдаточного акта

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

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

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

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

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

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

Выплаты на СБП по вторсырью "providerCode": "sbp-recycling"

Блок recipientDetails для выплаты на счет клиента СБП за вторсырье с обязательным указанием основания выплаты

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

Блок recipientDetails для выплаты на счет юридического лица

{
  "providerCode": "legal-entity-bank-account",
  "fields": {
    "account": "50537928100000002463",
    "bik": "304754657",
    "inn": "1111111111",
    "kpp": "389244830",
    "name": "Qiwi АО",
    "remarks": "Платежное получение №454"
  }
}
Parameter Type Description
account String Required. Номер счета получателя
bik String Required. БИК банка получателя
inn String Required. ИНН получателя
name String Required. Наименование организации получателя
remarks String Required. Назначение платежа
kpp String КПП получателя (для обществ с ограниченной ответственностью)

Класс 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 Валюта счета списания, обозначает валюту счета, с которого необходимо списывать денежные средства у агента

Класс WebhookPaymentInfo

{
  "agentId": "acme",
  "pointId": "00001",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
      "value": "COMPLETED",
      "changedDateTime": "2018-11-27T13:44:34.034+03:00"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId":"1000200300",
  }
}
Параметр Тип Описание
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 имеет доменную структуру с разделителем . (точка). Слева направо понижается уровень причины (системы), вызвавшей ошибку.

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

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

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

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

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

Примеры