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

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

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: b2b-api.qiwi.com

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-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: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-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: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-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": "Банковские карты РФ"
  }
]

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

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

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

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

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

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

   
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": "Выплаты на банковские карты",
  "legalName": "",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "pan",
      "required": true,
      "description": "Немаскированный PAN карты",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "3111453720",
  "contactDetails": {
    "address": "адрес",
    "phoneNumber": "8-800-111-22-33"
  }
}

Успешный ответ содержит расширенную информацию о провайдере в виде объекта 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>
Signature: <Sign-Value>
Host: b2b-api.qiwi.com

{
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "recipientDetails": {
    "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234567890213456"
    }
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

curl -X PUT \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <Token-Value>" \
     -H "Signature: <Sign-Value>" \
     https://b2b-api.qiwi.com/partner/payout/v2/agents/acme/payments/0123456789 \
     -d '{
            "amount": {
              "value": "2.00",
              "currency": "RUB"
            },
            "recipientDetails": {
              "providerCode": "bank-card-russia",
              "fields": {
                "pan": "1234567890213456"
              }
            },
            "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 символов
Signature header ✓ string Подпись платежного запроса
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": "bank-card-russia",
    "fields": {
      "pan": "1234567890213456"
    }
  },
  "commission": {
    "currency": "RUB",
    "value": "0.04"
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

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

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

Подпись платежного запроса

При создании платежа партнер должен подписать запрос и передать значение подписи в заголовке Signature.

Чтобы подписать запрос, необходимо выполнить действия:

  1. Создать пару ключей с помощью алгоритма RSA-2048.
  2. Передать публичный ключ, соответствующий секретному ключу.
  3. Подписывать каждый запрос создания платежа.

Шаги 1 и 2 выполняются разово, шаг 3 — каждый раз при создании запроса.

Создание пары ключей

  • Сгенерируйте закрытый ключ
openssl genrsa -out private-key.pem 2048
  • Получите открытый ключ, соответствующий закрытому
openssl rsa -in private-key.pem -pubout -out public-key.pem

Создание пары ключей выполняется с помощью утилиты OpenSSL.

  1. Сгенерируйте закрытый ключ. Размер закрытого ключа — строго 2048 бит, формат — PEM.

    В папке выполнения команды будет создан файл с секретным ключом: private-key.pem.

  2. Получите открытый ключ, соответствующий закрытому.

Передача публичного ключа

Партнёр должен передать QIWI ключ, полученный на шаге 2 создания пары ключей. Способ передачи ключа необходимо уточнить у курирующего менеджера.

Вычисление подписи для запроса

  • Сформируйте строку для подписи
SIGNATURE_STRING='{agentId}|{paymentId}|{amount.value}|{amount.currency}|{recipientDetails.providerCode}|{значения recipientDetails.fields в алфавитном порядке ключей}'
  • Сформируйте цифровую подпись
SIGNATURE_RAW=$(echo -n $SIGNATURE_STRING | openssl dgst -sha256 -sign private-key.pem)
  • Закодируйте полученную цифровую подпись
SIGNATURE_BASE64=$(echo -n $SIGNATURE_RAW | base64)
  1. Сформируйте строку для подписи со значениями выбранных параметров запроса (используйте разделитель | для соединения параметров):
    • agentId
    • paymentId
    • amount.value
    • amount.currency
    • recipientDetails.providerCode
    • значения recipientDetails.fields в алфавитном порядке ключей.
      Можно использовать подготовленные шаблоны строк для подписи, которые для каждого провайдера индивидуальны.
  2. Сформируйте цифровую подпись с помощью алгоритма SHA256withRSA и секретного ключа private-key.pem, полученного на этапе Создание пары ключей.
  3. Закодируйте полученную цифровую подпись при помощи Base64 в строку.
  4. Передайте закодированную цифровую подпись в заголовке Signature при отправке запроса.

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

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

curl -X POST \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-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": "bank-card-russia",
      "fields": {
        "pan": "1234564543654321"
      }
  },
  "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: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-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": "bank-card-russia",
      "fields": {
        "pan": "1234564543654321"
      }
    },
    "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": "bank-card-russia",
      "fields": {
        "pan": "1233764543654321"
      }
    },
    "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: b2b-api.qiwi.com

