Вопросы
bss@qiwi.com
NAV Navbar
http bash

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

Payout API — это универсальное API для выплат денежных средств от юридических лиц. Среди возможных инструментов выплат доступны:

Обзор API

Выплатное API построено на архитектуре REST, где данные и функциональные возможности считаются ресурсами, доступ к которым осуществляется с помощью универсальных идентификаторов ресурсов (URI).

Ресурсы обрабатываются с помощью набора простых, четко определенных операций. Клиенты и серверы обмениваются представлениями ресурсов, используя стандартизированный интерфейс и HTTP протокол.

Используемые HTTP методы

Формат данных

Ресурсы представляются в виде JSON объектов, при создании которых (HTTP метод PUT) необходимо указывать Content-Type: application/json в заголовках запроса.

Способы передачи данных

Идемпотентность

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

Авторизация

В рамках технического взаимодействия доступно два вида авторизации:

Авторизация с помощью Bearer токена

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/providers

При данном типе авторизации все запросы партнера, при вызовах методов, авторизуются по известному только партнеру значению Bearer токена.

Токен указывается в HTTP-заголовке Authorization с префиксом Bearer, согласно спецификации RFC 6750. Например: Authorization: Bearer <Token-Value>.

Авторизация с использованием клиентского сертификата

GET /partner/payout/v2/agents/acme HTTP/1.1
Accept: application/json
Host: private-api.qiwi.com

curl -X GET \
     --key private.key \
     --cert certificate.crt \
     --cacert ca.pem \
     https://private-api.qiwi.com/partner/payout/v2/agents/acme/providers

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

В этом случае на стороне клиента заголовок Authorization не формируется и запрос сопровождается цифровым сертификатом формата X.509 v3, согласно спецификации RFC 5280.

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

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

https://api.qiwi.com/partner/payout/v<version>/<method>

На текущий момент поддерживается две версии API Payout — 1 и 2. Актуальной текущей редакцией протокола выплат является 2 версия. В описании методов явно указываются версии API для использования.

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

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

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

Шифрование Авторизация Точка доступа
RSA Токен https://api-test.qiwi.com/
RSA Сертификат https://private-api-test.qiwi.com/
ГОСТ Токен https://api-gost-test.qiwi.com/
ГОСТ Сертификат https://private-api-gost-test.qiwi.com/

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

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

Шифрование Авторизация Точка доступа
RSA Токен https://api.qiwi.com/
RSA Сертификат https://private-api.qiwi.com/
ГОСТ Токен https://api-gost.qiwi.com/
ГОСТ Сертификат https://private-api-gost.qiwi.com/

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

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

Баланс основного счета

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/balance

Используется для получения текущего баланса основного счета.

   
HTTP метод: GET
URI ресурса: /partner/payout/v2/agents/{agentId}/balance

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента

Ответ

Ответ

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

{
  "balance": {
    "currency": "RUB",
    "value": "1000000.00"
  },
  "overdraft": {
    "currency": "RUB",
    "value": "500000.00"
  },
  "available": {
    "currency": "RUB",
    "value": "1500000.00"
  }
}

Успешный ответ содержит текущий баланс основного счета в виде объекта Balance.

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

Баланс всех счетов

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/balances

Используется для получения текущих балансов всех счетов.

   
HTTP метод: GET
URI ресурса: /partner/payout/v2/agents/{agentId}/balances

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента

Ответ

Ответ

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

{
  "RUB": {
    "balance": {
      "currency": "RUB",
      "value": "1000000.00"
    },
    "available": {
      "currency": "RUB",
      "value": "1000000.00"
    }
  }
}

Успешный ответ содержит набор балансов всех счетов в виде отношения Currency и Balance.

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

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

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/providers

Используется для получения списка доступных провайдеров для выплат.

   
HTTP метод: GET
URI ресурса: /partner/payout/v2/agents/{agentId}/providers

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента

Ответ

Ответ

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

