rbkmoney · volkov-sergei · Dec 16, 2020 · Dec 16, 2020 · Dec 16, 2020 · Dec 16, 2020
diff --git a/content/docs/readme/Bender/readme.md b/content/docs/readme/Bender/readme.md
@@ -0,0 +1,25 @@
+# Bender
+<!-- Insert your shields here -->
+
+<!-- TOC -->
+## Содержание 
+
+- [Общее описание](#Общее-описание)
+- [Принцип функционирования сервиса](#Принцип-функционирования-сервиса)
+- [Связанные сервисы](#Связанные-сервисы)
+- [Составители](Составители)
+
+## Общее описание
+
+**Bender (External ID for Distributed Systems Service)** - сервис генерации идентификаторов. Позволяет генерировать идентификаторы для сущностей платформы, что используется в других сервисах для обеспечения [идемпотентности](https://en.wikipedia.org/wiki/Idempotence) операций. 
+
+## Пример функционирования сервиса
+
+При вызове любого метода платформы, использующего уникальный идентификатор (например, id инвойса при вызове метода [`CreateInvoice`](https://developer.rbk.money/api/#operation/createInvoice) или id плательщика при вызове метода [`CreateCustomer`](https://developer.rbk.money/api/#operation/createCustomer)), сервис формирует id для объекта платформы и дальнейшего мониторинга состояния этого объекта.
+
+## Связанные сервисы
+
+* `Machinegun`
+* `CAPI`
+
+## Составители
diff --git a/content/docs/readme/Hooker/Hooker_Readme.md b/content/docs/readme/Hooker/Hooker_Readme.md
@@ -0,0 +1,63 @@
+# Hooker
+<!-- Место для ваших шильдиков -->
+
+<!-- Toc -->
+## Содержание
+- [Общее описание](#Общее-описание)
+  - [Стратегия доставки webhook'ов](#Стратегия-доставки-webhook'ов)
+  - [Авторизация полученных сообщений](#Авторизация-полученных-сообщений)
+- [Сценарии работы сервиса](#Сценарии-работы-сервиса)
+  - [Типы событий инвойса (InvoicesTopic)](#Типы-событий-инвойса-(InvoicesTopic))
+  - [Типы событий плательщика (CustomersTopic)](#Типы-событий-плательщика-(CustomersTopic))
+- [Связанные сервисы](#Cвязанные-сервисы)
+- [Составители](#Составители)
+
+
+## Общее описание
+
+**Hooker (Webhooks Notifications and Management Service)** – сервис, определяющий протокол доставки асинхронных оповещений о возникновении новых событий в рамках организации, которые сервис доставляет в виде HTTP-запросов на URL-адреса  webhook'ов, указанных при их формировании. Информацию о произошедших событиях сервис получает из базы данных Kafka.  
+
+**Webhook** - это подписка на определенный тип события либо их группу, касающихся различных объектов в рамках организации. Для управления webhook'ами используются методы RBKmoney API, описанные в спецификации [RBKmoney Webhooks Management API](https://rbkmoney.github.io/api/#tag/Webhooks). Когда наступает одно из событий в рамках определенного инвойса (например, изменение статуса инвойса или платежа по этому инвойсу), платформа выбирает webhook, подходящий под этот тип события, и отправляет HTTP-запрос, содержащий сообщение в формате [JSON](https://www.json.org/json-en.html) на указанный в этом webhook'е URL. Если создано несколько webhook'ов, подходящих под указанный тип события, то сообщение о возникновении события доставляется одновременно на все заданные в webhook'ах URL в неопределённом порядке. Максимальное количество webhook'ов для одного магазина - 10 штук.
+
+### Стратегия доставки webhook'ов
+Платформа гарантирует порядок доставки сообщений о произошедших событиях в рамках определенного инвойса, никакое событие не может быть пропущено и доставлено не в порядке возникновения в платформе. Платформа поддерживает очередь сообщений для каждого инвойса для того, чтобы соблюсти эти гарантии.
+
+Запрос на доставку считается успешным только при получении ответа со статусом `200`. Платформа будет ожидать успешного ответа на отправленный запрос в течение 10 секунд. В случае ответа с любым другим статусом или по истечении указанного времени, отведённого на обработку оповещения, платформа будет пытаться повторно доставить оповещения до получения успешного ответа, либо до принятия решения о невозможности доставить информацию. Попытки доставки будут производиться со следующими временными интервалами между запросами:
+- 30 секунд;
+- 5 минут;
+- 15 минут;
+- 1 час;
+- каждый час в течении суток (24 часа).
+
+Если последняя попытка в течении суток доставить оповещение оканчивается неудачей, все события, которые накопились в очереди этого инвойса, отбрасываются.
+
+### Авторизация полученных сообщений
+Платформа подтверждает подлинность оповещений, подписывая сообщения приватным ключом, уникальным для каждого webhook'а, парный публичный ключ к которому содержится в данных этого webhook'а. Подпись передается в HTTP-заголовке Content-Signature. В заголовке в виде различных атрибутов содержится информация об использованном при формировании подписи алгоритме и значение подписи в формате [URL-safe base-64](https://tools.ietf.org/html/rfc4648). Пример подписи представлен ниже.
+
+```
+Content-Signature: alg=RS256; digest=zFuf7bRH4RHwyktaqHQwmX5rn3LfSb4dKo...
+```
+
+<!-- На данный момент возможно использование единственного алгоритма формирования подписи. -->
+
+#### Алгоритм [RS256](https://tools.ietf.org/html/rfc7518#section-3.3)
+
+Подпись формируется согласно алгоритму [RSASSA-PKCS1-v1_5](https://tools.ietf.org/html/rfc3447#section-8.2), на вход которому подаётся результат вычисления хэша сообщения по алгоритму [SHA-256](https://tools.ietf.org/html/rfc6234).
+
+
+## Сценарии работы сервиса
+Сервис Hooker может создавать webhook'и для двух типов событий:
+1. типы событий инвойса (InvoicesTopic);
+2. типы событий плательщиков (CustomersTopic).
+
+### Типы событий инвойса (InvoicesTopic)
+Подробное описание webhook'ов для типов событий инвойса описано на примере [кейса проведения платежа](https://github.com/volkov-sergei/coredocs/tree/master/docs/Readme/Hooker/Кейс обычного платежа.md).
+
+### Типы событий плательщика (CustomersTopic)
+Подробное описание webhook'ов для типов событий плательщика описано на примере [кейса создания рекуррента](https://github.com/volkov-sergei/coredocs/tree/master/docs/Readme/Hooker/Кейс создания рекуррента.md).
+
+## Cвязанные сервисы
+* `Hellgate`
+* `Kafka cluster`   
+
+## Составители
diff --git a/content/docs/readme/Hooker/rec_from_first_payment.md b/content/docs/readme/Hooker/rec_from_first_payment.md
@@ -0,0 +1,22 @@
+# Создание рекуррента через проведение первого платежа
+
+Рассмотрим кейс создания привязки покупателя для проведения рекуррентных платежей с помощью первого платежа.
+
+Ниже приведен сценарий создания рекуррента через первый платеж с помощью методов API, предоставляемых платформой.
+
+1. В платформе создается новый инвойс методом [`createInvoice`](https://developer.rbk.money/api/#operation/createInvoice). Инвойсу присваивается уникальный *invoiceId*.
+2. Методом [`createCustomer`](https://developer.rbk.money/api/#operation/createCustomer) в платформе создается новый плательщик. Метод присваивает покупателю уникальный `id` и пользовательский токен доступа `customerAccessToken.payload`.
+3. По полученным `id` и `customerAccessToken.payload` платформа формирует ссылку формы `Checkout`.
+4. Мерчант предоставляет плательщику ссылку формы `Checkout`, в которой плательщик вводит данные платежного инструмента и указывает согласие для использования этого платежного инструмента в дальнейших безакцептных списаниях.
+5. Форма `Checkout` внутренними алгоритмами формирует новый платеж методом [`createPayment`](https://developer.rbk.money/api/#operation/createPayment). В поле запроса `makeRecurrent` устанавливается параметр `true`.
+   * В поле `type` указывается по какой схеме совершается платеж:
+      - по одностадийной схеме `PaymentFlowInstant`;
+      - по двухстадийной схеме `PaymentFlowHold`.
+6. Платежу присваивается уникальный *id*.
+7. Плательщик подтверждает списание платежных средств с помощью прохождения 3D-Secure.
+8. Если платеж прошел успешно, то *invoiceId* и *id* платежа (п.6) в дальнейшем будут использоваться в качестве родительских.
+   * При следующих платежах в объекте `Payer` будут указаны следующие данные:   
+      "payerType": "RecurrentPayer",   
+      "recurrentParentPayment":    
+      "invoiceID": "*invoiceID* полученный при инициализирующем платеже",     
+      "paymentID": "*id* инициализирующего платежа" 
diff --git a/content/docs/readme/Hooker/Кейс обычного платежа.md b/content/docs/readme/Hooker/Кейс обычного платежа.md
@@ -0,0 +1,32 @@
+Рассмотрим кейс обычного платежа плательщика мерчанту через платформу. 
+Мерчант решил установить webhook'и (в личном кабинете) на все возможные события, предоставляемые платформой (мерчант может выбрать любой набор webhook'ов для необходимых событий). Также мерчант может установить необходимые webhook'и, используя API, методом [CreateWebhok](https://developer.rbk.money/api/#operation/createWebhook) и, указывая необходимые параметры.   
+Обратная связь от webhook'ов поступает на бэкенд мерчата с помощью сервиса `Hooker`.   
+После срабатывания триггера любого webhook'а, мерчанту приходит об этом оповещение на указанный при добавлении webhook'а URL.
+Ниже представлен сценарий проведения платежа с указанием событий, активирующих определенные webhook'и.   
+Возможно создать webhook'и для нижеперечисленных событий:
+* InvoiceCreated - создан новый инвойс;
+* InvoicePaid - инвойс перешел в состояние "Оплачен";
+* InvoiceCancelled - инвойс отменен по истечению срока давности;
+* InvoiceFulfilled - инвойс успешно погашен;
+* PaymentStarted - создан платеж;
+* PaymentProcessed - платеж обработан;
+* PaymentCaptured - платеж успешно завершен;
+* PaymentCancelled - платеж успешно отменен;
+* PaymentRefunded - платеж успешно возвращен;
+* PaymentFailed - при проведении платежа возникла ошибка;
+* PaymentRefundCreated - возврат платежа успешно создан; 
+* PaymentRefundSucceeded - возврат платежа прошел успешно;
+* PaymentRefundFailed - возврат платежа завершился неудачей.
+
+1. Плательщик выбрал в магазине мерчанта необходимый товар, добавил его в корзину, готов перейти к процедуре оплаты.
+2. Бэкенд мерчанта методом [createInvoice](https://developer.rbk.money/api/#operation/createInvoice) создает инвойс с указанием окончания срока действия. Платформа возвращает бэкенду мерчанта сформированный инвойс, ключ для доступа к инвойсу - `invoiceAccessToken` и платежную ссылку.
+3. Срабатывает триггер webhook'а `InvoiceCreated (Создан новый инвойс)`.
+4. Бэкенд мерчанта направляет плательщику платежную ссылку, при переходе по которой у плательщика появится форма `Checkout`. Плательщик вводит необходимые для оплаты данные и нажимает кнопку оплаты. 
+    - Если покупатель не ввел в форму `Checkout` данные об оплате в течении заданного мерчантом времени, инвойс переходит в статус "Отменен" и срабатывает триггер webhook'а `InvoiceCancelled (инвойс отменен по истечению срока давности)`.
+5. По введенным в форму `Checkout` данным внутренние методы  платформы вызывают метод [createPaymentResource](https://developer.rbk.money/api/#operation/createPaymentResource). <!-- исправил с createPaymentToolToken ошибка в схеме-->  В платформе создается одноразовый токен платежного средства `paymentToolToken`, предоставленного плательщиком, а также новая уникальная платежная сессия `paymentToolSession`.
+6. Бэкенд мерчанта методом  [createPayment](https://developer.rbk.money/api/#operation/createPayment) создает в платформе новый платеж и передает следующие токены платформе: `invoiceAccessToken`, `paymentToolToken` и `paymentToolSession`. Срабатывает триггер webhook'а `PaymentStarted (создан платеж)`. 
+7. Проводится авторизация плательщика методом холдирования платежных средств на платежном инструменте.
+   - Если не получилось произвести процедуру холдировнаия платежных средств (например, неправильно введен номер карты или недостаточно средств на счете), то срабатывает триггер webhook'а `PaymentFailed (при проведении платежа возникла ошибка)`.
+8. При успешном прохождении холдирования срабатывает триггер webhook'а `PaymentProcessed (платеж обработан)`.
+   - Если после ввода платежных данных плательщик решает отменить платеж, то это вызывает срабатывание триггера webhook'а `PaymentCancelled (платеж успешно отменен)`.  
+9. Мерчант может проверить корректность платежа webhook'ом `PaymentCaptured (платеж успешно завершен)`. Инвойс переходит в статус "Оплачен". Так же успешность платежа можно проверить вызовом webhook'а `InvoicePaid (инвойс перешел в состояние "Оплачен")`. После этого мерчант может собственноручно перевести инвойс в статус "Погашен", после чего сработает триггер webhook'а `InvoiceFulfilled (инвойс успешно погашен)`.