Перейти к содержанию

Оплата с формы QIWI с помощью API

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

Партнёру доступны несколько сценариев приёма платежей с помощью формы и API QIWI:

  • одношаговый — когда авторизация и подтверждение платежа выполняются в рамках одного запроса;
  • двухшаговый — когда авторизация и подтверждение платежа выполняются двумя отдельными запросами.

При выполнении одношагового сценария средства клиента холдируются и сразу же списываются после нажатия кнопки оплаты на форме QIWI. Отменить списание технически невозможно, доступен лишь возврат средств.

При выполнении двухшагового сценария средства клиента холдируются после нажатия кнопки оплаты на форме QIWI и списываются только после получения подтверждения от партнёра. Холдирование средств можно отменить, списанные средства можно вернуть.

Начало работы

① Выполните шаги, указанные в статье «Интернет-эквайринг» → «Начало работы»

② Выпустите ключ доступа к API приёма платежей

Ключ доступа к API — cимвольная строка для авторизации запросов к API согласно стандарту OAuth 2.0 RFC 6749, RFC 6750В. Выпускается в личном кабинете в разделе «Настройки».

③ Протестируйте взаимодействие

Отправленный вам siteId по умолчанию находится в тестовом режиме. В этом режиме вы можете проводить операции без реального движения денежных средств. Подробности см. в статье «Тестовый режим».

Одношаговый сценарий

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

Обратите внимание

Все способы оплаты, кроме оплаты с банковской карты, подключаются по запросу: оплата с банковской карты доступна по умолчанию, для подключения остальных способов обратитесь в службу поддержки.

  1. Клиент выбирает товар или услугу на торговой площадке партнёра, переходит к оплате.
  2. Партнёр отправляет QIWI запрос на создание счёта, в котором передаёт сумму платежа, срок жизни счёта и признак одношагового проведения платежа (flags:[SALE]).

    Если не передать flags:[SALE], платёж будет проведён по двушаговому сценарию: средства клиента будут захолдированы после нажатия кнопки оплаты и списаны только после получения подтверждения от партнёра.

  3. QIWI возвращает партнёру статус счёта (CREATED — создан, ожидает оплаты), а также URL-адрес платёжной формы QIWI payUrl.

  4. Партнёр направляет клиента на полученный payUrl.

    Альтернативный вариант — использование библиотеки Checkout Popup для открытия формы во всплывающем окне.

  5. Клиент выбирает способ оплаты, указывает платёжные данные и нажимает «Оплатить».

  6. QIWI проводит аутентификацию клиента с помощью 3D-Secure.
  7. QIWI с помощью платёжной системы отправляет запрос на авторизацию и подтверждение платежа в банк-эмитент.
  8. Банк-эмитент резервирует (холдирует) и сразу же списывает денежные средства с карты клиента.
  9. QIWI фиксирует успешное завершение платежа — оплаты счёта.

    Опциональные шаги

    П.10 является опциональным и выполняется лишь в том случае, если для партнёра настроен successUrl. Подробности см. в статье «Платёжная форма» → «URL-адрес страницы для успешного платежа».

  10. Форма QIWI направляет клиента на «URL-адрес страницы для успешного платежа».

  11. Партнёр принимает решение об успешности завершения платежа — выполняет действия, указанные в статье «Общие принципы и правила» → «Решение об успешности операции».
%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        60 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant Q as QIWI
    participant B as Банк-эмитент
    С->>P: Выбор товара или услуги
    Note right of С: Переход к оплате
    P->>+Q: Запрос на создание счёта
    Note right of P: siteId, billId, amount, expirationDateTime, flags: SALE
    Q->>-P: Ответ на запрос создания счёта
    Note left of Q: siteId, billId, amount, invoiceUid, status:CREATED, expirationDateTime, payUrl
    P->>С: Направление на payUrl
    Note left of P: Платёжная форма
    rect rgb(230, 230, 230)
    С->>С: Заполнение данных на форме
    С->>Q: Выполнение кода (вызов API формой)
    rect rgb(255, 238, 223)
    Q->>+С: Аутентификация клиента с помощью 3D-Secure
    С->>-Q: 
    end
    Q->>+B: Запрос на авторизацию и подтверждение платежа
    Note right of Q: Через платёжную систему
    B->>B: HOLD
    B->>B: CAPTURE
    B->>-Q: Ответ на запрос
    Note left of B: ОК
    Q->>Q: Завершение платежа (оплаты счёта)
    Q->>С: Отображение результата на форме
    Note right of С: «Платёж успешен»
    opt Направление на URL-адрес successUrl (опционально)
    С->>P: 
    Note left of P: Страница статуса платежа в интерфейсе партнёра
    end
    end
    rect rgb(255, 238, 223)
    Q->>P: Сценарий «Принятие решения об успешности операции»
    P->>Q: 
    end

Элемент диаграммы QIWI — совокупность участников процесса проведения платежа. Указанные на диаграмме сценарии см. в статьях:

Обратите внимание

