Платеж через форму мерчанта {#merchant-api-integration}

При интеграции карточных платежей со своей платежной формой вы отправляете в API запросы с полными номерами карт и кодом CVV/CVV2. Это допускается только при наличии PCI DSS сертификата у вашей организации.

PCI DSS — стандарт информационной безопасности, принятый в индустрии платежных карт Visa и Mastercard. Соблюдать требования стандарта обязаны все компании, которые принимают карты к оплате.

Согласно требованиям Банка России 13-МР от 12.10.2023 выполняется проверка соответствия фактической деятельности партнёра заявленной им при заключении договора. Для этого, а также для снижения риска недействительных и мошеннических операций, партнёру требуется интегрировать скрипт, разработанный для сбора дополнительных данных о клиенте при совершении платежей.

При подключении платежей через собственную платежную форму по умолчанию доступен только способ оплаты Банковские карты. Другие способы оплаты доступны по запросу:

Платежные токены карт.
Система Быстрых Платежей (СБП).

Процесс платежа {#flow-payment-merchant-form}

sequenceDiagram participant customer as Покупатель participant store as Магазин participant qb as QIWI (эквайер) participant ips as Эмитент customer->>store:Выбор товаров, Старт оплаты,
ввод платежных данных activate store store->>qb:API: запрос "Платеж"
Одношаговый платеж — все способы оплаты
Двухшаговый платеж — только карты activate qb qb->>store:Статус операции, данные для 3DS или QR-код СБП rect rgb(255, 238, 223) Note over customer, ips:3-D Secure store->>customer:Переадресация покупателя на acsUrl
или в приложение банка (СБП) activate ips ips->>customer:Аутентификация покупателя:
3DS — карты,
СБП — подтверждение операции в интерфейсе эмитента карты customer->>ips:Аутентификация ips->>store:Результат аутентификации (PaRes) store->>qb:API: запрос "Завершение аутентификации клиента" end qb->>ips:Запрос списания денежных средств activate ips ips->>qb:Статус операции qb->>store:Уведомление о статусе операции store->>qb: Проверка статуса операции
API: запрос "Статус платежа" qb->>store: Статус операции rect rgb(255, 238, 223) Note over store, ips:Двухшаговый платеж store->>qb:Подтверждение операции (capture) qb->>ips:Подтверждение списания deactivate ips qb->>store:Уведомление о подтверждении платежа store->>qb: Проверка статуса операции
API: запрос "Статус подтверждения" qb->>store: Статус операции end deactivate qb deactivate store

Чтобы создать платеж, передайте в запросе API Платеж:

ключ доступа к API;
сумму платежа;
метод платежа;
другую информацию для создания платежа.

Банковская карта {#merchant-form-card}

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

Создание платежа {#merchant-form-hold}

Пример платежа с холдированием (двухшаговый платеж)

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  }
}

Пример платежа с немедленной оплатой (одношаговый платеж)

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  },
  "flags": [ "SALE" ]
}

Чтобы инициировать платеж с предварительным холдированием средств на карте (двухшаговый платеж), передайте в запросе API Платеж:

ключ доступа к API;
сведения о сумме платежа;
параметры метода платежа в объекте paymentMethod:
- type — CARD;
- pan — номер карты;
- expiryDate – срок действия карты в формате MM/YY;
- cvv2 — CVV2/CVC2 карты;
- holderName – имя владельца карты (латиница);
другую информацию о платеже.

Если карта, указанная клиентом, была ранее сохранена (токенизирована) на стороне мерчанта, должны быть добавлены дополнительные параметры в объекте paymentMethod:

cardTokenPaymentType – параметр для корректной обработки транзакций в платежных системах для операций с сохраненными картами. Возможные значения:
- FIRST_PAYMENT — если после этой операции мерчант сохранит карту на своей стороне.
- INITIATED_BY_CLIENT — транзакция по сохраненной карте инициирована клиентом.
- INITIATED_BY_MERCHANT — транзакция по сохраненной карте инициирована мерчантом.
- RECURRING_PAYMENT — повторяющаяся операция по сохраненной карте.
- INSTALLMENT — повторяющаяся операция по сохраненной карте в соответствии с графиком платежей для погашения кредита.
firstTransaction – (опционально) JSON-объект, содержащий сведения об идентификаторе транзакции, в которой ранее была привязана карта. Содержит параметры:
- paymentId – уникальный идентификатор платежа в информационной системе ТСП;
- trnId – уникальный идентификатор платежа в информационной системе НСПК.