[
  {
    "providerCode": "bank-card-russia",
    "name": "Банковские карты РФ"
  },
  {
    "providerCode": "qiwi-wallet",
    "name": "Qiwi кошелек"
  }
]

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

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

Информация о провайдере

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/providers/qiwi-wallet

Используется для получения расширенной информации о провайдере.

   
HTTP метод: GET
URI ресурса: /partner/payout/v2/agents/{agentId}/providers/{providerCode}

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента
providerCode path ✓ ProviderCode Уникальный идентификатор провайдера

Ответ

Ответ

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

{
  "name": "Qiwi Wallet",
  "legalName": "Qiwi Bank JSC",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "account",
      "required": true,
      "description": "QW user's account",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "3123011520",
  "contactDetails": {
    "address": "Russia, 117648, Moscow, md. Chertanovo Severnoe, 1A, bldg. 1",
    "phoneNumber": "8-800-707-77-59"
  }
}

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

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

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

Методы для работы с платежами, в том числе создание, проведение и получение информации о платеже.

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

PUT /partner/payout/v2/agents/acme/payments/0123456789 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <Token-Value>
Host: api.qiwi.com

{
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789 \
     -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "recipientDetails": {
              "providerCode": "qiwi-wallet",
              "fields": {
                "account": "79010001122"
              }
            },
            "webhookUrl": "https://acme.inc/webhook",
            "customFields": {
              "user": "Wile E. Coyote"
            }
        }'

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

   
HTTP метод: PUT
URI ресурса: /partner/payout/v2/agents/{agentId}/payments/{paymentId}

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента
paymentId path ✓ string Уникальный идентификатор платежа от 1 до 36 символов
payload body ✓ PaymentPayload Параметры создаваемого платежа

Ответ

Ответ

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

