PAYMENTS API
Последнее обновление: 14-03-2022
API предназначен для партнеров, инициирующих платежи из своего пользовательского интерфейса.
Термины, используемые в тексте:
- пользовательский интерфейс — web-сайт или мобильное приложение;
- пользователь — клиент (физическое лицо), использующий интерфейс;
- партнер — юридическое лицо, использующее API с целью предоставить физическим лицам платежную функциональность в своем интерфейсе;
- провайдер — поставщик услуги.
Взаимодействие между партнёром и сервисом Payments совершается по защищенному протоколу (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-окружение.
Сценарии взаимодействия с сервисом
Сценарий пополнения счета пользователя с банковской карты
Партнер использует платежную форму QIWI
- Пользователь инициирует пополнение баланса своего счета с банковской карты в интерфейсе партнера. Если для этого типа платежа настроена комиссия, партнер отправляет запрос для получения значения комиссии.
- Партнер отправляет платежный запрос сервису Payments, в котором передает сумму платежа и размер полученной ранее комиссии.
- В случае неуспешной обработки запроса сервис Payments возвращает сервису партнера соответствующий ответ. В случае успешной обработки запроса сервис Payments возвращает сервису партнера статус проведения платежа
PROCESSING
и URL платежной формы в полеpayUrl
. - Партнер перенаправляет пользователя на полученный url для ввода данных банковской карты.
- Пользователь указывает данные карты и подтверждает оплату.
- Сервис Payments проводит операцию пополнения. При неуспешном проведении операции пополнения пользователю будет предложено повторить операцию с возможностью смены реквизитов банковской карты. При успешном проведении операции на форме оплаты пользователь увидит соответствующее подтверждение.
- Партнер получает уведомление, содержащее актуальный статус пополнения.
- Если статус пополнения принял финальное значение (финальный успешный или финальный неуспешный), то рекомендуется однократно выполнить соответствующий запрос статуса. Это позволит устранить риски компрометации данных в случае утечки секрета, используемого при вычислении цифровой подписи уведомления.
- На основании полученного статуса партнер принимает решение об успешности платежа в своей системе.
Сценарий перевода средств со счета пользователя на банковскую карту
- Пользователь инициирует перевод средств со своего счета на банковскую карту в интерфейсе партнера. Если для этого типа платежа настроена комиссия, партнер отправляет запрос для получения значения комиссии. Пользователь видит размер комиссии и подтверждает платеж.
- Партнер отправляет платежный запрос сервису Payments, в котором передает сумму платежа и размер полученной ранее комиссии.
- В случае неуспешной обработки запроса сервис Payments возвращает сервису партнера соответствующий ответ. В случае успешной обработки запроса сервис Payments возвращает сервису партнера статус проведения платежа
PROCESSING
и информацию о необходимости подтвердить платеж -needClientApprove
. - Если
needClientApprove
имеет значениеtrue
— партнер сообщает пользователю о том, что перевод на указанную карту является потенциально подозрительной операцией: получатель денежных средств, возможно, относится к числу финансовых мошенников. Пользователь отказывается от проведения операции или подтверждает ее исполнение. - Партнер передает сервису Payments отказ или подтверждение пользователя запросом confirmations.
- Сервис Payments проводит операцию перевода средств на банковскую карту.
- Партнер получает уведомление, содержащее актуальный статус платежа.
- Если статус платежа принял финальное значение (финальный успешный или финальный неуспешный), партнеру достаточно однократно выполнить соответствующий запрос статуса. Это позволит устранить риски компрометации данных в случае утечки секрета, используемого при вычислении цифровой подписи уведомления.
- На основании полученного статуса партнер принимает решение об успешности платежа в своей системе.
Сценарий оплаты в пользу провайдера со счета пользователя
Оплата в пользу провайдера может быть совершена:
- по сценарию, описанному в этом разделе;
- по сценарию, описанному в разделе "Сценарий оплаты для остальных видов платежей".
Сценарий проведения платежа зависит от провайдера и на текущий момент определяется необходимостью передавать поле toProviderData.
Используемый для каждого отдельного провайдера сценарий можно уточнить у курирующего менеджера.
- Пользователь инициирует оплату в пользу провайдера (например, пополнение игрового аккаунта или оплату услуг сотовой связи) со своего счета в интерфейсе партнера.
- Партнер отправляет платежный запрос сервису Payments, в котором передает сумму и дополнительные данные, необходимые провайдеру для успешного проведения платежа.
- В случае неуспешной обработки запроса сервис Payments возвращает сервису партнера соответствующий ответ. В случае успешной обработки запроса сервис Payments возвращает сервису партнера статус проведения платежа
PROCESSING
. - Сервис Payments проводит операцию оплаты в пользу провайдера со счета пользователя.
- Партнер получает уведомление, содержащее актуальный статус платежа.
- Если статус платежа принял финальное значение (финальный успешный или финальный неуспешный), партнеру достаточно однократно выполнить соответствующий запрос статуса. Это позволит устранить риски компрометации данных в случае утечки секрета, используемого при вычислении цифровой подписи уведомления.
- На основании полученного статуса партнер принимает решение об успешности платежа в своей системе.
Сценарий оплаты для остальных видов платежей
Сценарий может быть использован для следующих видов платежей (методов API):
- Пополнение счета пользователя с другого счета. Например, выплата партнером бонусов.
- Оплата в пользу провайдера со счета пользователя. Например, покупка товара определенного продавца.
- Перевод между счетами пользователей: p2p-перевод.
- Пользователь инициирует покупку товара/перевод на счет другого пользователя в интерфейсе партнера.
- Партнер отправляет соответствующий запрос сервису Payments.
- Партнер получает ответ от сервиса Payments, на основании которого принимает решение об успешности платежа в своей системе. Партнер может периодически опрашивать сервис Payments соответствующим запросом статуса платежа.
Взаимодействие через API
Пополнение счета пользователя с банковской карты
Партнер использует платежную форму QIWI
См. детализацию сценария пополнения. См. также дополнительную информацию об использовании платежной формы.
Метод используется для пополнения счета пользователя с карты.
Запрос → 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 eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-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 не настроена в сервисе Payments, передавать параметр не нужно. |
||
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 | Дата создания операции в сервисе Payments |
accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в сервисе Payments |
payUrl | String | URL платежной формы, на которую партнеру необходимо перенаправить пользователя для заполнения реквизитов платежа |
status | String | Статус операции в сервисе Payments |
statusDetails | String | Заполнен, если "status": "DECLINED" |
clientCommission | Блок с информацией о комиссии, которая взимается с пользователя | |
value | Number | Значение с двумя десятичными разрядами |
currency | String | Валюта, ISO 4217 |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Статус пополнения счета пользователя с банковской карты
Партнер использует платежную форму QIWI
Метод используется для получения текущего статуса платежа.
Запрос → 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 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.
Пополнение счета пользователя с другого счета
См. также детализацию сценария пополнения.
В качестве счета-источника может быть использован как счет партнера, открытый в QIWI (с целью осуществлять выплаты пользователю), так и счет собственных средств QIWI (зависит от бизнес-сценария).
Метод используется для пополнения счета пользователя.
Запрос → 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 eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-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 Обязательный параметр тела запроса. Идентификатор источника денежных средств: с его счета в сервисе Payments средства будут списаны на счет пользователя |
^[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 | Дата создания операции в сервисе Payments |
accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в сервисе Payments |
status | String | Статус операции в сервисе Payments |
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.
Перевод средств со счета пользователя на банковскую карту
См. также описание сценария перевода.
Метод используется для перевода денежных средств со счета пользователя на банковскую карту.
Запрос → 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 eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-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 не настроена в сервисе Payments, передавать параметр не нужно. |
||
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 | Дата создания операции в сервисе Payments |
accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в сервисе Payments |
status | String | Статус операции в сервисе Payments |
statusDetails | String | Заполнен, если "status": "DECLINED" |
clientCommission | Блок с информацией о комиссии, которая взимается с пользователя | |
value | Number | Значение с двумя десятичными разрядами |
currency | String | Валюта, ISO 4217 |
needClientApprove | Boolean | Если true - пользователю необходимо сообщить о том, что перевод на указанную карту является потенциально подозрительной операцией: получатель денежных средств, возможно, относится к числу финансовых мошенников. Пользователь может отказаться от проведения операции или подтвердить ее исполнение запросом confirmations. |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Получение комиссии по платежу
Метод используется для получения размера комиссии по платежу.
Запрос → 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 | Перевод со счета пользователя на банковскую карту |
Подтверждение перевода средств со счета пользователя на банковскую карту
Метод используется, когда от пользователя требуется явно отказаться от проведения операции или подтвердить ее исполнение. Это необходимо в случае, когда в ответе на создание платежа возвращается "needClientApprove":true
.
Запрос → 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 eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-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.
Получение токена формы перевода средств со счета пользователя на банковскую карту
Метод возвращает токен и 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.
Оплата в пользу провайдера со счета пользователя
Метод используется для совершения оплаты в пользу провайдера со счета пользователя.
См. также детализацию сценария оплаты.
Запрос → PUT
URL /partner/openapi-payment-api/v1/payment/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/payment/products/best-partner/transactions/100
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
"fromClientId": "customerUid4000",
"toProviderId": "uid30",
"toProviderData": {
"fields" : {
"account" : "5886987209"
}
},
"transactionAmount": {
"value": 200.00,
"currency": "RUB"
},
"clientIpAddress": "2001:db8:85a3::8a2e:0370:7334"
}'
Параметр | Описание | 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 Обязательный параметр тела запроса. Идентификатор пользователя, со счета которого происходит списание денежных средств |
^[A-Za-z0-9-]{1,100}$ |
Cnt-123-DEF-456 |
toProviderId | string Обязательный параметр тела запроса. Идентификатор провайдера/услуги, в пользу которого осуществляется платеж. Выдается партнеру при интеграции. |
^[A-Za-z0-9-]{1,100}$ |
Prv-123-DEF-456 |
toProviderData | object Параметр тела запроса. Блок с доп. информацией для успешного проведения платежа |
||
fields | object Параметр тела запроса. Параметры блока toProviderData |
||
account | string Параметр тела запроса. Идентификатор пользователя на стороне провайдера |
^[A-Za-z0-9-]{1,100}$ |
Зависит от toProviderId |
transactionAmount | object Обязательный параметр тела запроса. Блок с информацией о сумме операции |
||
value | number Обязательный параметр тела запроса. Значение с двумя десятичными разрядами |
200.00 |
|
currency | string Обязательный параметр тела запроса. Валюта, ISO 4217 |
RUB |
|
clientIpAddress | string Обязательный параметр тела запроса. IP-адрес, с которого пользователь осуществляет запрос на совершение платежа |
валидный IPv4/IPv6 | 255.255.255.255 |
Ответ ←
Пример ответа
{
"productId": "best-partner",
"transactionId": "a97",
"fromClientId": "customerUid4000",
"toProviderId": "uid30",
"toProviderData": {
"fields" : {
"account" : "5886987209"
}
},
"transactionAmount": {
"currency": "RUB",
"value": 200
},
"creationDateTime": "2018-10-31T18:10:37+03:00",
"accountingDateTime": "2017-09-03T14:30:00+03:00",
"status": "SUCCESS",
"statusDetails": {}
}
Параметр | Тип | Описание |
---|---|---|
productId | String | Идентификатор продукта, в рамках которого совершается платеж: выдается партнеру при интеграции |
transactionId | String | Уникальный идентификатор операции в системе партнера |
fromClientId | String | Идентификатор пользователя, со счета которого происходит списание денежных средств |
toProviderId | String | Идентификатор провайдера/услуги, в пользу которого осуществляется платеж. Выдается партнеру при интеграции. |
toProviderData | Блок с доп. информацией для успешного проведения платежа | |
fields | Параметры блока toProviderData |
|
account | String | Идентификатор пользователя на стороне провайдера |
transactionAmount | Блок с информацией о сумме операции | |
currency | String | Валюта, ISO 4217 |
value | Number | Значение с двумя десятичными разрядами |
creationDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата создания операции в сервисе Payments |
accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в сервисе Payments |
status | String | Статус операции в сервисе Payments |
statusDetails | String | Заполнен, если "status": "DECLINED" |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Идентификатор пользователя на стороне провайдера
Провайдер | Идентификатор |
---|---|
МТС.Сотовая связь | Номер телефона абонента из 10 цифр, без кода страны |
War Thunder | Игровой e-mail |
Статус оплаты в пользу провайдера со счета пользователя
Метод используется для получения текущего статуса платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/payment/products/{productId}/transactions/{transactionId}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/payment/products/best-partner/transactions/100
-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.
Отмена оплаты в пользу провайдера
Отмена оплаты онлайн-методом доступна для платежей в пользу определенных провайдеров.
Доступность отмены для конкретного провайдера toProviderId
можно уточнить у курирующего менеджера.
Создать отмену можно в течение N
часов с момента совершения исходного платежа. Число N
задается в настройках конкретного productId
.
Разрешено максимум X
отмен для одного платежа. Число X
задается в настройках конкретного productId
.
Запрос → PUT
URL /partner/openapi-payment-api/v1/payment/products/{productId}/transactions/{transactionId}/cancellations/{cancellationId}
HEADERS
- Authorization: Bearer SECRET_KEY
- Content-Type: application/json;charset=UTF-8
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/payment/products/best-partner/transactions/100/cancellations/cnl1
-X PUT
-H 'Content-Type: application/json;charset=UTF-8'
-H 'Authorization: Bearer eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-d '{
"cancellationAmount" : {
"value" : 1.00,
"currency" : "RUB"
},
"clientIpAddress" : "174.86.104.67"
}'
Параметр | Описание | 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 |
cancellationId | Обязательный параметр URL запроса. Уникальный идентификатор отмены в системе партнера, значение не должно пересекаться с transactionId в пределах продукта productId |
^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
cancellationAmount | object Обязательный параметр тела запроса. Сумма отмены, возможна полная или частичная отмена исходной операции |
||
value | number Обязательный параметр тела запроса. Значение с двумя десятичными разрядами |
200.00 |
|
currency | string Обязательный параметр тела запроса. Валюта, ISO 4217 |
RUB |
|
clientIpAddress | string Обязательный параметр тела запроса. IP-адрес, с которого пользователь осуществляет запрос на совершение платежа |
валидный IPv4/IPv6 | 255.255.255.255 |
Ответ ←
Пример ответа
{
"productId": "best-partner",
"transactionId": "100",
"cancellationId": "cancel1",
"cancellationAmount": {
"currency": "RUB",
"value": 1.00
},
"cancellationStatus": "SUCCESS",
"cancellationStatusDetails": {},
"cancellationCreatedDateTime": "2020-08-27T15:33:00+03:00",
"cancellationCompletedDateTime": "2020-08-27T15:33:01+03:00"
}
Параметр | Тип | Описание |
---|---|---|
productId | String | Идентификатор продукта, в рамках которого совершается платеж: выдается партнеру при интеграции |
transactionId | String | Уникальный идентификатор операции в системе партнера |
cancellationAmount | Сумма отмены | |
currency | String | Валюта, ISO 4217 |
value | Number | Значение с двумя десятичными разрядами |
cancellationCreatedDateTime | DateTime | Дата создания отмены в Payments в формате ISO 8601 ±hh:mm с московской Time Zone |
cancellationCompletedDateTime | DateTime | Дата перехода операции отмены в финальный статус в сервисе Payments, возвращается в формате ISO 8601 ±hh:mm с московской Time Zone |
cancellationStatus | String | Статус операции в сервисе Payments |
cancellationStatusDetails | String | Заполнен, если "status": "DECLINED" |
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Получение информации по конкретной отмене оплаты в пользу провайдера
Метод используется для получения информации по статусу операции отмены платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/payment/products/{productId}/transactions/{transactionId}/cancellations/{cancellationId}
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/payment/products/best-partner/transactions/100/cancellations/cnl1
-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 |
cancellationId | Обязательный параметр URL запроса. Уникальный идентификатор отмены в системе партнера, значение не должно пересекаться с transactionId в пределах продукта productId |
^[A-Za-z0-9-]{1,100}$ |
Txn-123-DEF-456 |
Ответ ←
См. формат ответа на запрос "Отмена оплаты в пользу провайдера".
Ответ с ошибкой содержит объект с информацией об ошибке. Подробнее см. раздел Формат ошибок API.
Получение информации по всем отменам для оплаты в пользу провайдера
Метод используется для получения информации по статусу всех операций отмены указанного платежа.
Запрос → GET
URL /partner/openapi-payment-api/v1/payment/products/{productId}/transactions/{transactionId}/cancellations
HEADERS
- Authorization: Bearer SECRET_KEY
Параметры запроса
Пример запроса
curl https://api-test.qiwi.com/partner/openapi-payment-api/v1/payment/products/best-partner/transactions/100/cancellations
-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.
Перевод между счетами пользователей
См. детализацию сценария перевода между счетами.
Метод используется для совершения перевода между счетами пользователей.
Запрос → 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 eyJ2ZXJzaW9uIjoicmVzdF92MyIsImRhdGEiOnsibWVyY2hhbnRfaWQiOjIwNDIsImFwaV91c2VyX2lkIjo1NjYwMzk3Miwic2VjcmV0IjoiQjIwODlDNkI5Q0NDNTdCNDQzNGHJK43JFJDK595FJFJMjlCRkFFRDM5OE***********************'
-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 | Дата создания операции в сервисе Payments |
accountingDateTime | DateTime в формате ISO 8601 ±hh:mm с московской Time Zone | Дата перехода операции в финальный статус в сервисе Payments |
status | String | Статус операции в сервисе Payments |
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 | Некорректная сумма: получить комиссию на указанную сумму нельзя |
Платежная форма
Срок жизни
Операция пополнения счета пользователя с банковской карты имеет период, в рамках которого можно воспользоваться пополнением, т. е. совершить оплату на форме.
Значение периода (срока жизни) необходимо уточнять отдельно.
По истечении заданного срока жизни операция из статуса PROCESSING переходит в один из статусов:
- финальный неуспешный — если оплата не была совершена;
- финальный успешный — если оплата была и она успешна.
Возможные значения срока жизни:
- минимум 1 секунда
- максимум 45 дней
Пример: срок жизни установлен в 5 минут. Пользователь находится на форме, затем закрывает ее. Через какое-то время снова возвращается на форму. Совершить оплату этот пользователь сможет только в том случае, если 5 минут с момента создания запроса не истекли.
Способы оплаты
На форме в testing-окружении можно увидеть следующие способы оплаты:
- QIWI-кошелек;
- банковская карта.
В production-окружении на форме доступен единственный способ оплаты — банковская карта.
Редирект с платежной формы
После успешной оплаты пользователя можно вернуть на нужную страницу: например, на сайт партнера.
Необходимо к полученному в ответе значению payUrl добавить новый параметр success_url
или передать необходимое значение success_url
курирующему менеджеру для его настройки в рамках задачи по кастомизации формы.
В параметре success_url
передается адрес, на который будет перенаправлен пользователь. Например, ...&success_url=ya.ru
.
Автоматический редирект происходит после успешной оплаты спустя 3-10 секунд.
При повторном открытии формы (уже после успешной оплаты) перейти на success_url
можно только по нажатию на ссылку внизу формы. Ссылка содержится в строке. Строка имеет следующий вид: Вернуться на сайт {Наименование продукта}.
{Наименование продукта} — информация из сервиса Payments, содержит ссылку на success_url
.
Строка не кастомизируется под каждого отдельного партнера.
Если передавать success_url
— строка появляется на форме, если не передавать — строки на форме не будет.
Кастомизация
Кастомизация позволяет адаптировать платежную форму под стиль партнера. Настраивается лого, фон и цвет кнопок.
Для кастомизации необходимы:
- лого в формате png, svg: размер 310x36 или пропорционально больше;
- цвет фона и цвет кнопок в HEX;
- краткое описание деятельности (максимальная длина 120 символов);
- картинка для фона, размеры 382х560 или пропорционально больше, форматы png, svg.
Дополнительные настройки:
- url успешного платежа;
- ссылка на оферту.
Что не кастомизируется:
- строка с наименованием ссылки редиректа;
- срок жизни;
- белое пространство на форме: его нельзя уменьшить/увеличить.
Можно ли узнать, когда клиент заполнил форму и отправил платеж?
Сервис Payments не знает о том, что клиент:
- заполнил данные;
- подтвердил платеж;
- закрыл платежную форму, не совершив платеж.
Сервис Payments изменит статус платежа только в случае:
- получения оплаты;
- истечения срока жизни запроса на пополнение.
Однако по переходу на success_url
партнер может понять, что пользователь подтвердил платеж на форме и вскоре статус платежа в сервисе Payments изменится на финальный успешный или финальный неуспешный.
Пользователь увидел на форме подтверждение оплаты, но вернулся статус платежа, отличный от успешного
Это может произойти в случае, когда платеж привел к превышению заданного для пользователя лимита. Форма не знает о лимитах.
По этой причине в пользовательском интерфейсе партнера необходимо отображать результаты проведения финансовых операций только на основании ответа на запрос статуса операции пополнения.
Запрет на открытие формы в iFrame на iOS
В Safari с iPhone блокируется запись cookie, если пользователь не был на домене в течении прошлых 30 дней (в том числе с Desktop/iPad).
В QIWI стоит запрет на открытие формы в iFrame на iOS.
Разрешить открывать форму в iFrame только для определенных доменов — на текущий момент не представляется возможным.
Вариант открытия формы в Safari — в отдельном окне.
Для корректного отображения формы должны быть разрешены запись и чтение cookie.
Можно ли сделать автоматический скролл?
Для этого нет специальных настроек. Определяется библиотекой браузера, в котором открывается форма.