В двухшаговом платеже возмещение формируется только после подтверждения платежа.

По умолчанию, при холдировании сервис QIWI ожидает подтверждения платежа в течение 72 часов. По истечении срока выполняется автоподтверждение платежа. Чтобы увеличить или уменьшить период ожидания, или настроить автоотмену платежа обратитесь в Службу поддержки. Период ожидания не может длиться более 5 суток.

Для одношагового платежа без холдирования укажите в запросе API Платеж параметр "flags":["SALE"]. Если не передать этот параметр, то будет выполнено безусловное холдирование средств для выполнения платежа и сервис будет ожидать подтверждения платежа.

Ожидание аутентификации покупателя (3-D Secure) {#merchant-threeds}

Пример ответа с требованием аутентификации покупателя

{
    "paymentId": "1811",
    "billId": "autogenerated-a29ea8c9-f9d9-4a60-87c2-c0c4be9affbc",
    "createdDateTime": "2019-08-15T13:28:26+03:00",
    "amount": {
        "currency": "RUB",
        "value": 1.00
    },
    "capturedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "refundedAmount": {
        "currency": "RUB",
        "value": 0.00
    },
    "paymentMethod": {
        "type": "CARD",
        "maskedPan": "444444******1049",
        "rrn": "123",
        "authCode": "181218",
        "type": "CARD"
    },
    "status": {
        "value": "WAITING",
        "changedDateTime": "2019-08-15T13:28:26+03:00"
    },
    "requirements" : {
        "threeDS" : {
          "pareq" : "eJyrrgUAAXUA+Q==",
          "acsUrl" : "https://test.paymentgate.ru/acs/auth/start.do"
        }
    }
}

Перенаправление для аутентификации 3-D Secure

<form name="form" action="{ACSUrl}" method="post" >
        <input type="hidden" name="TermUrl" value="{TermUrl}" >
        <input type="hidden" name="MD" value="{MD}" >
        <input type="hidden" name="PaReq" value="{PaReq}" >
</form>

Завершение аутентификации покупателя

POST /partner/payin/v1/sites/test-01/payments/1811/complete HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
  "threeDS": {
    "pares": "eJzVWFevo9iyfu9fMZrzaM0QjWHk3tIiGptgooE3cgabYMKvv3jvTurTc3XOfbkaJMuL...."
  }
}

Если требуется 3-D Secure аутентификация покупателя, в ответе на запрос платежа добавляется объект requirements.threeDS с полями:

acsUrl — URL сервера аутентификации 3-D Secure, для перенаправления на страницу подтверждения от эмитента;
pareq — зашифрованный запрос на аутентификацию 3-D Secure.

Для дополнительной проверки покупателя у эмитента выполните POST-запрос на URL сервера аутентификации 3-D Secure с параметрами:

TermUrl — URL перенаправления покупателя после успешной аутентификации 3-D Secure;
MD — уникальный идентификатор транзакции;
PaReq — значение параметра pareq из ответа на платежный запрос.

Чтобы сохранять обратную совместимость, использование протокола 3-D Secure 1.0 или 3-D Secure 2.0 не влияет на интеграцию ТСП с API QIWI.

Далее информация о покупателе передаётся в платежную систему карты. Банк-эмитент либо предоставляет разрешение на списание средств без аутентификации (frictionless flow), либо принимает решение о необходимости аутентификации с помощью одноразового пароля (challenge flow). После прохождения проверки покупатель перенаправляется по адресу TermUrl с зашифрованным результатом проверки в параметре PaRes.

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

уникальный ID мерчанта;
номер платежа (параметр paymentId) из ответа на запрос платежа;
результат 3-D Secure (значение параметра PaRes).