curl -X GET \
     -H "Authorization: Bearer <Token-Value>" \
     https://b2b-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": "bank-card-russia",
      "fields": {
        "pan": "1234564543654321"
      }
  },
  "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
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 "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 адрес для уведомлений со стороны партнера
Signature header ✓ string Подпись запроса, см. алгоритм вычисления подписи
payload body ✓ Webhook Информация о платеже

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

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

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

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

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

Провайдер Статус платежа Стадия платежа Реквизит Значение
bank-card-russia
bank-card-russia-fio
bank-card-russia-gph		 COMPLETED Проведение pan 2201380000000009
bank-card-russia
bank-card-russia-fio
bank-card-russia-gph		 FAILED Создание pan 4444440000000004
bank-card-russia
bank-card-russia-fio
bank-card-russia-gph		 FAILED Проведение pan 5555550000000002
bank-card-russia
bank-card-russia-fio
bank-card-russia-gph		 IN_PROGRESS Проведение pan 2201380000000017
sbp-b2c COMPLETED Проведение bankId sbp_bank_id_success
sbp-b2c FAILED Создание bankId sbp_bank_id_create_failed
sbp-b2c FAILED Проведение bankId sbp_bank_id_execute_failed
sbp-b2c IN_PROGRESS Проведение bankId sbp_bank_id_execute_in_progress
bank-card-token COMPLETED Проведение account token_success
bank-card-token FAILED Создание account token_create_failed
bank-card-token FAILED Проведение account token_execute_failed
bank-card-token IN_PROGRESS Проведение account token_execute_in_progress

Для тестирования полной цепочки платежа через Банк, где у вас открыт счет, обратитесь к вашему менеджеру поддержки - после уточнения деталей и настройки, вам выдадут новый agentId.

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

Описание моделей данных, применяемых в 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" : "bank-card-russia",
  "name" : "Выплаты на карты банков РФ"
}

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

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

Модель ProviderInfo

{
  "name": "Выплаты на банковские карты",
  "legalName": "",
  "amountLimits": {
    "RUB": {
      "min": "1.00",
      "max": "600000.00"
    }
  },
  "parameters": [
    {
      "extKey": "pan",
      "required": true,
      "description": "Немаскированный PAN карты",
      "validationPattern": "7\\d{10}"
    }
  ],
  "inn": "3111453720",
  "contactDetails": {
    "address": "адрес",
    "phoneNumber": "8-800-111-22-33"
  }
}

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

Параметр ✓\× Тип Описание
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": "bank-card-russia",
      "fields": {
        "pan": "1234564543654321"
      }
  },
  "webhookUrl": "https://acme.inc/webhook",
  "customFields": {
    "user": "Wile E. Coyote"
  }
}

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

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

Модель RecipientDetails

{
  "providerCode": "bank-card-russia",
    "fields": {
      "pan": "1234564543654321"
    }
}

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

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

Модель ProviderCode

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

Значение Описание
bank-card-russia Выплаты на карты РФ
bank-card-russia-fio Выплаты на карты РФ с обязательным указанием ФИО получателя
bank-card-russia-gph Выплаты на карты РФ по договору ГПХ
bank-card-token Выплаты на карты РФ по токену
sbp-b2c Выплаты по СБП

Модель 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-russia-fio"

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

Выплаты на банковские карты РФ по договору ГПХ "providerCode": "bank-card-russia-gph"

{
  "providerCode": "bank-card-russia-gph",
  "fields": {
    "pan": "2201380000000009",
    "lastName": "Иванов",
    "firstName": "Иван",
    "purpose": "Выплата по договору ГПХ №2 от 01.01.2025, за оказанные услуги, за период 02.2025"
  }
}
Параметр ✓\× Тип Описание
pan ✓ string Номер карты получателя
lastName ✓ string Фамилия получателя
firstName ✓ string Имя получателя
middleName × string Отчество получателя
purpose ✓ string Описание оказанной услуги

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

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

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

{
  "providerCode": "bank-card-token",
  "fields": {
    "account": "17b985ce-5677-49f8-b88f-5ac2ef2cbc52"
  }
}
Параметр ✓\× Тип Описание
account ✓ string Токен карты получателя
cardholder_name × string Имя получателя
cardholder_lastname × string Фамилия получателя
description × 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": "bank-card-russia",
      "fields": {
        "pan": "1234564543654321"
      }
  },
  "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 Дополнительная информация со стороны получателя
Примеры