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

PAYMENTS API

Последнее обновление: 14-03-2022

API предназначен для партнеров, инициирующих платежи из своего пользовательского интерфейса.

Термины, используемые в тексте:

Взаимодействие между партнёром и сервисом Payments совершается по защищенному протоколу (HTTPS).

Данные в запросах передаются в формате JSON в кодировке UTF-8. В ответе данные возвращаются также в формате JSON в кодировке UTF-8.

Авторизация

Поддерживаются только HTTPS-запросы. HTTP-запросы по нешифрованному каналу не поддерживаются.

Схема аутентификации — Bearer.

В заголовках запроса передаётся bearer-токен в поле Authorization

--header "Authorization: Bearer MjMyNDQxMjM6NDUzRmRnZDQ0M*******"

Bearer-токен выдается партнеру при интеграции.

URL для вызовов API

Сценарии взаимодействия с сервисом

Сценарий пополнения счета пользователя с банковской карты

Партнер использует платежную форму QIWI

  1. Пользователь инициирует пополнение баланса своего счета с банковской карты в интерфейсе партнера. Если для этого типа платежа настроена комиссия, партнер отправляет запрос для получения значения комиссии.
  2. Партнер отправляет платежный запрос сервису Payments, в котором передает сумму платежа и размер полученной ранее комиссии.
  3. В случае неуспешной обработки запроса сервис Payments возвращает сервису партнера соответствующий ответ. В случае успешной обработки запроса сервис Payments возвращает сервису партнера статус проведения платежа PROCESSING и URL платежной формы в поле payUrl.
  4. Партнер перенаправляет пользователя на полученный url для ввода данных банковской карты.
  5. Пользователь указывает данные карты и подтверждает оплату.
  6. Сервис Payments проводит операцию пополнения. При неуспешном проведении операции пополнения пользователю будет предложено повторить операцию с возможностью смены реквизитов банковской карты. При успешном проведении операции на форме оплаты пользователь увидит соответствующее подтверждение.
  7. Партнер получает уведомление, содержащее актуальный статус пополнения.
  8. Если статус пополнения принял финальное значение (финальный успешный или финальный неуспешный), то рекомендуется однократно выполнить соответствующий запрос статуса. Это позволит устранить риски компрометации данных в случае утечки секрета, используемого при вычислении цифровой подписи уведомления.
  9. На основании полученного статуса партнер принимает решение об успешности платежа в своей системе.

Сценарий проведения платежа

Сценарий перевода средств со счета пользователя на банковскую карту

  1. Пользователь инициирует перевод средств со своего счета на банковскую карту в интерфейсе партнера. Если для этого типа платежа настроена комиссия, партнер отправляет запрос для получения значения комиссии. Пользователь видит размер комиссии и подтверждает платеж.
  2. Партнер отправляет платежный запрос сервису Payments, в котором передает сумму платежа и размер полученной ранее комиссии.
  3. В случае неуспешной обработки запроса сервис Payments возвращает сервису партнера соответствующий ответ. В случае успешной обработки запроса сервис Payments возвращает сервису партнера статус проведения платежа PROCESSING и информацию о необходимости подтвердить платеж - needClientApprove.
  4. Если needClientApprove имеет значение true — партнер сообщает пользователю о том, что перевод на указанную карту является потенциально подозрительной операцией: получатель денежных средств, возможно, относится к числу финансовых мошенников. Пользователь отказывается от проведения операции или подтверждает ее исполнение.
  5. Партнер передает сервису Payments отказ или подтверждение пользователя запросом confirmations.
  6. Сервис Payments проводит операцию перевода средств на банковскую карту.
  7. Партнер получает уведомление, содержащее актуальный статус платежа.
  8. Если статус платежа принял финальное значение (финальный успешный или финальный неуспешный), партнеру достаточно однократно выполнить соответствующий запрос статуса. Это позволит устранить риски компрометации данных в случае утечки секрета, используемого при вычислении цифровой подписи уведомления.
  9. На основании полученного статуса партнер принимает решение об успешности платежа в своей системе.

Сценарий проведения платежа

Сценарий оплаты в пользу провайдера со счета пользователя

Оплата в пользу провайдера может быть совершена:

Сценарий проведения платежа зависит от провайдера и на текущий момент определяется необходимостью передавать поле toProviderData.

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

  1. Пользователь инициирует оплату в пользу провайдера (например, пополнение игрового аккаунта или оплату услуг сотовой связи) со своего счета в интерфейсе партнера.
  2. Партнер отправляет платежный запрос сервису Payments, в котором передает сумму и дополнительные данные, необходимые провайдеру для успешного проведения платежа.
  3. В случае неуспешной обработки запроса сервис Payments возвращает сервису партнера соответствующий ответ. В случае успешной обработки запроса сервис Payments возвращает сервису партнера статус проведения платежа PROCESSING.
  4. Сервис Payments проводит операцию оплаты в пользу провайдера со счета пользователя.
  5. Партнер получает уведомление, содержащее актуальный статус платежа.
  6. Если статус платежа принял финальное значение (финальный успешный или финальный неуспешный), партнеру достаточно однократно выполнить соответствующий запрос статуса. Это позволит устранить риски компрометации данных в случае утечки секрета, используемого при вычислении цифровой подписи уведомления.
  7. На основании полученного статуса партнер принимает решение об успешности платежа в своей системе.

Сценарий проведения платежа

Сценарий оплаты для остальных видов платежей

Сценарий может быть использован для следующих видов платежей (методов API):

  1. Пользователь инициирует покупку товара/перевод на счет другого пользователя в интерфейсе партнера.
  2. Партнер отправляет соответствующий запрос сервису Payments.
  3. Партнер получает ответ от сервиса Payments, на основании которого принимает решение об успешности платежа в своей системе. Партнер может периодически опрашивать сервис Payments соответствующим запросом статуса платежа.

Сценарий проведения платежа

Взаимодействие через API

Пополнение счета пользователя с банковской карты

Партнер использует платежную форму QIWI

См. детализацию сценария пополнения. См. также дополнительную информацию об использовании платежной формы.

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

Запрос → PUT

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

curl https://api-test.qiwi.com/partner/openapi-commissions/v1/products/best-partner/{txnType}?clientId=1&value=100.99&currency=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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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

Пример запроса

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 содержит:

В поле 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 переходит в один из статусов:

Возможные значения срока жизни:

Пример: срок жизни установлен в 5 минут. Пользователь находится на форме, затем закрывает ее. Через какое-то время снова возвращается на форму. Совершить оплату этот пользователь сможет только в том случае, если 5 минут с момента создания запроса не истекли.

Способы оплаты

На форме в testing-окружении можно увидеть следующие способы оплаты:

В production-окружении на форме доступен единственный способ оплаты — банковская карта.

Редирект с платежной формы

После успешной оплаты пользователя можно вернуть на нужную страницу: например, на сайт партнера.

Необходимо к полученному в ответе значению payUrl добавить новый параметр success_url или передать необходимое значение success_url курирующему менеджеру для его настройки в рамках задачи по кастомизации формы.

В параметре success_url передается адрес, на который будет перенаправлен пользователь. Например, ...&success_url=ya.ru.

Автоматический редирект происходит после успешной оплаты спустя 3-10 секунд.

При повторном открытии формы (уже после успешной оплаты) перейти на success_url можно только по нажатию на ссылку внизу формы. Ссылка содержится в строке. Строка имеет следующий вид: Вернуться на сайт {Наименование продукта}.

{Наименование продукта} — информация из сервиса Payments, содержит ссылку на success_url.

Строка не кастомизируется под каждого отдельного партнера. Если передавать success_url — строка появляется на форме, если не передавать — строки на форме не будет.

Кастомизация

Кастомизация позволяет адаптировать платежную форму под стиль партнера. Настраивается лого, фон и цвет кнопок.

Для кастомизации необходимы:

Дополнительные настройки:

Customer form

Что не кастомизируется:

Можно ли узнать, когда клиент заполнил форму и отправил платеж?

Сервис Payments не знает о том, что клиент:

Сервис Payments изменит статус платежа только в случае:

Однако по переходу на success_url партнер может понять, что пользователь подтвердил платеж на форме и вскоре статус платежа в сервисе Payments изменится на финальный успешный или финальный неуспешный.

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

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

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

Запрет на открытие формы в iFrame на iOS

В Safari с iPhone блокируется запись cookie, если пользователь не был на домене в течении прошлых 30 дней (в том числе с Desktop/iPad).

В QIWI стоит запрет на открытие формы в iFrame на iOS.

Разрешить открывать форму в iFrame только для определенных доменов — на текущий момент не представляется возможным.

Вариант открытия формы в Safari — в отдельном окне.

Для корректного отображения формы должны быть разрешены запись и чтение cookie.

Можно ли сделать автоматический скролл?

Для этого нет специальных настроек. Определяется библиотекой браузера, в котором открывается форма.

Примеры