Skip to content

Latest commit

 

History

History
256 lines (159 loc) · 19.6 KB

_intro_ru.html.md

File metadata and controls

256 lines (159 loc) · 19.6 KB

Термины и сокращения {#articles}

Ключ доступа к API — Символьная строка для авторизации мерчанта в API согласно стандарту OAuth 2.0 RFC 6749 RFC 6750.

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

API: Application Programming Interface — набор готовых методов, предоставляемых приложением (системой) для использования во внешних программных продуктах.

REST: Representational State Transfer — архитектурный стиль взаимодействия компонентов распределённого приложения в сети.

JSON: JavaScript Object Notation — текстовый формат обмена данными, основанный на JavaScript RFC 7159.

3DS: 3-D Secure — протокол защиты карточных данных, используемый для аутентификации держателя банковской карты во время совершения платежной операции через интернет. QIWI поддерживает как версию 3DS 1.0, так и версию 3DS 2.0 протокола.

ТСП, Мерчант — Торгово-сервисное предприятие.

MPI: Merchant Plug-In — модуль, выполняющий 3DS аутентификацию покупателя.

PCI DSS: Payment Card Industry Data Security Standard — стандарт безопасности данных индустрии платёжных карт, учреждённым международными платёжными системами Visa, MasterCard, American Express, JCB и Discover.

Начало работы {#start}

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

Шаг 1. Оставьте заявку на подключение b2b.qiwi.com

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

Шаг 2. Получите доступ к личному кабинету

При подключении к Протоколу приема платежей вы получаете уникальный идентификатор siteId и доступ в Личный кабинет. Параметры доступа отправляются на указанный при регистрации email.

Шаг 3. Выпустите ключ доступа к API

Ключ доступа к API используется для взаимодействия с API. Выпустите ключ API в Личном кабинете в разделе Настройки.

Шаг 4. Протестируйте взаимодействие

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

Когда интеграция на вашей стороне закончена, мы переводим ваш идентификатор siteId в производственный режим. В производственном режиме выполняются реальные списания средств с карт.

Способы подключения {#methods}

Протокол приема платежей поддерживает несколько вариантов взаимодействия:

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

Доступные методы оплаты {#payment-ways}

Метод Платежная форма QIWI Платежная форма мерчанта
Банковская карта* ✓ ✓
Оплата платежным токеном ✓ ✓
Yandex Pay × ✓
Mir Pay × ✓
Оплата через СБП ✓ ✓
Оплата с баланса КИВИ Кошелька ✓ ✓**
Оплата с баланса мобильного телефона × ✓

* — метод оплаты доступен по умолчанию, другие методы оплаты подключаются по запросу.

** — посредством выпуска платежного токена для КИВИ кошелька.

Типы операций {#operations}

В Протоколе доступны следующие операции:

  • Счет (Invoice) — электронный документ, выставляемый продавцом покупателю. Содержит информацию о сумме и номере заказа. Не является финансовой сущностью и имеет ограниченный срок жизни. Выставление счета необходимо для получения ссылки на платежную форму QIWI.
  • Платеж (Payment) — операция списания денежных средств от покупателя в пользу продавца. Фактическое списание происходит только после подтверждения (Capture). При работе через платежную форму QIWI, Payment — попытка оплаты счета (Invoice).
  • Завершение (Complete) — завершение 3DS-верификации Покупателя. Используется при работе через Платежную форму мерчанта.
  • Подтверждение (Capture) — операция подтверждения авторизации (списания) средств. Возможно только однократное успешное подтверждение авторизации.
  • Возврат (Refund) — возврат средств покупателю по успешному платежу. Финансовая операция списания денежных средств от продавца в пользу покупателя. Если подтверждения операции Payment не было, то в ответе на операцию Refund вы получите флаг Reversal и деньги со счета Покупателя на счет продавца не перечислятся (комиссия за эквайринг также не удерживается).

Общая схема проведения платежа и взаиморасчетов {#principal-scheme}

sequenceDiagram participant customer as Покупатель participant store as Магазин мерчанта participant ipsstore as Кредитная организация
мерчанта participant qb as QIWI participant ips as Платежная система participant ipscust as Кредитная организация
Покупателя
Эмитент или банк-отправитель customer->>store:Старт оплаты store->>qb:Платеж qb->>ips:Авторизация платежа ips->>ipscust:Авторизация платежа rect rgb(255, 238, 223) Note over ipsstore, ipscust:Взаиморасчеты ipscust->>ips:₽₽₽ ips->>qb:₽₽₽ qb->>ipsstore:₽₽₽ end

Формат взаимодействия {#api-format}

API Протокола приема платежей основано на принципах REST-архитектуры. Данные и методы считаются ресурсами, которые доступны через вызов универсальных идентификаторов ресурсов (URI).

Методы API вызываются через HTTP-запросы. Постоянная часть URL-адреса для вызова методов API:

https://api.qiwi.com/partner/

Параметры методов помещаются в JSON-тело запроса. В GET-запросах параметры помещаются в query запроса.

Необходимо указывать Accept: application/json в заголовках запроса — API всегда возвращает ответ в формате JSON.

Методы API обеспечивают логическую идемпотентность, т. е. многократный вызов метода эквивалентен однократному. Однако ответ сервера может меняться (например, состояние счёта может измениться между запросами).

Авторизация {#api-auth}

Пример запроса с авторизацией

curl -X PUT \
  https://api.qiwi.com/partner/v1/sites/{site_id}/payments/{payment_id} \
  --oauth2-bearer <Ключ API>

Пример заголовка авторизации

Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9

Для авторизации запросов к API используется стандарт OAuth 2.0 согласно RFC 6750. Указывайте значение ключа доступа к API в HTTP-заголовке Authorization как

Bearer <Ключ API>

Аутентификация по цифровой подписи {#sign-auth}

Аутентификация по цифровой подписи применяется только для создания операций типа "Выплата" через API.

Для аутентификации по цифровой подписи мерчант должен создать пару RSA-ключей, например, с помощью утилиты OpenSSL. Закрытый ключ должен быть размером 2048 бит в PEM-формате. Мерчант должен передать в QIWI закодированный в Base64 открытый ключ, соответствующий закрытому ключу.

Как создать ключи {#create-key-sign}

  1. Сгенерировать закрытый ключ. Выполните команду:

    openssl genrsa -out private-key.pem 2048

    В папке выполнения команды будет создан файл с закрытым ключом: private-key.pem.

    Это секретная информация. Сохраняйте конфиденциальность закрытого ключа.

  2. Получить открытый ключ, соответствующий закрытому, командой:

    openssl rsa -in private-key.pem -pubout -out public-key.pem

  3. Закодировать полученный ключ public-key.pem в Base64 командой:

    base64 -i public-key.pem

  4. Передать закодированный в Base64 открытый ключ в QIWI, а закрытый ключ использовать для подписи запросов.

Как подписывать запросы {#how-to-sign}

Алгоритм с примерами на языке Bash:

  1. Сформировать body запроса в виде строки:

    REQUEST_BODY='{"amount":{"value":100, "currency":"RUB"},...'

  2. При помощи закрытого ключа private-key.pem, сгенерированного ранее, сформировать цифровую подпись по алгоритму SHA256withRSA:

    SIGNATURE_RAW=$(echo -n $REQUEST_BODY | openssl dgst -sha256 -sign private-key.pem)

  3. Закодировать полученную цифровую подпись при помощи Base64 в строку:

    SIGNATURE_BASE64=$(echo -n $SIGNATURE_RAW | base64)

  4. Передать закодированную цифровую подпись в заголовке X-Digital-Sign при отправке запроса.

Тестирование проведения операций {#test_mode}

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

Для операций в тестовом режиме используются стандартные URL API Протокола.

Тестовый режим для метода оплаты с баланса КИВИ Кошелька не предусмотрен.

Когда интеграция на вашей стороне закончена, служба поддержки QIWI переводит siteId в производственный режим. В этом режиме выполняются реальные списания денежных средств с карт.

При переходе в производственный режим перевыпускать ключ доступа к API не нужно.

При необходимости измените постоянный URL для обработки уведомлений с тестового (например, https://your-shop-test.ru/callbacks) на производственный (например, https://your-shop-prod.ru/callbacks) в Личном кабинете.

Ключ API, привязанный к siteId, действует для всех способов оплаты, подключенных к этому идентификатору.

Оплата картой {#test_data_card}

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

Тестовые номера карт

Получить номера карт

В тестовом режиме из валют (параметр amount.currency) разрешен только рубль РФ (643).

CVV в тестовом режиме может быть любым (произвольные 3 цифры).

Для тестирования различных вариантов оплаты и ответов используйте различные сроки действия карты:

Месяц срока действия карты Результат
02 Операция проведена неуспешно
03 Операция проведена успешно, задержка — 3 секунды
04 Операция проведена неуспешно, задержка — 3 секунды
Все остальные значения Операция выполняется успешно

В тестовом режиме установлено ограничение на сумму и количество операций:

  • Максимальная сумма транзакции — 10 рублей.
  • Максимальное количество транзакций в сутки — 100. Учитываются операции за текущие сутки (время по МСК) с суммой каждой операции не более установленного лимита 10 рублей.

Для проведения операции с 3DS используйте строку unknown name в имени держателя карты. Прохождение 3DS в режиме тестирования можно проверить только при вводе номера реальной карты.

Вы также можете проверить выпуск платежного токена. Схема выпуска в тестовом режиме идентична описанной в разделе Выпуск платежного токена карты.

Оплата СБП {#test_data_sbp}

В тестовом режиме можно через API только выпускать QR-код СБП и запрашивать его статус. Для тестирования разных вариантов ответов указывайте разные суммы платежа (поле amount.value):

  • 200 — QR-код будет успешно создан.
  • Для других сумм платеж пройдет неуспешно со статусом DECLINED.

При запросе статуса платежа СБП в тестовом режиме доступно ограниченное количество статусов:

  • CREATED — Платеж создан.
  • DECLINED — Платеж отклонен.
  • EXPIRED — Срок действия платежа истек.

Выплаты {#payout-test-mode}

Для тестирования различных вариантов выплаты и ответов в тестовом режиме указывайте разные суммы платежа (поле amount.value):

Значение поля amount.value Результат
200.00 или 2.00 На инициирующий запрос выплаты возвращается status.value=WAITING, на последующие запросы статуса выплаты возвращается status.value=SUCCESS
500.00 или 5.00 На запрос выплаты возвращается status.value=DECLINED
510.00 или 5.10 На инициирующий запрос выплаты возвращается status.value=WAITING, на последующие запросы статуса выплаты возвращается status.value=DECLINED