_intro_ru.html.md.erb

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

**Ключ доступа к API** — Символьная строка для авторизации мерчанта в API согласно стандарту OAuth 2.0 [RFC 6749](https://tools.ietf.org/html/rfc6749) [RFC 6750](https://tools.ietf.org/html/rfc6750).

**Мерчант** — см. **ТСП**.

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

**ТСП** — Торгово-сервисное предприятие.

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

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

**JSON**: JavaScript Object Notation — текстовый формат обмена данными, основанный на JavaScript [RFC 7159](https://tools.ietf.org/html/rfc7159).

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

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

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

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

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

**Шаг 1. Оставьте заявку на подключение [b2b.qiwi.com](https://b2b.qiwi.com)**

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

<a name="auth"></a>

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

При подключении к Протоколу приема платежей вы получаете уникальный идентификатор `siteId` и доступ в [Личный кабинет](https://business.qiwi.com/service/core/merchants?). Параметры доступа отправляются на указанный при регистрации email.

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

Ключ доступа к API используется для взаимодействия с API. Выпустите ключ API в [Личном кабинете](https://business.qiwi.com/service/core/merchants?) в разделе **Настройки**.

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

При подключении идентификатор ТСП находится в тестовом режиме. В этом режиме вы можете проводить  операции без списания средств с банковской карты. Подробнее о тестовом режиме см. в разделе [Тестовый режим](#test_mode).

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

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

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

* [Платеж через форму QIWI](#invoicing).
* [Платеж через форму мерчанта](#merchant-api-integration).

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

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

Метод|[Платежная форма QIWI](#invoicing)|[Платежная форма мерчанта](#merchant-api-integration)
-----|---------|--------------
Банковская карта*|✓|✓**
Оплата платежным токеном | ✓ | ✓
Оплата через СБП | ✓ | ✓

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

`**` — требуется сертификация PCI DSS.

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

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

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

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

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

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

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

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

`https://b2b-api.qiwi.com/partner/`

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

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

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

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

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

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

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

~~~shell
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
~~~

Для авторизации запросов к API используется стандарт OAuth 2.0 согласно [RFC 6750](https://tools.ietf.org/html/rfc6750). Указывайте значение ключа доступа к API в HTTP-заголовке `Authorization` как

`Bearer <Ключ API>`

<% if config[:payin_show_methods] == "true" %>

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

Аутентификация по цифровой подписи применяется только для создания [операций типа "Выплата"](#payout-put) через API.

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

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

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

   `openssl genrsa -out private-key.pem 2048`

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

   <aside class="warning">Это секретная информация. Сохраняйте конфиденциальность закрытого ключа.</aside>

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).

### Как подписывать запросы {#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` при отправке запроса.

<% end %>

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

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

Для операций в тестовом режиме используются стандартные [URL API Протокола](#api-format).

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

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

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

<aside class="notice">
Ключ API, привязанный к <code>siteId</code>, действует для всех способов оплаты, подключенных к этому идентификатору.
</aside>

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

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

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

Вы также можете проверить выпуск платежного токена. Схема выпуска в тестовом режиме идентична описанной в разделе [Выпуск платежного токена карты](#merchant-form-token-issue).

### Тестовые номера карт {#test-card-numbers}

* **Mir**: `2200000000000004`, `2200000000000012`, `2200000000000020`, `2200000000000038`, `2200000000000046`, `2200000000000053`, `2200000000000061`, `2200000000000079`, `2200000000000087`, `2200000000000095`, `2200000000000103`, `2200000000000111`
* **Visa**: `4256000000000003`, `4256000000000011`, `4256000000000029`, `4256000000000037`, `4256000000000045`, `4256000000000052`, `4256000000000060`, `4256000000000078`, `4256000000000086`, `4256000000000094`, `4256000000000102`, `4256000000000110`
* **Mastercard**: `5236000000000005`, `5236000000000013`, `5236000000000021`, `5236000000000039`, `5236000000000047`, `5236000000000054`, `5236000000000062`, `5236000000000088`, `5236000000000096`, `5236000000000104`, `5236000000000112`, `5236000000000120`
* **UnionPay**: `6056000000000000`, `6056000000000018`, `6056000000000026`, `6056000000000034`, `6056000000000042`, `6056000000000059`, `6056000000000067`, `6056000000000075`, `6056000000000083`, `6056000000000091`, `6056000000000109`, `6056000000000117`

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

### Тестирование операций с 3-D Secure {#test-3ds}

1. Создайте платежную ссылку [по API](#qiwi-form-invoice-api) или [без него](#https-qiwi-form).
2. Используйте любую карту из раздела [Тестовые номера карт](#test-card-numbers).
3. CVV для 3-D Secure в тестовом режиме должно быть равным `849` или используйте имя держателя карты, которое содержит строку `3ds`.
4. Подтвердите или отклоните операцию на форме.
![test-3ds](/images/payin/test-3ds.png)

### Ограничения при тестировании {#test_limit}

* Из валют (параметр `amount.currency`) разрешен только рубль РФ (`643`).
* Установлены ограничения на сумму и количество операций:

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

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

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

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

При [запросе статуса платежа СБП](#qr-code-sbp-get) в тестовом режиме доступно ограниченное количество статусов:

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