PAYMENTS API
Последнее обновление: 01-12-2022
API предназначен для проведения платежей в рамках продукта BaaS. Подробности см. на explain.qiwi.com.
Используемые в тексте термины описаны в этой статье.
Взаимодействие между партнёром и BaaS совершается по защищенному протоколу (HTTPS).
Данные в запросах передаются в формате JSON в кодировке UTF-8. В ответе данные возвращаются также в формате JSON в кодировке UTF-8.
Авторизация
Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.
Схема аутентификации — Bearer.
В заголовках запроса передаётся bearer-токен в поле Authorization
--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"
Bearer-токен выдается партнёру при интеграции.
URL для вызовов API
- https://api-test.qiwi.com — testing-окружение;
- https://api.qiwi.com — production-окружение.
Взаимодействие через API
Пополнение с банковской карты
Пополнение с банковской карты описано на explain.qiwi.com.
Запрос → PUT
URL /partner/openapi-payment-api/v1/replenishment-by-webform/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/replenishment-by-webform/products/best-partner/transactions/a97 \
-X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9FJMjlCRkFFRDM5OE***********************' \
-d '{
"toClientId": "1",
"transactionAmount": {
"value": 100.00,
"currency": "RUB"
},
"clientIpAddress": "255.255.255.255",
"clientCommission" : {
"value" : 2.00,
"currency" : "RUB"
}
}'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
| toClientId | string Обязательный параметр тела запроса. Идентификатор получателя. Уникален в рамках продукта productId. Генерируется партнёром при создании клиента через API Clients. Если для платежа настроена комиссия, необходимо указать clientId, переданный в запросе комиссии по платежу. |
^[A-Za-z0-9-]{1,100}$ |
Cnt-123-DEF-456 |
| transactionAmount | object Обязательный параметр тела запроса. Блок с информацией о сумме операции |
||
| value | string Обязательный параметр тела запроса. Значение с двумя десятичными разрядами. Указывается сумма без учета комиссии. |
200.00 |
|
| currency | string Обязательный параметр тела запроса. Валюта, ISO 4217 |
RUB |
|
| clientIpAddress | string Обязательный параметр тела запроса. IP-адрес, с которого клиент осуществляет запрос на совершение платежа |
валидный IPv4/IPv6 | 255.255.255.255 |
| clientCommission | object Параметр тела запроса. Блок с информацией о комиссии, которая взимается с клиента. Если комиссия для указанного productID не настроена в BaaS, передавать параметр не нужно. |
||
| value | number Параметр тела запроса. Значение с двумя десятичными разрядами. Необходимо передать значение, полученное запросом комиссии по платежу. |
10.00 |
|
| currency | string Параметр тела запроса. Валюта, ISO 4217 |
RUB |
Ответ ←
Пример ответа
{
"productId": "best-partner",
"transactionId": "a97",
"toClientId": "1",
"transactionAmount": {
"currency": "RUB",
"value": "100.00"
},
"creationDateTime": "2020-08-25T18:11:22+03:00",
"payUrl": "https://oplata-test.qiwi.com/form/?invoice_uid=0ad92a20-3dfc-4627-baa4-b70a96a867ae",
"status": "PROCESSING",
"statusDetails": {},
"clientCommission": {
"currency": "RUB",
"value": 2.00
}
}
| Параметр | Тип | Описание |
|---|---|---|
| productId | String | Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции |
| transactionId | String | Уникальный идентификатор операции в системе партнёра |
| toClientId | String | Идентификатор получателя. Уникален в рамках продукта productId |
| transactionAmount | Блок с информацией о сумме операции | |
| currency | String | Валюта, ISO 4217 |
| value | String | Значение с двумя десятичными разрядами |
| creationDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата создания операции в BaaS |
| accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в сервисе Payments |
| payUrl | String | URL платежной формы, на которую партнёру необходимо перенаправить клиента для заполнения реквизитов платежа |
| status | String | Статус операции в BaaS |
| statusDetails | String | Заполнен, если "status": "DECLINED" |
| clientCommission | Блок с информацией о комиссии, которая взимается с клиента | |
| value | Number | Значение с двумя десятичными разрядами |
| currency | String | Валюта, ISO 4217 |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Статус пополнения с банковской карты
Метод используется для получения текущего статуса платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/replenishment-by-webform/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/replenishment-by-webform/products/best-partner/transactions/a97 \
-X GET \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoiCRkFFRDM5OE***********************'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ | Txn-123-DEF-456 |
Ответ ←
См. ответ на запрос "Пополнение с банковской карты".
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Выплата на кошелёк
Подробности см. на explain.qiwi.com.
Запрос → PUT
URL /partner/openapi-payment-api/v1/replenishment-from-funder/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/replenishment-from-funder/products/best-partner/transactions/a98 \
-X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzMjlCRkFFRDM5OE***********************' \
-d '{
"fromFunderId": "uid40",
"toClientId": "customerUid4000",
"transactionAmount": {
"currency": "RUB",
"value": "200.00"
},
"clientIpAddress": "255.255.255.255"
}'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ | Txn-123-DEF-456 |
| fromFunderId | string Обязательный параметр тела запроса. Идентификатор источника средств |
^[A-Za-z0-9-]{1,100}$ | Fnd-123-DEF-456 |
| toClientId | string Обязательный параметр тела запроса. Идентификатор получателя. Уникален в рамках продукта productId. Генерируется при создании клиента по API Clients. |
^[A-Za-z0-9-]{1,100}$ | Cnt-123-DEF-456 |
| transactionAmount | object Обязательный параметр тела запроса. Блок с информацией о сумме операции |
||
| value | string Обязательный параметр тела запроса. Значение с двумя десятичными разрядами |
200.00 |
|
| currency | string Обязательный параметр тела запроса. Валюта, ISO 4217 |
RUB |
|
| clientIpAddress | string Обязательный параметр тела запроса. IP-адрес, с которого клиент осуществляет запрос на совершение платежа |
валидный IPv4/IPv6 | 255.255.255.255 |
Ответ ←
Пример ответа
{
"productId": "best-partner",
"transactionId": "a98",
"fromFunderId": "uid40",
"toClientId": "1",
"transactionAmount": {
"currency": "RUB",
"value": 50.00
},
"creationDateTime": "2020-08-26T13:03:17+03:00",
"accountingDateTime": "2020-08-26T13:03:17+03:00",
"status": "SUCCESS",
"statusDetails": {}
}
| Параметр | Тип | Описание |
|---|---|---|
| productId | String | Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции |
| transactionId | String | Уникальный идентификатор операции в системе партнёра |
| fromFunderId | String | Идентификатор источника средств |
| toClientId | String | Идентификатор получателя. Уникален в рамках продукта productId |
| transactionAmount | Блок с информацией о сумме операции | |
| currency | String | Валюта, ISO 4217 |
| value | Number | Значение с двумя десятичными разрядами |
| creationDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата создания операции в BaaS |
| accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в BaaS |
| status | String | Статус операции в BaaS |
| statusDetails | String | Заполнен, если "status": "DECLINED" |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Статус выплаты на кошелёк
Метод используется для получения текущего статуса платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/replenishment-from-funder/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/replenishment-from-funder/products/best-partner/transactions/a98 \
-X GET \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
Ответ ←
См. ответ на запрос "Выплата на кошелёк".
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Перевод на банковскую карту
Перевод на банковскую карту описан на explain.qiwi.com.
Запрос → PUT
URL /partner/openapi-payment-api/v1/withdrawal-to-card/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/withdrawal-to-card/products/best-partner/transactions/a97 \
-X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoiMjlCRkFFRDM5OE***********************' \
-d '{
"fromAccountId": "customerAccountUid4000",
"pan": "4002345686552016",
"clientIpAddress": "198.204.56.69",
"transactionAmount": {
"value" : 9.45,
"currency" : "RUB"
},
"clientCommission": {
"value" : 49.00,
"currency" : "RUB"
}
}'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
| fromAccountId | string Обязательный параметр тела запроса. Уникальный идентификатор счёта, c которого происходит списание денежных средств. Генерируется партнёром при создании счёта по API Clients. |
^[A-Za-z0-9-]{1,100}$ |
Acc-123-DEF-456 |
| pan | string Обязательный параметр тела запроса. Номер карты получателя денежных средств |
^\\d{16,19}$ |
2345678910111213 |
| transactionAmount | object Обязательный параметр тела запроса. Блок с информацией о сумме операции |
||
| value | number Обязательный параметр тела запроса. Значение с двумя десятичными разрядами. Указывается сумма без учета комиссии. |
200.00 |
|
| currency | string Обязательный параметр тела запроса. Валюта, ISO 4217 |
RUB |
|
| clientIpAddress | string Обязательный параметр тела запроса. IP-адрес, с которого клиент осуществляет запрос на совершение платежа |
валидный IPv4/IPv6 | 255.255.255.255 |
| clientCommission | object Обязательный параметр тела запроса. Блок с информацией о комиссии, которая взимается с клиента. Если комиссия для указанного productID не настроена в BaaS, передавать параметр не нужно. |
||
| value | number Обязательный параметр тела запроса. Значение с двумя десятичными разрядами. Нужно передать значение, полученное запросом комиссии по платежу. |
10.00 |
|
| currency | string Обязательный параметр тела запроса. Валюта, ISO 4217 |
RUB |
Ответ ←
Пример ответа
{
"productId": "best-partner",
"transactionId": "a97",
"fromAccountId": "customerAccountUid4000",
"transactionAmount": {
"currency": "RUB",
"value": 200
},
"clientCommission" : {
"value" : 49.00,
"currency" : "RUB"
},
"creationDateTime": "2018-10-31T18:10:37+03:00",
"accountingDateTime": "2017-09-03T14:30:00+03:00",
"status": "PROCESSING",
"statusDetails": {},
"needClientApprove": false
}
| Параметр | Тип | Описание |
|---|---|---|
| productId | String | Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции |
| transactionId | String | Уникальный идентификатор операции в системе партнёра |
| fromAccountId | String | Уникальный идентификатор счёта, c которого происходит списание денежных средств |
| transactionAmount | Блок с информацией о сумме операции | |
| currency | String | Валюта, ISO 4217 |
| value | Number | Значение с двумя десятичными разрядами |
| creationDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата создания операции в BaaS |
| accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в BaaS |
| status | String | Статус операции в BaaS |
| statusDetails | String | Заполнен, если "status": "DECLINED" |
| clientCommission | Блок с информацией о комиссии, которая взимается с клиента | |
| value | Number | Значение с двумя десятичными разрядами |
| currency | String | Валюта, ISO 4217 |
| needClientApprove | Boolean | Если true - клиенту необходимо сообщить о том, что перевод на указанную карту является потенциально подозрительной операцией: получатель денежных средств, возможно, относится к числу финансовых мошенников. Клиент может отказаться от проведения операции или подтвердить ее исполнение запросом confirmations. |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Получение комиссии по платежу
Получение комиссии описано на explain.qiwi.com.
Запрос → GET
URL /partner/openapi-commissions/v1/products/{productId}/payment/{txnType}?clientId={clientId}&value={value}¤cy={currency}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-commissions/v1/products/best-partner/{txnType}?clientId=1&value=100.99¤cy=RUB \
-X GET \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| txnType | Обязательный параметр URL запроса. Тип операции, для которой необходимо получить размер комиссии | ||
| clientId | Обязательный параметр URL запроса. Идентификатор клиента, для которого планируется совершить платеж и которому необходимо отобразить размер комиссии. Уникален в рамках продукта productId. Генерируется при создании клиента по API Clients. |
^[A-Za-z0-9-]{1,100}$ |
Cnt-123-DEF-456 |
| value | Обязательный параметр URL запроса. Сумма, для которой необходимо рассчитать размер комиссии. Эта же сумма должна быть передана в transactionAmount платежного запроса. |
10.00 |
|
| currency | Обязательный параметр URL запроса. Валюта, ISO 4217 |
Ответ ←
Пример ответа
{
"clientCommission": {
"value": 10.00,
"currency": "RUB"
}
}
| Параметр | Тип | Описание |
|---|---|---|
| clientCommission | object | Блок с информацией о комиссии, которая взимается с клиента |
| value | Number | Размер комиссии, значение с двумя десятичными разрядами |
| currency | String | Валюта, ISO 4217 |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Типы операций для получения размера комиссии
| Тип операции | Описание |
|---|---|
| replenishment-by-webform | Пополнение с банковской карты |
| withdrawal-to-card | Перевод на банковскую карту |
Подтверждение перевода на банковскую карту
Перевод средств на банковскую карту (в том числе этап подтверждения перевода) описан на explain.qiwi.com.
Запрос → PUT
URL /partner/openapi-payment-api/v1/withdrawal-to-card/products/{productId}/transactions/{transactionId}/confirmations
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/withdrawal-to-card/products/best-partner/transactions/a97/confirmations \
-X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVFJMjlCRkFFRDM5OE***********************' \
-d '{
"clientApproveStatus": "APPROVED"
}'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
| clientApproveStatus | string Обязательный параметр тела запроса. Статус подтверждения. Необходимо передать APPROVED или NOT_APPROVED: см. справочник статусов. |
APPROVED |
Ответ ←
Пример ответа
{
"clientApproveStatus": "APPROVED"
}
| Параметр | Тип | Описание |
|---|---|---|
| clientApproveStatus | String | Статус подтверждения: см. справочник статусов |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Статус подтверждения перевода на банковскую карту
Метод используется для получения текущего статуса операции подтверждения платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/withdrawal-to-card/products/{productId}/transactions/{transactionId}/confirmations
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/withdrawal-to-card/products/best-partner/transactions/a97/confirmations \
-X GET \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
Ответ ←
См. ответ на запрос confirmations.
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Справочник статусов подтверждения платежа
| Статус | Описание |
|---|---|
| APPROVED | Платеж подтвержден: финальный статус |
| NOT_APPROVED | Платеж не подтвержден: финальный статус |
| NONE | Промежуточный статус: возвращается, если отсутствует подтверждение или отказ на проведение операции |
Статус перевода на банковскую карту
Метод используется для получения текущего статуса платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/withdrawal-to-card/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/withdrawal-to-card/products/best-partner/transactions/a97 \
-X GET \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
Ответ ←
См. ответ на запрос "Перевод на банковскую карту".
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Получение токена формы для перевода на банковскую карту
Перевод средств на банковскую карту с помощью формы описан на explain.qiwi.com. Метод возвращает токен и URL-адрес формы для перевода.
Запрос → PUT
URL /partner/openapi-payment-api/v1/withdrawal-to-card/products/{productId}/transactions/{transactionId}/form-token
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/withdrawal-to-card/products/best-partner/transactions/a99/form-token \
-X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******' \
-d '{
"fromAccountId" : "customerAccountUid4000"
}'
| Параметр | Описание | REGEX | Пример | |
|---|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта: выдается партнёру при интеграции | \^[A-Za-z0-9-]{1,100}$ | Prd-123-DEF-456 |
|
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ | Txn-123-DEF-456 |
+ |
| fromAccountId | string Обязательный параметр тела запроса. Уникальный идентификатор счёта, c которого происходит списание денежных средств. Генерируется партнёром при создании счёта по API Clients. |
^[A-Za-z0-9-]{1,100}$ | Acc-123-DEF-456 |
Ответ ←
Пример ответа
{
"formToken" : "0b96b8e82f93b00a4010a66e23adb9e1",
"formUrl" : "https://openapi-widget.qiwi.com/api/pay-transfer-widget/widget"
}
| Параметр | Тип | Описание |
|---|---|---|
| formToken | String | Токен для формы просмотра реквизитов карты. |
| formUrl | String | URL формы для перевода на банковскую карту |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Перевод между кошельками
Перевод между кошельками описан на explain.qiwi.com.
Запрос → PUT
URL /partner/openapi-payment-api/v1/transfer-betweenclients/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/transfer-between-clients/products/best-partner/transactions/a121 \
-X PUT \
-H 'Content-Type: application/json;charset=UTF-8' \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhRkFFRDM5OE***********************' \
-d '{
"fromClientId": "customerUid4000",
"toClientId": "customerUid3000",
"transactionAmount": {
"value": 200.00,
"currency": "RUB"
},
"clientIpAddress": "255.255.255.255"
}'
| Параметр | Описание | REGEX | Пример |
|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
| fromClientId | string Обязательный параметр тела запроса. Идентификатор клиента-отправителя. Генерируется при создании клиента по API Clients |
^[A-Za-z0-9-]{1,100}$ |
Cnt-123-DEF-456 |
| toClientId | string Обязательный параметр тела запроса. Идентификатор клиента-получателя. Генерируется при создании клиента по API Clients |
^[A-Za-z0-9-]{1,100}$ |
Cnt-123-DEF-456 |
| transactionAmount | object Обязательный параметр тела запроса. Блок с информацией о сумме операции |
||
| value | number Обязательный параметр тела запроса. Значение с двумя десятичными разрядами |
200.00 |
|
| currency | string Обязательный параметр тела запроса. Валюта, ISO 4217 |
RUB |
|
| clientIpAddress | string Обязательный параметр тела запроса. IP-адрес, с которого клиент осуществляет запрос на совершение платежа |
валидный IPv4/IPv6 | 255.255.255.255 |
Ответ ←
Пример ответа
{
"productId": "best-partner",
"transactionId": "a121",
"fromClientId": "customerUid4000",
"toClientId": "customerUid3000",
"transactionAmount": {
"currency": "RUB",
"value": 200
},
"creationDateTime": "2018-10-31T18:36:35+03:00",
"accountingDateTime": "2018-10-31T18:36:35+03:00",
"status": "SUCCESS",
"statusDetails": {}
}
| Параметр | Тип | Описание |
|---|---|---|
| productId | String | Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции |
| transactionId | String | Уникальный идентификатор операции в системе партнёра |
| fromClientId | String | Идентификатор клиента-отправителя |
| toClientId | String | Идентификатор клиента-получателя |
| transactionAmount | Блок с информацией о сумме операции | |
| currency | String | Валюта, ISO 4217 |
| value | String | Значение с двумя десятичными разрядами |
| creationDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата создания операции в BaaS |
| accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в BaaS |
| status | String | Статус операции в BaaS |
| statusDetails | String | Заполнен, если "status": "DECLINED" |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Статус перевода между кошельками
Метод используется для получения текущего статуса платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/transfer-betweenclients/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/transfer-between-clients/products/best-partner/transactions/a121 \
-X GET \
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
| Параметр | Описание | Тип | REGEX | Пример | Обяз. |
|---|---|---|---|---|---|
| productId | Обязательный параметр URL запроса. Идентификатор продукта, в рамках которого совершается платеж: выдается партнёру при интеграции | String | ^[A-Za-z0-9-]{1,100}$ |
Prd-123-DEF-456 |
+ |
| transactionId | Обязательный параметр URL запроса. Уникальный идентификатор операции в системе партнёра | String | ^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
+ |
Ответ ←
См. ответ на запрос "Перевод между кошельками".
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Статусы платежей
| Статус | Описание |
|---|---|
| PROCESSING | Платеж в процессе проведения |
| SUCCESS | Платеж успешен: финальный статус |
| DECLINED | Платеж неуспешен: финальный статус |
Детализация статуса DECLINED
Пример ответа с статусом DECLINED
{
"productId": "best-partner",
"transactionId": "txn1",
"fromClientId": "1",
"toClientId": "2",
"transactionAmount": {
"currency": "RUB",
"value": 2.00
},
"creationDateTime": "2020-08-26T16:09:09+03:00",
"accountingDateTime": "2020-08-26T16:09:09+03:00",
"status": "DECLINED",
"statusDetails": {
"failureCode": "LIMIT_EXCEEDED"
}
}
Ответ на запрос с финальным неуспешным статусом DECLINED содержит:
-
для обычного платежа – объект
statusDetails, например:"status":"DECLINED", "statusDetails":{"failureCode":"LIMIT_EXCEEDED"} -
для отмены – объект
cancellationStatusDetails, например:"cancellationStatus":"DECLINED","cancellationStatusDetails":{"failureCode":"ORIGIN_TXN_AMOUNT_EXCEEDED"}
В поле failureCode указывается код детализации статуса.
Справочник кодов детализации статуса
| Код | Описание |
|---|---|
| CLIENT_BLOCKED | Клиент заблокирован. |
| ORIGIN_TXN_EXPIRED | Актуально для отмен: срок, когда исходную операцию можно отменить, истек. |
| ORIGIN_TXN_AMOUNT_EXCEEDED | Актуально для отмен: допустимая сумма отмены превышена. |
| ORIGIN_TXN_CANCELLATIONS_COUNT_EXCEEDED | Актуально для отмен: количество отмен для одной операции превышено. |
| ORIGIN_TXN_INCORRECT_STATUS | Актуально для отмен: исходная операция находится в статусе, в котором ее нельзя отменить. |
| CLIENT_INCORRECT_IDENTIFICATION_LEVEL | Выполнение операции запрещено для текущего уровня идентификации клиента. |
| ACCOUNT_BALANCE_ERROR | Системная ошибка, связанная с балансами. |
| ACCOUNT_BALANCE_INSUFFICIENT_FUNDS | Недостаточно средств на источнике платежа: в случае платежа со счёта клиента. |
| ACCOUNT_BALANCE_EXCEEDED | Нарушен допустимый лимит на остаток на счёте. |
| LIMIT_EXCEEDED | Нарушены лимиты: на оборот, на сумму одной операции и т.д. |
| INVOICE_EXPIRED | Актуально для операции пополнения с карты: счёт для оплаты был создан, но не оплачен клиентом в течение заданного времени. |
| INVOICE_ERROR | Актуально для операции пополнения счёта клиента с банковской карты: возникла ошибка со счётом для оплаты с карты. |
| PAYMENT_ERROR | Актуально для операции перевода средств на банковскую карту: возникла ошибка при зачислении средств на банковскую карту. |
| FRAUD_OPERATION | Операция запрещена системой фрод-мониторинга. |
Формат ошибок API
В разделе описывается структура ответа на неуспешный запрос.
Пример ответа
{
"serviceName": "openapi-payment-api",
"errorCode": "validation.error",
"dateTime": "2020-07-23T20:13:22.290416+03:00",
"traceId": "67477569e8bc6838",
"cause": {
"fromFunderId.value": [
"Abc-123-DEF-456" # string, regex: ^[A-Za-z0-9-]{1,100}$
]
}
}
| Название | Описание |
|---|---|
| serviceName | Имя сервиса, который вернул ошибку |
| errorCode | Код ошибки. См. справочник кодов ошибок |
| dateTime | Дата и время формирования ответа |
| traceId | Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовках ответа (response headers) в параметре X-B3-TraceId |
| cause | Причина, опциональный параметр |
Справочник кодов ошибок
| Код | Описание |
|---|---|
| openapi.payment.api.bad.request.data | Некорректные параметры запроса |
| openapi.payment.api.bad.amount.data | Некорректная сумма: платеж на указанную сумму провести нельзя |
| openapi.payment.api.unsupported.currency | Указанная валюта не поддерживается |
| openapi.payment.api.txn.parameter.changed | Попытка создать операцию с тем же идентификатором, но другими данными |
| openapi.payment.api.txn.type.changed | Попытка создать/получить операцию с верным идентификатором, но неверного типа: тип операции содержится в path запроса (p2p, payment и т.д.) |
| openapi.payment.api.txn.test.mode.configured.incorrectly | Попытка создать операцию не в тестовом режиме, при этом для партнёра задана настройка "тестовый режим", и наоборот. Все участники операции (productId, fromFunderId, providerId, clientId) должны быть в одинаковом состоянии: отсутствие или наличие тестового режима. |
| openapi.payment.api.txn.not.found | Операция не найдена |
| openapi.payment.api.client.not.found | Клиент не найден |
| openapi.payment.api.provider.not.found | Провайдер не найден |
| openapi.payment.api.withdrawal.to.card.not.found | Не найдена операция перевода на карту |
| openapi.payment.api.withdrawal.to.card.token.parameter.changed | Попытка выпустить токен формы для перевода средств на банковскую карту с тем же идентификатором транзакции, что уже выпущенный, но другими данными (fromAccountId) |
| openapi.payment.api.withdrawal.to.card.token.expired | Токен формы для перевода средств на банковскую карту с таким идентификатором транзакции уже был выпущен и срок его действия истек |
| openapi.payment.api.withdrawal.to.card.token.already.used | Токен формы для перевода средств на банковскую карту с таким идентификатором транзакции уже был выпущен и использован для создания перевода клиентом |
| openapi.payment.api.withdrawal.to.card.already.exists | Попытка выпустить токен формы для перевода средств на банковскую карту с тем же идентификатором транзакции, как уже существующий перевод |
| openapi.payment.api.funder.not.found | Источник денежных средств не найден |
| openapi.payment.api.product.not.found | Продукт не найден |
| openapi.payment.api.client.blocked | Клиент заблокирован |
| openapi.payment.api.payform.not.enabled.for.product | Не заданы настройки для пополнения с карты |
| openapi.payment.api.payout.not.enabled.for.product | Не заданы настройки для перевода на карту |
| openapi.payment.api.client.wrong.identification.level | Выполнение операции запрещено для текущего уровня идентификации клиента |
| openapi.payment.api.precheck.failed | В случае пополнения с банковской карты и перевода на банковскую карту: запрос не прошел банковские проверки, например, превышен лимит. Финансовая операция не создаётся. |
| openapi.payment.api.withdrawal.to.card.does.not.require.confirmation | В случае перевода на карту: операцию не требуется подтверждать. |
| openapi.payment.api.cancellation.not.found | Операция отмены не найдена |
| openapi.payment.api.cancellation.parameter.changed | Попытка создать отмену с тем же идентификатором, но другими данными |
| openapi.payment.api.wrong.commission.amount | Неверная сумма комиссии |
| openapi.payment.api.wrong.commission.currency | Неверная валюта комиссии |
| openapi.commissions.internal.error | Внутренняя ошибка в сервисе комиссий |
| openapi.commissions.product.not.found | Продукт не найден |
| openapi.commissions.wrong.currency | Неверная валюта/валюта не поддерживается |
| openapi.commissions.wrong.provider.data | В случае платежей в пользу провайдеров, для которых необходимо заполнять toProviderData: параметр toProviderData не заполнен или заполнен некорректно. |
| openapi.commissions.cancellation.inapplicable | Отмены не применимы к платежу |
| openapi.commissions.wrong.money.amount | Некорректная сумма: получить комиссию на указанную сумму нельзя |