{
  "paymentId": "0123456789",
  "creationDateTime": "2023-01-17T15:05:51+03:00",
  "expirationDateTime": "2023-01-17T15:35:51+03:00",
  "status": {
    "value": "READY",
    "changedDateTime": "2023-01-17T15:05:51+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "2.00"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.04"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

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

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

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

POST /partner/payout/v2/agents/acme/payments/0123456789/execute HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: api.qiwi.com

curl -X POST \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789/execute

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

   
HTTP метод: POST
URI ресурса: /partner/payout/v2/agents/{agentId}/payments/{paymentId}/execute

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента
paymentId path ✓ string Уникальный идентификатор платежа от 1 до 36 символов

Ответ

Ответ

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

{
  "paymentId": "0123456789",
  "creationDateTime": "2023-01-17T15:05:51+03:00",
  "expirationDateTime": "2023-01-17T15:35:51+03:00",
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2023-01-17T15:06:00+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "2.00"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.04"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

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

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

Список платежей

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/payments

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

   
HTTP метод: GET
URI ресурса: /partner/payout/v2/agents/{agentId}/payments

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента
limit query × integer Ограничение на число платежей, возвращаемое в ответе, по умолчанию 20
offset query × integer Число платежей, которое надо пропустить, по умолчанию 0
from query × date Дата начала интервала поиска в формате YYYY-MM-DD
to query × date Дата конца интервала поиска в формате YYYY-MM-DD

Ответ

Ответ

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

[
  {
    "paymentId": "0123456789-01",
    "creationDateTime": "2023-01-17T15:05:51+03:00",
    "expirationDateTime": "2023-01-17T15:35:51+03:00",
    "status": {
      "value": "COMPLETED",
      "changedDateTime": "2023-01-17T15:06:00+03:00"
    },
    "amount": {
      "currency": "RUB",
      "value": "2.00"
    },
    "recipientDetails": {
      "providerCode": "qiwi-wallet",
      "fields": {
        "account": "79010001122"
      }
    },
    "commission": {
      "currency": "RUB",
      "value": "0.04"
    },
    "webhookUrl": "https://acme.inc/webhook",
    "customFields": {
      "user": "Wile E. Coyote"
    }
  },
  {
    "paymentId": "0123456789-02",
    "creationDateTime": "2023-01-18T15:05:51+03:00",
    "expirationDateTime": "2023-01-18T15:35:51+03:00",
    "status": {
      "value": "COMPLETED",
      "changedDateTime": "2023-01-18T15:06:00+03:00"
    },
    "amount": {
      "currency": "RUB",
      "value": "40.00"
    },
    "recipientDetails": {
      "providerCode": "qiwi-wallet",
      "fields": {
        "account": "79010001122"
      }
    },
    "commission": {
      "currency": "RUB",
      "value": "0.80"
    },
    "webhookUrl": "https://acme.inc/webhook",
    "customFields": {
      "user": "Wile E. Coyote"
    }
  }
]

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

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

Информация по платежу

GET /partner/payout/v2/agents/acme/payments/0123456789-02 HTTP/1.1
Accept: application/json
Authorization: Bearer <Token-Value>
Host: api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789-02

Используется для получения информации о платеже. Поиск платежа осуществляется за последние 50 дней.

   
HTTP метод: GET
URI ресурса: /partner/payout/v2/agents/{agentId}/payments/{paymentId}

Параметры

Параметр Положение ✓\× Тип Описание
agentId path ✓ string Уникальный идентификатор агента
paymentId path ✓ string Уникальный идентификатор платежа от 1 до 36 символов

Ответ

Ответ

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

{
  "paymentId": "0123456789-02",
  "creationDateTime": "2023-01-18T15:05:51+03:00",
  "expirationDateTime": "2023-01-18T15:35:51+03:00",
  "status": {
    "value": "COMPLETED",
    "changedDateTime": "2023-01-18T15:06:00+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "40.00"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.80"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

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

Ответ с HTTP кодом ошибки (4xx, 5xx) содержит объект Error, для подробной информации следует обратиться к разделу Обработка ошибок.

Уведомления

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

Уведомление о статусе платежа

POST /webhook HTTP/1.1
Accept: application/json
Content-Type: application/json
QIWI-Signature: <Sign-Value>
Host: acme.inc

{
  "agentId": "acme",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
    "value": "FAILED",
    "changedDateTime": "2023-01-18T13:00:28Z",
    "errorCode": "INTERNAL_ERROR",
    "errorMessage": "Some reason"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId": "20221101000019",
    "rrn": "A123456",
    "accountNumber": "4950001122",
    "accountInfo": "Ivanov I.P.",
    "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
  }
}

curl -X POST \
     -H "Content-Type: application/json" \
     -H "QIWI-Signature: <Sign-Value>" \
     https://acme.inc/webhook \
     -d '{
           "agentId": "acme",
           "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
           "status": {
             "value": "FAILED",
             "changedDateTime": "2023-01-18T13:00:28Z",
             "errorCode": "INTERNAL_ERROR",
             "errorMessage": "Some reason"
           },
           "amount": {
             "value": "200.00",
             "currency": "RUB"
           },
           "billingDetails": {
             "transactionId": "20221101000019",
             "rrn": "A123456",
             "accountNumber": "4950001122",
             "accountInfo": "Ivanov I.P.",
             "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
           }
        }'

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

   
HTTP метод: POST
URI ресурса: {webhookAddressUrl}

Параметры

Параметр Положение ✓\× Тип Описание
webhookAddressUrl path ✓ string URL адрес для уведомлений со стороны партнера
QIWI-Signature header ✓ string Подпись запроса, см. алгоритм вычисления подписи
payload body ✓ Webhook Информация о платеже

Алгоритм вычисления подписи запроса

Для вычисления подписи QIWI-Signature используется следующий алгоритм:

  1. Сформировать строку для подписи вида: {agentId}|{paymentId}|{status.value}|{amount.value}|{amount.currency}.
    Где каждый из {param} является значением соответствующего параметра path в теле уведомления Webhook и затем склеены между собой символом |.
  2. Вычислить HMAC с хэш-функцией SHA256 от сформированной строки и секретного ключа как ключа шифрования.
  3. Передать получившуюся подпись в заголовке запроса в поле QIWI-Signature.

Ответ

Тело ответа не анализируется, система ориентируется только на коды состояния HTTP.

Любой код, отличный от 2xx, рассматривается как ошибка, система продолжит повторять уведомление.

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

Согласно REST архитектуре верхнеуровневые ошибки обработки запросов передаются в коде состояния HTTP RFC 2068. В универсальном выплатном API применяются следующие HTTP коды:

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

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

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

Модель Error

{
  "serviceName": "payout-api",
  "errorCode": "internal.error",
  "userMessage": "Описание ошибки для отображения пользователя",
  "description": "Описание ошибки",
  "traceId": "aa99e984dd230404",
  "dateTime": "2023-01-01T00:23:46+03:00",
  "cause": {
    "amount": ["Payout's amount is greater than maximum available"]
  }
}

Сводная информация об ошибке.

Параметр ✓\× Тип Описание
serviceName ✓ string Идентификатор сервиса
errorCode ✓ ErrorCode Код ошибки
userMessage ✓ string Описание ошибки для пользователя
description ✓ string Описание ошибки
traceId ✓ string Уникальный идентификатор запроса
dateTime ✓ dateTime Дата возникновения ошибки в формате YYYY-MM-DDThh:mm:ssTZD
cause × map[string, array[string]] Дополнительные детали ошибки

Модель ErrorCode

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

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

Значение Описание
auth.error Общая ошибка авторизации
auth.failed Ошибка авторизации: токен/сертификат не предоставлен или не найден
auth.forbidden Доступ запрещен: нет прав для доступа к запрашиваемому ресурсу

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

Значение Описание
payout.bad.request Некорректный запрос: обязательные параметры отсутствуют или указаны некорректно
payout.resource.exists Ресурс уже существует: ресурс с запрашиваемым идентификатором уже существует
payout.payment.not-found Платеж не найден: платеж по запрашиваемому идентификатору не найден
payout.provider.not-found Провайдер не найден: провайдер по запрашиваемому идентификатору не найден
validation.error Ошибка валидации запроса, некорректный JSON

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

Значение Описание
payout.provider.forbidden Провайдер запрещен: платежи по указанному провайдеру запрещены
payout.provider.unavailable Провайдер недоступен: платежи по указанному провайдеру временно невозможны
payout.billing.declined Платеж отклонен: получен отказ от информационной системы получателя в приеме платежа
payout.billing.timeout Таймаут запроса: не получен ответ от информационной системы получателя

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

Значение Описание
payout.fraud.violated Платеж запрещен: нарушены правила финансового или фрод-мониторинга
payout.legislation.prohibited Платеж запрещен: платеж запрещен согласно требованиям законодательства РФ

Общие ошибки

Значение Описание
payout.insufficient-funds Недостаточно средств: недостаточно денежных средств на балансе партнера
payout.internal.error Внутренняя ошибка
internal.error Внутренняя ошибка

Тестовые реквизиты

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

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

Описание моделей данных, применяемых в API.

Модель Balance

{
  "balance": {
    "currency": "RUB",
    "value": "1000000.00"
  },
  "overdraft": {
    "currency": "RUB",
    "value": "500000.00"
  },
  "available": {
    "currency": "RUB",
    "value": "1500000.00"
  }
}

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

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

Модель Money

{
  "currency": "RUB",
  "value": "1000000.00"
}

Информация о сумме с указанием валюты.

Параметр ✓\× Тип Описание
currency ✓ Currency Код валюты
value ✓ string Сумма в формате числа c разделителем . (точка) и двумя цифрами после

Модель Currency

Перечисление доступных кодов валют согласно спецификации ISO 4217 (буквенный код Alpha-3).

Значение Описание
RUB Российский рубль

Модель Provider

{
  "code" : "qiwi-wallet",
  "name" : "Qiwi кошелек"
}

Краткая информация о провайдере.

Параметр ✓\× Тип Описание
code ✓ ProviderCode Уникальный идентификатор провайдера
name ✓ string Наименование провайдера

Модель ProviderInfo

{
  "name": "Qiwi Wallet",
  "legalName": "Qiwi Bank JSC",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "account",
      "required": true,
      "description": "QW user's account",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "3123011520",
  "contactDetails": {
    "address": "Russia, 117648, Moscow, md. Chertanovo Severnoe, 1A, bldg. 1",
    "phoneNumber": "8-800-707-77-59"
  }
}

Расширенная информация о провайдере.

Параметр ✓\× Тип Описание
name ✓ string Наименование провайдера
legalName ✓ string Юридическое наименование провайдера
amountLimits ✓ map[Currency, Limit] Набор разрешенных сумм для каждой из доступных валют
parameters ✓ set of Parameter Используемые при вызове платежных методов параметры
inn × string ИНН провайдера
contactDetails × Contact Контактные данные провайдера

Модель Parameter

{
  "extKey": "account",
  "required": true,
  "description": "QW user's account",
  "validationPattern": "7\\d{10}"
}

Описание параметра платежа для провайдера.

Параметр ✓\× Тип Описание
extKey ✓ string Код параметра
required ✓ boolean Признак обязательности
description ✓ string Описание параметра
validationPattern × string Шаблон заполнения

Модель Contact

{
  "address": "Russia, 117648, Moscow, md. Chertanovo Severnoe, 1A, bldg. 1",
  "phoneNumber": "8-800-707-77-59"
}

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

Параметр ✓\× Тип Описание
address × string Почтовый адрес
phoneNumber × string Телефонный номер

Модель CurrencyLimit

{
  "currency": "RUB",
  "min": "1.00",
  "max": "600000.00"
}

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

Параметр ✓\× Тип Описание
currency ✓ Currency Код валюты
min ✓ string Минимальная разрешенная сумма (включительно)
max ✓ string Максимально разрешенная сумма (включительно)

Модель Limit

{
  "min": "1.00",
  "max": "600000.00"
}

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

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

Модель PaymentPayload

{
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

Параметры создаваемого платежа.

Параметр ✓\× Тип Описание
amount ✓ Money Сумма платежа
recipientDetails ✓ RecipientDetails Параметры получателя платежа
webhookUrl × string URL адрес для уведомлений
customFields × map[string, string] Дополнительные параметры для сопровождения платежа

Модель RecipientDetails

{
  "providerCode": "qiwi-wallet",
  "fields": {
    "account": "79010001122"
  }
}

Параметры получателя платежа (направления выплаты).

Параметр ✓\× Тип Описание
providerCode ✓ Provider.code Уникальный идентификатор провайдера
fields ✓ map[Parameter.extKey, string] Набор параметров получателя платежа

Модель ProviderCode

Перечисление возможных кодов провайдеров.

Значение Описание
bank-card-russia Выплаты на карты РФ
bank-card-token Выплаты на карты РФ по токену
self-employed-bank-card Выплаты на карты самозанятым
self-employed-card-token Выплаты на карты самозанятым по токену
self-employed-bank-card-tax-payment Выплаты на карты самозанятым с уплатой налога
self-employed-bank-card-recycling Выплаты на карты самозанятым за вторсырье
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 Выплаты на банковские счета юридических лиц

Модель ProviderFields

Информация о параметрах платежа в разрезе провайдера.

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

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

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

{
  "providerCode": "bank-card-token",
  "fields": {
    "account": "ac465705-16f9-477d-a194-6641e0e8e90e"
  }
}
Параметр ✓\× Тип Описание
account ✓ string Токен номера карты
cardholder_name × string Имя получателя
cardholder_lastname × string Фамилия получателя
description × string Описание оказанной услуги

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

{
  "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 ✓ enum Источник дохода (FROM_LEGAL_ENTITY, FROM_INDIVIDUAL)
name × string Имя получателя
lastname × string Фамилия получателя
customerInn × string ИНН организации, оплачивающей услугу
customerOrganization × string Наименование организации, оплачивающей услугу

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

{
  "providerCode": "self-employed-card-token",
  "fields": {
    "inn": "111111111111",
    "account": "ac465705-16f9-477d-a194-6641e0e8e90e",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "Платеж",
    "name": "Имя получателя",
    "lastname": "Фамилия получателя",
    "customerInn": "7777777777",
    "customerOrganization": "Наименование организации, оплачивающей услугу"
  }
}
Параметр ✓\× Тип Описание
account ✓ string Токен номера карты
description ✓ string Описание оказанной услуги
inn ✓ string ИНН самозанятого
incomeType ✓ enum Источник дохода (FROM_LEGAL_ENTITY, FROM_INDIVIDUAL)
name × string Имя получателя
lastname × string Фамилия получателя
customerInn × string ИНН организации, оплачивающей услугу
customerOrganization × string Наименование организации, оплачивающей услугу

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

{
  "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 ✓ enum Источник дохода (FROM_LEGAL_ENTITY, FROM_INDIVIDUAL)
name × string Имя получателя
lastname × string Фамилия получателя
customerInn × string ИНН организации, оплачивающей услугу
customerOrganization × string Наименование организации, оплачивающей услугу

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

{
  "providerCode": "self-employed-bank-card-recycling",
  "fields": {
    "inn": "111111111111",
    "account": "4111111111111111",
    "incomeType": "FROM_LEGAL_ENTITY",
    "description": "ПСА 1001",
    "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"

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

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

{
  "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 Идентификатор банка получателя в СБП
description ✓ string Описание оказанной услуги
inn ✓ string ИНН самозанятого
incomeType ✓ enum Источник дохода (FROM_LEGAL_ENTITY, FROM_INDIVIDUAL)
name × string Имя получателя
lastname × string Фамилия получателя
customerInn × string ИНН организации, оплачивающей услугу
customerOrganization × string Наименование организации, оплачивающей услугу

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

{
  "providerCode": "qiwi-wallet",
  "fields": {
    "account": "79123456789",
    "comment": "Комментарий"
  }
}
Параметр ✓\× Тип Описание
account ✓ string Номер телефона
comment × string Комментарий

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

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

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

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

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

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

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

{
  "providerCode": "sbp-b2c",
  "fields": {
    "account": "79098087755",
    "bankId": "100000000001"
  }
}
Параметр ✓\× Тип Описание
account ✓ string Номер телефона получателя в международном формате без знака +
bankId ✓ string Идентификатор банка получателя в СБП

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

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

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

{
  "providerCode": "sbp-recycling",
  "fields": {
    "phone": "79098087755",
    "bankId": "100000000001",
    "lastName": "Иванов",
    "firstName": "Иван",
    "middleName": "Иванович",
    "description": "ПСА 123"
  }
}
Параметр ✓\× Тип Описание
phone ✓ string Номер телефона получателя в международном формате без знака +
bankId ✓ string Идентификатор банка получателя в СБП
lastName ✓ string Фамилия получателя
firstName ✓ string Имя получателя
middleName × string Отчество получателя
description ✓ string Номер приемо-сдаточного акта или другое основание выплаты 
{
  "providerCode": "legal-entity-bank-account",
  "fields": {
    "account": "50537928100000002463",
    "bik": "304754657",
    "inn": "1111111111",
    "kpp": "389244830",
    "name": "АО Qiwi",
    "remarks": "Платежное поручение №454"
  }
}
Параметр ✓\× Тип Описание
account ✓ string Номер счета получателя
bik ✓ string БИК банка получателя
inn ✓ string ИНН получателя
name ✓ string Наименование организации получателя
remarks ✓ string Назначение платежа
kpp × string КПП получателя (для обществ с ограниченной ответственностью)

Модель BillingDetails

{
  "transactionId": "20221101000019",
  "rrn": "A123456",
  "accountNumber": "4950001122",
  "accountInfo": "Ivanov I.P.",
  "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
}

Дополнительная информация со стороны получателя платежа.

Параметр ✓\× Тип Описание
transactionId × string Идентификатор платежа на стороне получателя
rrn × string Код акцептования платежа на стороне получателя
accountNumber × string Номер счета для подтверждения платежа
accountInfo × string Дополнительная информация для подтверждения платежа
receiptUrl × string Ссылка на документ с информацией о платеже

Модель Payment

{
  "paymentId": "0123456789",
  "creationDateTime": "2023-01-17T15:05:51+03:00",
  "expirationDateTime": "2023-01-17T15:35:51+03:00",
  "status": {
    "value": "READY",
    "changedDateTime": "2023-01-17T15:05:51+03:00"
  },
  "amount": {
    "currency": "RUB",
    "value": "2.00"
  },
  "recipientDetails": {
    "providerCode": "qiwi-wallet",
    "fields": {
      "account": "79010001122"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.04"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  },
  "billingDetails": {
    "transactionId": "20221101000019",
    "rrn": "A123456",
    "accountNumber": "4950001122",
    "accountInfo": "Ivanov I.P.",
    "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
  }
}

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

Параметр ✓\× Тип Описание
paymentId ✓ string Уникальный идентификатор платежа
creationDateTime ✓ dateTime Дата создания платежа в формате YYYY-MM-DDThh:mm:ssTZD
expirationDateTime ✓ dateTime Дата окончания жизни платежа в формате YYYY-MM-DDThh:mm:ssTZD
status ✓ Status Статус платежа
amount ✓ Money Сумма платежа
recipientDetails ✓ RecipientDetails Параметры получателя платежа
commission ✓ Money Рассчитанная сумма комиссии для платежа
webhookUrl × string URL адрес для уведомлений
customFields × map[string, string] Дополнительные параметры для сопровождения платежа
billingDetails × BillingDetails Дополнительная информация со стороны получателя

Модель Status

{
  "value": "READY",
  "changedDateTime": "2023-01-17T15:05:51+03:00"
}

Подробная информация о статусе платежа.

Параметр ✓\× Тип Описание
value ✓ StatusCode Статус платежа
changedDateTime ✓ dateTime Дата изменения статуса платежа в формате YYYY-MM-DDThh:mm:ssTZD
errorCode × StatusErrorCode Код ошибки
errorMessage × string Описание ошибки

Модель StatusCode

Перечисление возможных статусов платежей.

Значение Описание
CREATED Платеж создан, но не готов к проведению
READY Платеж создан и готов к проведению
EXPIRED Срок жизни платежа истек
IN_PROGRESS Платеж в процессе обработки
FAILED Платеж неуспешен
COMPLETED Платеж успешно завершен

Модель StatusErrorCode

Перечисление возможных кодов ошибок.

Значение Описание
INTERNAL_ERROR Внутренняя ошибка
INSUFFICIENT_FUNDS Не проведен из-за недостатка денежных средств
BILLING_DECLINED Платеж отклонен биллингом получателя
FRAUD_SUSPECTED Отклонен из-за подозрения Фрод-мониторинга
LIMIT_ERROR Отклонен из-за превышения лимитов
EXPIRED Платеж просрочен

Модель Webhook

{
  "agentId": "acme",
  "paymentId": "c0d85b0b-a528-9c66-4a15-cb7a12eda9d6",
  "status": {
    "value": "FAILED",
    "changedDateTime": "2023-01-18T13:00:28Z",
    "errorCode": "INTERNAL_ERROR",
    "errorMessage": "Some reason"
  },
  "amount": {
    "value": "200.00",
    "currency": "RUB"
  },
  "billingDetails": {
    "transactionId": "20221101000019",
    "rrn": "A123456",
    "accountNumber": "4950001122",
    "accountInfo": "Ivanov I.P.",
    "receiptUrl": "https://billing.inc/receipt/6f5ec8cc-69ed-4fe5-aa2c-28850fc87ab2"
  }
}

Уведомление об изменении статуса платежа для партнера.

Параметр ✓\× Тип Описание
agentId ✓ string Уникальный идентификатор агента
paymentId ✓ string Уникальный идентификатор платежа
status ✓ Status Статус платежа
amount ✓ Money Сумма платежа
billingDetails × BillingDetails Дополнительная информация со стороны получателя
http bash