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

Оплата с формы партнёра

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

Оплату с собственной платёжной формы партнёр может реализовать c помощью API.

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

Для приёма платежей с помощью собственной платёжной формы партнёру необходимо отвечать стандартам безопасности PCI DSS и иметь соответствующий сертификат, т.к. данные банковских карт, принимаемые к оплате, являются чувствительной информацией.

Доступны несколько сценариев приёма платежей:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  5. QIWI возвращает партнёру статус платежа (WAITING — создан, ожидает аутентификации клиента с помощью 3D-Secure), а также данные для аутентификации: pareq и acsUrl.

  6. Партнёр использует полученные данные для аутентификации клиента и сообщает QIWI об успешном прохождении аутентификации: см. шаги из статьи «Приём платежей» → 3D-Secure.
  7. QIWI с помощью платёжной системы отправляет запрос на авторизацию и подтверждение платежа в банк-эмитент.
  8. Банк-эмитент резервирует (холдирует) и сразу же списывает денежные средства с карты клиента.
  9. QIWI фиксирует успешное списание средств и возвращает партнёру статус платежа COMPLETED.
  10. Партнёр принимает решение об успешности завершения платежа — выполняет действия, указанные в статье «Общие принципы и правила» → «Решение об успешности операции».
%%{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, paymentId, amount, cardData, flags: SALE
    Q->>-P: Ответ на запрос создания платежа
    Note left of Q: siteId, paymentId, amount, status:WAITING, requirements.threeDS.pareq, requirements.threeDS.acsUrl
    rect rgb(230, 230, 230)
    Note over С, B: Аутентификация клиента с помощью 3D-Secure
    end
    Q->>+B: Запрос на авторизацию и подтверждение платежа
    Note right of Q: Через платёжную систему
    B->>B: HOLD
    B->>B: CAPTURE
    B->>-Q: Ответ на запрос
    Note left of B: ОК
    Q->>Q: Завершение платежа
    Q->>P: Статус платежа
    Note left of Q: status:COMPLETED
    rect rgb(255, 238, 223)
    Q->>P: Сценарий «Принятие решения об успешности операции»
    P->>Q: 
    end
    P->>С: Отображение результата на форме
    Note right of С: «Платёж успешен»

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

Партнёр получает, обрабатывает и хранит данные карты клиента.

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

{
  "amount": {
    "currency": "RUB",
    "value": 1.00
  },
  "paymentMethod" : {
    "type" : "CARD",
    "pan" : "4444443616621049",
    "expiryDate" : "12/19",
    "cvv2" : "123",
    "holderName" : "unknown cardholder"
  },
  "flags": [ "SALE" ]
}
HTTP/1.1 200 OK
Content-Type: application/json
{
    "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"
        }
    }
}

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

Примеры запросов для аутентификации клиента см. в статье «3D-Secure».

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

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

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

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

  1. Клиент выбирает товар или услугу на торговой площадке партнёра, переходит к оплате.
  2. Партнёр отображает клиенту собственную платёжную форму для ввода реквизитов карты.
  3. Клиент вводит реквизиты карты и подтверждает оплату.
  4. Партнёр отправляет QIWI запрос на создание платежа, в котором передаёт сумму платежа и данные карты.
  5. QIWI возвращает партнёру статус платежа (WAITING — создан, ожидает аутентификации клиента с помощью 3D-Secure), а также данные для аутентификации: pareq и acsUrl.
  6. Партнёр использует полученные данные для аутентификации клиента и сообщает QIWI об успешном прохождении аутентификации: см. шаги из статьи «Приём платежей» → 3D-Secure.
  7. QIWI с помощью платёжной системы отправляет запрос на авторизацию платежа в банк-эмитент.
  8. Банк-эмитент резервирует (холдирует) денежные средства на карте клиента.
  9. QIWI фиксирует успешное холдирование средств.
  10. Партнёр выполняет действия, указанные в статье «Общие принципы и правила» → «Решение об успешности операции».

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

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

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

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

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

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

  14. Банк-эмитент списывает денежные средства с карты клиента.
  15. QIWI фиксирует успешное завершение платежа.
  16. Партнёр принимает решение об успешности завершения платежа — выполняет действия, указанные в статье «Общие принципы и правила» → «Решение об успешности операции».
%%{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, paymentId, amount, cardData
    Q->>-P: Ответ на запрос создания платежа
    Note left of Q: siteId, paymentId, amount, status:WAITING, requirements.threeDS.pareq, requirements.threeDS.acsUrl
    rect rgb(230, 230, 230)
    Note over С, B: Аутентификация клиента с помощью 3D-Secure
    end
    Q->>+B: Запрос на авторизацию платежа
    Note right of Q: Через платёжную систему
    B->>B: HOLD
    B->>-Q: Результат авторизации
    Note left of B: ОК
    Q->>Q:  Состояние операции
    Note over Q: Средства захолдированы
    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 — совокупность участников процесса проведения платежа. Указанные на диаграмме сценарии см. в статьях:

Партнёр получает, обрабатывает и хранит данные карты клиента.

PUT /partner/payin/v1/sites/test-01/payments/1811 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: 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-00/payments/804900/capture/cap1234567890 HTTP/1.1
Accept: application/json
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Content-type: application/json
Host: api.qiwi.com

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

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

Примеры запросов для аутентификации клиента см. в статье «3D-Secure».