Подтверждение платежа {#merchant-capture}

Пример уведомления

{
  "payment":{
    "paymentId":"804900",  <==paymentId, необходимый для подтверждения
    "type":"PAYMENT",
    "createdDateTime":"2020-11-28T12:58:49+03:00",
    "status":{
        "value":"SUCCESS",
        "changedDateTime":"2020-11-28T12:58:53+03:00"
    },
    "amount":{
      "value":100.00,
      "currency":"RUB"
    },
    "paymentMethod":{
      "type":"CARD",
      "maskedPan":"444444XXXXXX4444",
      "rrn":null,
      "authCode":null,
      "type":"CARD"
    },
    "merchantSiteUid":"test-00",
    "customer":{
      "phone":"75167693659"
    },
    "gatewayData":{
      "type":"ACQUIRING",
      "eci":"6",
      "authCode":"181218"
    },
    "billId":"autogenerated-a51d0d2c-6c50-405d-9305-bf1c13a5aecd",
    "flags":[]
  },
  "type":"PAYMENT",
  "version":"1"
}

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

PUT /partner/payin/v1/sites/{siteId}/payments/804900/captures/bxwd8096 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

Это действие требуется только для двухшагового платежа с холдированием.

Чтобы подтвердить платеж:

Получите paymentId платежа:
- Из серверного уведомления после успешного холдирования средств.
- Из ответа на запрос Статус платежа.
Отправьте запрос API Подтверждение платежа и укажите в нём полученный paymentId.

Платежный токен {#merchant-token-pay}

Использование платежного токена в запросе платежа

PUT /partner/payin/v1/sites/test-02/payments/1815 HTTP/1.1
Accept: application/json
Authorization: Bearer 7uc4b25xx93xxx5d9cb8cd17480356f9
Content-type: application/json
Host: b2b-api.qiwi.com

{
  "amount": {
    "currency": "RUB",
    "value": 2000.00
  },
  "paymentMethod" : {
    "type": "TOKEN",
    "paymentToken" : "66aebf5f-098e-4e36-922a-a4107b349a96"
  },
  "customer": {
        "account": "token324"
  }
}

Платежные токены используются для списаний с карт без ввода реквизитов карты. Метод оплаты платежным токеном по умолчанию отключен. Чтобы подключить его, обратитесь к вашему курирующему менеджеру.

При оплате платёжным токеном покупатель не будет указывать свои карточные данные и проходить проверку 3-D Secure.

О выпуске платежного токена см. подробнее в этом разделе.

Покупатель может совершать оплату только на том сайте, для которого был выпущен платежный токен.

Чтобы платежный токен действовал на других сайтах, отправьте запрос в Службу поддержки.

Чтобы инициировать платёж с оплатой платежным токеном, передайте в запросе API Платеж:

ключ доступа к API;
сведения о сумме платежа;
параметры метода платежа в объекте paymentMethod:
- type — TOKEN;
- paymentToken — строка платежного токена;
дополнительная информация о транзакции по сохраненной карте в объекте paymentMethod:
- cardTokenPaymentType – параметр для корректной обработки транзакций в платежных системах для операций с сохраненными картами. Возможные значения:
  - INITIATED_BY_CLIENT — транзакция по сохраненной карте инициирована клиентом.
  - INITIATED_BY_MERCHANT — транзакция по сохраненной карте инициирована мерчантом.
  - RECURRING_PAYMENT — повторяющаяся операция по сохраненной карте.
  - INSTALLMENT — повторяющаяся операция по сохраненной карте в соответствии с графиком платежей для погашения кредита.
- firstTransaction – JSON-объект, содержащий сведения об идентификаторе транзакции, на которой была привязана карта. Содержит параметры:
  - paymentId – уникальный идентификатор платежа в информационной системе ТСП;
  - trnId – уникальный идентификатор платежа в информационной системе НСПК.
customer.account — идентификатор покупателя в системе ТСП, для которого выпущен платежный токен. Без этого параметра оплата платежным токеном невозможна.
другую информацию о платеже.

Оплата через СБП {#merchant-form-sbp}

Протокол приема платежей поддерживает списание средств с покупателя через Систему быстрых платежей (СБП). Через СБП можно выполнять платежи в пользу юридических лиц, в том числе с использованием QR-кодов.

По умолчанию прием оплаты через СБП отключен. Чтобы подключить этот способ оплаты, обратитесь к вашему курирующему менеджеру.

Получение QR-кода {#qr-sbp}

Пример тела запроса для платежа через СБП

{
  "amount": {
    "value": 100.00,
    "currency": "RUB"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
      "mediaType": "image/png",
      "width": 300,
      "height": 300
    }
  },
  "paymentPurpose": "Flower for my girlfriend",
  "redirectUrl": "http://someurl.com"
}

Пример ответа c QR-кодом

{
  "qrCodeUid": "Test12",
  "amount": {
    "currency": "RUB",
    "value": "100.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "image": {
        "mediaType": "image/png",
        "width": 300,
        "height": 300,
        "content": "iVBORw0KGgoAAAANSUhEUgAAASwAAAEsCAYAA"
    },
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "CREATED"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

При оплате через СБП покупатель сканирует QR-код и получает ссылку на платеж, которую можно открыть в приложении своего банка.

Для выпуска QR-кода СБП отправьте запрос API Получение QR-кода СБП. В запросе укажите:

Уникальный идентификатор запроса.
Объект qrCode с характеристиками запрашиваемого QR-кода:
- Тип QR-кода в параметре qrCode.type:
  - DYNAMIC — динамический QR-код, индивидуальный для каждой оплаты.
- Срок действия кода в минутах в параметре qrCode.ttl. По истечении срока QR-код деактивируется. По умолчанию срок действия 72 часа.
- Тип и размер изображения QR-кода в блоке qrCode.image.
Сумму платежа в блоке amount.
Параметр paymentPurpose с описанием платежа. Если не указан, в приложении банка покупателя отобразится название магазина ТСП.

В ответе на запрос в объекте qrCode содержатся данные QR-кода:

image.content — base64-encoded QR-код. После расшифровки вы получите изображение для отображения покупателю.
payload — URL-based QR для перенаправления покупателя в приложение банка.

Статус платежа через СБП {#sbp-status}

После перехода платежа в финальный статус вы получите уведомление с указанным в исходном запросе идентификатором выпуска QR-кода в поле qrCodeUid. Актуальный статус платежа по идентификатору платежа paymentId из уведомления можно получить через API.

Статус QR-кода {#qr-code-status}

Пример ответа на запрос статуса QR-кода

{
  "qrCodeUid": "Test",
  "amount": {
    "currency": "RUB",
    "value": "1.00"
  },
  "qrCode": {
    "type": "DYNAMIC",
    "ttl": 999,
    "payload": "https://qr.nspk.ru/AD10006M8KH234K782OQM0L13JI31LQDtype=02bank=100000000009&sum=200&cur=RUB&crc=C63A",
    "status": "PAYED"
  },
  "payment": {
    "paymentUid": "A22231710446971300200933E625FCB3",
    "paymentStatus": "COMPLETED"
  },
  "createdOn": "2022-08-11T20:10:32+03:00"
}

Используйте запрос Статус QR-кода СБП. В ответе возвращается информация о QR-коде, в том числе его текущий статус. Так вы можете определить действует ли QR-код.

Оплата токеном через СБП {#token-sbp-payment}

Пример тела запроса оплаты токеном СБП

{
  "tokenizationAccount": "customer123",
  "token": "c5ba4a05-21c9-4a36-af7a-b709b4caa4d6"
}

О выпуске платежного токена читайте подробнее в этом разделе.

Покупатель может совершать оплату только на том сайте, для которого был выпущен платежный токен.

Чтобы платежный токен действовал на других сайтах, отправьте запрос в Службу поддержки.

Воспользуйтесь методом API Платеж токеном СБП и передайте в запросе:

платежный токен в параметре token,
идентификатор покупателя, для которого был выпущен платежный токен, в параметре tokenizationAccount.

Тестирование оплаты СБП {#test-sbp}

См. информацию в этом разделе.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Платеж через форму мерчанта {#merchant-api-integration}

Процесс платежа {#flow-payment-merchant-form}

Банковская карта {#merchant-form-card}

Создание платежа {#merchant-form-hold}

Ожидание аутентификации покупателя (3-D Secure) {#merchant-threeds}

Подтверждение платежа {#merchant-capture}

Платежный токен {#merchant-token-pay}

Оплата через СБП {#merchant-form-sbp}

Получение QR-кода {#qr-sbp}

Статус платежа через СБП {#sbp-status}

Статус QR-кода {#qr-code-status}

Оплата токеном через СБП {#token-sbp-payment}

Тестирование оплаты СБП {#test-sbp}

Uh oh!

FilesExpand file tree

_merchant-form_ru.html.md

Latest commit

History

_merchant-form_ru.html.md

File metadata and controls

Платеж через форму мерчанта {#merchant-api-integration}

Процесс платежа {#flow-payment-merchant-form}

Банковская карта {#merchant-form-card}

Создание платежа {#merchant-form-hold}

Ожидание аутентификации покупателя (3-D Secure) {#merchant-threeds}

Подтверждение платежа {#merchant-capture}

Платежный токен {#merchant-token-pay}

Оплата через СБП {#merchant-form-sbp}

Получение QR-кода {#qr-sbp}

Статус платежа через СБП {#sbp-status}

Статус QR-кода {#qr-code-status}

Оплата токеном через СБП {#token-sbp-payment}

Тестирование оплаты СБП {#test-sbp}