# Виджет приема оплаты

## Описание

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

### Приема оплат

> В зависимости от выбранного типа приема платежей, мы будем отправлять соответствующий тип вебхука
>
> [Вебхук при оплате счета](https://docs.apollopayment.io/webhooks#webhook-statusa-scheta)\
> [Вебхук при пополнении персонального адреса](https://docs.apollopayment.io/webhooks#webhook-statusa-depozita-na-personalnyi-adres)

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

#### Счета

Для каждого нового платежа пользователь получает новый счет с уникальным адресом, который действует ограниченное время. Счет может быть выставлен в крипто или фиатной валюте, с фиксированной суммой или без нее для свободной оплаты.

{% @mermaid/diagram content="sequenceDiagram
Клиент->>Мерчант: Переходит к оплате
Мерчант->>Мерчант: Размещает iframe-виджет

```
alt виджет
    Клиент->>Мерчант: Выбирает монету/сеть
    Мерчант ->> Apollopayment: Создание счета на оплату
    Мерчант ->> Клиент: Показ адреса оплаты
end

Apollopayment-->>Мерчант: Отправка вебхука

Note over Клиент: Клиент отправляет монеты

Note over Apollopayment: Увидели транзакцию в блокчейне

Apollopayment-->>Мерчант: Отправка вебхука" %}
```

***

#### Персональные адреса

Прием платежей позволяет формировать список крипто адресов под каждого плательщика. Эти адреса навсегда закрепляются за пользователем.

{% @mermaid/diagram content="sequenceDiagram
Клиент->>Мерчант: Переходит к оплате
Мерчант->>Мерчант: Размещает iframe-виджет

```
alt виджет
    Клиент->>Мерчант: Выбирает монету/сеть
    Мерчант ->> Apollopayment: Получение персонального адреса
    Мерчант ->> Клиент: Показ адреса оплаты
end

Note over Клиент: Клиент отправляет монеты

Note over Apollopayment: Увидели транзакцию в блокчейне

Apollopayment-->>Мерчант: Отправка вебхука" %}
```

### Выплаты

Через виджет можно осуществлять выплаты.

{% @mermaid/diagram content="sequenceDiagram
alt Перед выводом надо добавить адреса, куда пользователю можно делать вывод
Клиент->>Мерчант: Добавляет адрес для вывода
Мерчант->>Apollopayment: POST /api-gateway/personal-addresses/add-trusted-address
end

```
Клиент->>Мерчант: Переходит к выплате
Мерчант->>Мерчант: Размещает iframe-виджет

alt виджет
    Клиент->>Мерчант: Выбирает монету/сеть
    Мерчант ->> Apollopayment: Создание выплаты
    Мерчант ->> Клиент: Страница ожидания завершения вывода
end

Note left of Apollopayment: Монеты не уходят сразу, мы отправляем вебхук со статусом WAIT_APPROVE
Apollopayment-->>Мерчант: Отправка вебхука
Мерчант->>Apollopayment: POST /api-gateway/auto-withdrawals/approve

Note over Apollopayment: Отправка монет клиенту

Apollopayment-->>Мерчант: Отправка вебхука

alt виджет
    Мерчант ->> Клиент: Страница успеха
end" %}
```

## Подключение

Подключение происходит при помощи HTML-тега `<iframe/>`

Пример:

```html
<iframe 
    allow="clipboard-read; clipboard-write"
    src="https://widget.apollopayment.io/181a197e-3b00-4359-8298-6097aeb52c69"
></iframe>
```

> Атрибут `allow="clipboard-read; clipboard-write"` необходим чтобы ваши клиенты могли скопировать адрес платежа нажатием кнопки "Скопировать"

## Доступные параметры

Параметры передаются в `query`

> Для вставки данных в `query` их необходимо экранировать. В JavaScript это можно сделать с помощью функции `encodeURIComponent`
>
> const payinCryptoInvoiceId = encodeURIComponent('#12345');

### Параметры для приема платежей с помощью счетов

| Параметр                     | Пример                            | Описание                           |
| ---------------------------- | --------------------------------- | ---------------------------------- |
| payinCryptoInvoiceAmount     | (decimal) `123.45`                | Сумма к оплате                     |
| payinCryptoInvoiceCurrencies | (string) `USD,EUR`                | Валюта к пересчету                 |
| payinCryptoInvoiceId         | (string) `#12345`                 | Идентификатор платежа              |
| payinCryptoInvoiceDesc       | (string) `Оплата платежа 12345`   | Описание платежа                   |
| payinCryptoCurrenciesTo      | (string) `USDT_bsc,BNB,USDD_tron` | Список монет доступных для оплаты  |
| extUserId                    | (string) `user1234567`            | ID плательщика на стороне мерчанта |

> Если не передать параметр `payinCryptoInvoiceCurrencies`, то пользователю будет предложен\
> выбор из всех доступных валют для пересчета его суммы
>
> В параметр можно передать несколько валют через запятую, тогда пользователю будет предложен выбор\
> только из указанных валют
>
> Можно передать одну валюту, тогда она будет выбрана, без возможности для смены пользователем

> Параметр `payinCryptoInvoiceAmount` будет работать если в `payinCryptoInvoiceCurrencies` передана одна валюта

> В параметр можно указывать несколько монет/сетей через запятую
>
> Доступно указание только тикера монеты, в таком случае будут доступны все сети, в которых эта монета есть\
> Пример: `USDT,BNB,ETH`
>
> Доступно указание монеты в конкретной сети, разделитель - нижнее подчеркивание\
> Пример: `USDT_tron,BNB_bsc,ETH_ethereum`

> При указании параметр `payinCryptoInvoicePayerEmailRequired=true` поле `payinCryptoInvoicePayerEmailAllow` игнорируется

> При указании параметра `extUserId` резервируется персональный адрес для указанного пользователя, при этом задействуется функционал счетов. Если указанного персонального пользователя нет, то он будет создан

***

### Параметры для оплаты персональным адресом

| Параметр  | Пример                 | Описание                                                   |
| --------- | ---------------------- | ---------------------------------------------------------- |
| extUserId | (string) `user1234567` | ID плательщика на стороне мерчанта (параметр обязательный) |

> Создаваемые персональные пользователи из виджетов будут изолированны между виджетами
>
> *Если получить адрес оплаты для пользователя **X** из виджета **A**, то он не будет таким же как для того же пользователя **X** из виджета **B***
>
> ***
>
> Если вы хотите получить пользователя **X** через API персональных платежей, то вы должны добавить ID виджета в начало
>
> Пользователь **X**: `user12345`\
> ID виджета: `00000000-0000-0000-0000-000000000000`
>
> ID клиента для получения через API будет таким: `00000000-0000-0000-0000-000000000000@user12345`