Партнёр не получает, не обрабатывает и не хранит данные карты клиента. Это делает форма QIWI. Данный этап выделен на схеме серым цветом.

PUT /partner/payin/v1/sites/test-00/bills/1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "amount": {
        "currency": "RUB",
        "value": 150.00
    },
    "comment": "Spasibo",
    "expirationDateTime": "2023-07-07T14:30:00+03:00",
    "flags": [
        "SALE"
    ]
}
HTTP/1.1 200 OK
Content-Type: application/json

{
    "billId": "1234567890",
    "invoiceUid": "143a6822-6ef2-478f-a30b-4ad8c044d6d8",
    "amount": {
        "currency": "RUB",
        "value": "150.00"
    },
    "expirationDateTime": "2023-07-07T14:30:00+03:00",
    "status": {
        "value": "CREATED",
        "changedDateTime": "2023-02-17T14:50:44+03:00"
    },
    "comment": "Spasibo",
    "flags": [
        "SALE"
    ],
    "payUrl": "https://oplata.qiwi.com/form?invoiceUid=143a6822-6ef2-478f-a30b-4ad8c044d6d8"
}

Запросы и ответы приведены в качестве примера: актуальные формат и список параметров см. в разделе «Справочник методов API» документации API приёма платежей.

Двухшаговый сценарий

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

Обратите внимание

Двухшаговый сценарий позволяет использовать лишь один способ оплаты — с банковской карты.

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

  3. QIWI возвращает партнёру статус счёта (CREATED — создан, ожидает оплаты), а также URL-адрес платёжной формы QIWI payUrl.

  4. Партнёр направляет клиента на полученный payUrl.

    Альтернативный вариант — использование библиотеки Checkout Popup для открытия формы во всплывающем окне.

  5. Клиент выбирает способ оплаты, указывает платёжные данные и нажимает «Оплатить».

  6. QIWI проводит аутентификацию клиента с помощью 3D-Secure.
  7. QIWI с помощью платёжной системы отправляет запрос на авторизацию платежа в банк-эмитент.
  8. Банк-эмитент резервирует (холдирует) денежные средства на карте клиента.
  9. QIWI фиксирует успешную оплату счёта.

    Опциональные шаги

    П.10 является опциональным и выполняется лишь в том случае, если для партнёра настроен successUrl. Подробности см. в статье «Платёжная форма» → «URL-адрес страницы для успешного платежа».

  10. Форма QIWI направляет клиента на «URL-адрес страницы для успешного платежа».

  11. Партнёр принимает решение об успешности оплаты счёта (авторизации платежа) — выполняет действия, указанные в статье «Общие принципы и правила» → «Решение об успешности операции».

    На этапе получения уведомления у партнёра появляется идентификатор платежа, который он должен подтвердить — paymentId. Данный индентификатор также можно получить в ответ на запрос списка платежей по счёту.

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

    Сбор заказа и т.п.

  13. Партнёр отправляет QIWI запрос на подтверждение платежа, в котором передаёт полученный на этапе 11 идентификатор платежа.

    По умолчанию QIWI ожидает подтверждения платежа в течение 72 часов с момента его успешной авторизации — оплаты счёта. По истечении этого срока платёж подтверждается автоматически. Для изменения длительности ожидания или настройки автоматической отмены платежа обратитесь в службу поддержки. Длительность ожидания не может превышать 5 суток.

  14. QIWI с помощью платёжной системы отправляет запрос на подтверждение платежа в банк-эмитент.

  15. Банк-эмитент списывает денежные средства с карты клиента.
  16. QIWI фиксирует успешное завершение платежа.
  17. Партнёр принимает решение об успешности завершения платежа — выполняет действия, указанные в статье «Общие принципы и правила» → «Решение об успешности операции».
%%{init: {
    "sequence" : {
        "wrap":true,
        "messageFontSize":14,
        "noteFontSize":12,
        "actorMargin":
        60 }}}%%
