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

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

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

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

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

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

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

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

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

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

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

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

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 — совокупность участников процесса проведения платежа. Указанные на диаграмме сценарии см. в статьях:

• «3D-Secure»;
• «Общие принципы и правила» → «Решение об успешности операции».

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"
}

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

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

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 — совокупность участников процесса проведения платежа. Указанные на диаграмме сценарии см. в статьях:

• «3D-Secure»;
• «Общие принципы и правила» → «Решение об успешности операции».

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

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

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

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

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

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

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

Оплата с помощью платёжного токена может быть реализована путём выполнения одношагового или двухшагового сценария: в запросе на создание счёта необходимо передать идентификатор клиента, для которого выпущен токен (параметр 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"
   }
}

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

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