sequenceDiagram
    participant С as Клиент
    participant P as Партнёр
    participant Q as QIWI
    participant B as Банк-эмитент
    С->>P: Выбор товара или услуги
    Note right of С: Переход к оплате
    P->>+Q: Запрос на создание счёта
    Note right of P: siteId, billId, amount, expirationDateTime, `flags: SALE`
    Q->>-P: Ответ на запрос создания счёта
    Note left of Q: siteId, billId, amount, invoiceUid, status:CREATED, expirationDateTime, payUrl
    P->>С: Направление на `payUrl`
    Note left of P: Платёжная форма
    rect rgb(230, 230, 230)
    С->>С: Заполнение данных на форме
    С->>Q: Выполнение кода (вызов API формой)
    rect rgb(255, 238, 223)
    Q->>+С: Аутентификация клиента с помощью 3D-Secure
    С->>-Q: 
    end
    Q->>+B: Запрос на авторизацию платежа
    Note right of Q: Через платёжную систему
    B->>B: HOLD
    B->>-Q: Результат авторизации
    Note left of B: ОК
    Q->>Q:  Статус оплаты счёта
    Note over Q: ОК
    Q->>С: Отображение результата на форме
    Note right of С: «Оплата успешна»
    opt Направление на URL-адрес successUrl (опционально)
    С->>P: 
    Note left of P: Страница статуса оплаты в интерфейсе партнёра
    end
    end
    rect rgb(255, 238, 223)
    Q->>P: Сценарий «Принятие решения об успешности операции»
    Note left of Q: paymentId
    P->>Q: 
    end
    P->>С: Коммуникация с клиентом
    Note left of P: Заказ собирается
    P->>P: Сбор заказа
    Note over P: Заказ готов к отправке
    P->>+Q: Запрос на подтверждение платежа
    Note right of P: siteId, paymentId, captureId
    Q->>+B: Запрос на подтверждение платежа
    Note right of Q: Через платёжную систему
    B->>B: CAPTURE
    B->>-Q: Результат
    Note left of B: ОК
    Q->>Q:  Статус платежа
    Note over Q: COMPLETED
    Q->>-P: Ответ на запрос подтверждения
    Note left of Q: siteId, paymentId, captureId, amount, status: COMPLETED
    rect rgb(255, 238, 223)
    Q->>P: Сценарий «Принятие решения об успешности операции»
    Note left of Q: paymentId
    P->>Q: 
    end
    P->>С: Коммуникация с клиентом
    Note left of P: Заказ отправлен

Элемент диаграммы QIWI — совокупность участников процесса проведения платежа. Указанные на диаграмме сценарии см. в статьях:

Обратите внимание

Партнёр не получает, не обрабатывает и не хранит данные карты клиента. Это делает форма QIWI. Данный этап выделен на схеме серым цветом.

PUT /partner/payin/v1/sites/test-00/bills/1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
    "amount": {
        "currency": "RUB",
        "value": 150.00
    },
    "comment": "Spasibo",
    "expirationDateTime": "2023-07-07T14:30:00+03:00"
}
PUT /partner/payin/v1/sites/test-00/payments/804900/capture/cap1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

Пример ответа на запрос создания счёта см. в разделе «Одношаговый сценарий».

Запросы и ответы приведены в качестве примера: актуальные формат и список параметров см. в разделе «Справочник методов API» документации API приёма платежей.

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

Cпособы оплаты настраиваются для определённого siteId и отображаются на форме QIWI в зависимости от выполнения некоторых условий (см. таблицу ниже). Оплата с банковской карты доступна по умолчанию.

Условие Результат
• Служба поддержки не подключала никаких способов оплаты по запросу
• При выполнении одношагового или двухшагового сценария в запросе на создание счёта отсутствует параметр billPaymentMethodsType
На форме доступен лишь один способ оплаты — банковской картой
• Служба поддержки не подключала никаких способов оплаты по запросу
• При выполнении одношагового или двухшагового сценария в запросе на создание счёта передан параметр billPaymentMethodsType со списком способов оплаты
На форме доступен лишь один способ оплаты — банковской картой. Способы из billPaymentMethodsType не учитываются при отображении формы
Служба поддержки получила запрос на подключение определённых способов оплаты и подключила запрошенные способы
• При выполнении одношагового или двухшагового сценария в запросе на создание счёта отсутствует параметр billPaymentMethodsType
На форме доступны все подключенные службой поддержки способы оплаты
Служба поддержки получила запрос на подключение определённых способов оплаты и подключила запрошенные способы
• При выполнении одношагового или двухшагового сценария в запросе на создание счёта передан параметр billPaymentMethodsType со списком способов оплаты
На форме доступны способы оплаты, указанные в billPaymentMethodsType. Подключенные службой поддержки способы оплаты не учитываются при отображении формы

Оплата с помощью платёжного токена

Клиент может оплатить заказ без ввода платёжных реквизитов. Оплата в этом случае совершается с помощью платёжного токена. Для подключения этого способа оплаты обратитесь в службу поддержки.

Выпуск платёжного токена описан в статье «Платёжный токен».

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

Оплата с помощью платёжного токена может быть реализована путём выполнения одношагового или двухшагового сценария: в запросе на создание счёта необходимо передать идентификатор клиента, для которого выпущен токен (параметр customer.account). Без указания customer.account оплата платёжным токеном невозможна.

Запрос на создание счёта для оплаты токеном
PUT /partner/payin/v1/sites/test-02/bills/1815 HTTP/1.1
Accept: application/json
Authorization: Bearer 7uc4b25xx93xxx5d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

{
   "amount": {
     "currency": "RUB",
     "value": 100.00
   },
   "comment": "Text comment",
   "expirationDateTime": "2018-04-13T14:30:00+03:00",
   "customer": {
     "account": "token234"
   },
   "customFields": {
    "cf1": "Some data"
   }
}

Запрос приведён в качестве примера: актуальные формат и список параметров см. в разделе «Справочник методов API» документации API приёма платежей.

Если для клиента выпущен один или несколько токенов, на форме QIWI отображается список привязанных платёжных инструментов.

PAY-FORM

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