# Проведение выплат {#ru_pp_payout}

статья о порядке проведения через Payment Page выплат

## Общая информация {#section_nrq_x34_1bc .section}

В платёжной платформе Ecommpay поддерживается возможность проводить выплаты на счета, ассоциированные с платёжными картами, с использованием платёжной формы Payment Page: с предварительной регистрацией каждой такой выплаты через Gate API и с последующим вызовом платёжной формы в режиме работы Payout.При этом отправителями выплат могут выступать как сам мерчант, так и физические лица, а при проведении выплат могут использоваться сервисы Mastercard MoneySend и Visa Direct.

**Прим.:** Возможность проведения выплат поддерживается только в платёжной форме Payment Page 5-го поколения.

Для регистрации выплаты необходимо отправить соответствующий запрос к платформе через Gate API и принять оповещение о результате этой регистрации.Если выплата зарегистрирована, в оповещении передаётся специальный идентификатор \(`uuid`\), который необходимо указать при вызове Payment Page. При этом важно учитывать, что срок действия идентификатора составляет 30 минут и при открытии платёжной формы на её страницах отображается таймер с остающимся временем до подтверждения выплаты пользователем.В случае, если пользователь не подтвердил выплату в заданное время, ему отображается соответствующее уведомление, и для проведения выплаты со стороны веб-сервиса требуется зарегистрировать её повторно, с указанием нового идентификатора платежа \(`payment_id`\).

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

![](images/ecommpay/ru_pp_payout_code.svg "Пример письма с проверочным кодом")

Со стороны пользователя для проведения выплаты с использованием Payment Page следует выбрать платёжный инструмент, указать его реквизиты, затем указать проверочный код и получить уведомление о результате. При этом платёжные данные могут быть указаны одним из следующих способов:

-   *Через ввод на странице формы.*В этом случае пользователь обязательно заполняет на страницах формы все требуемые поля.
-   *Через выбор или ввод на странице формы.* В этом варианте пользователь может выбрать одни из уже сохранённых реквизитов или указать новые, которые также могут быть сохранены и доступны ему в дальнейшем.
-   *Через выбор до вызова формы.*В этом варианте пользователь выбирает в веб-сервисе конкретную карту, в запросе на открытие Payment Page указывается токен этой карты и платёжная форма открывается с указанием необходимых реквизитов.

По результатам проведения выплат могут формироваться токены платёжных карт— в случаях, когда данные этих карт не были сохранены ранее и такая возможность подключена для используемого проекта мерчанта \([подробнее](ru_pp_token.md)\).

## Пользовательский сценарий {#section_tgk_kx4_1bc .section}

Допустим, пользователь Prostetnik Jeltz занял третье место в конкурсе Millstone Jennings Poetry с призом, равным 70 EUR.Чтобы получить выплату, пользователь указывает данные платёжного инструмента и свои имя и фамилию, после чего подтверждает выплату и ожидает результата её проведения.

![](images/ecommpay/ru_pp_payout_1.svg "Указание платёжных данных")

![](images/ecommpay/ru_pp_payout_2.svg "Указание проверочного кода")

## Ограничения {#section_dkx_x34_1bc .section}

Проведение выплат с использованием Payment Page возможно с учётом следующих ограничений:

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

    В случае отправки запроса на регистрацию выплаты в рамках проекта, для которого не подключена такая возможность, от платёжной платформы к веб-сервису направляется оповещение с кодом ошибки `317` \([подробнее](ru_platform_payment_info_codes.md)\).

-   Для отправки запросов на регистрацию выплат должны использоваться IP-адреса, предоставленные специалистам технической поддержки Ecommpay и добавленные ими в список разрешённых.

    В случае отправки запроса с IP-адреса, не добавленного в список разрешённых, от платёжной платформы к веб-сервису направляется ответ с кодом ошибки `403` \([подробнее](ru_gate_interaction_organisation.md#)\).

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

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

-   Остаток средств на счёте мерчанта должен быть достаточным для проведения выплаты.

    Если средств недостаточно, выплата отклоняется, пользователю отображается страница платёжной формы с информацией об отклонении платежа и к веб-сервису направляется оповещение с соответствующим кодом ошибки. Информацию об остатке средств можно получать через Dashboard \([подробнее](ru_dbl_balances.md#)\) и Data API \([подробнее](ru_dbl_api_protocol.md)\), при этом с вопросами можно обращаться к курирующему менеджеру Ecommpay.

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

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

    **Прим.:**

    Такие требования могут касаться, в частности, следующих случаев:

    -   для выплат в рамках программ сервиса MoneySend платёжной системы Mastercard, в которых отправителем является физическое лицо, должны указываться имя и фамилия получателя, а также имя и фамилия, основной идентификатор используемого платёжного инструмента и информация о местонахождении отправителя — если эти сведения не указаны в запросе на открытие платёжной формы, выплата отклоняется;
    -   для выплат в рамках программы Money Transfer платёжной системы Visa должна указываться информация о местонахождении получателя, если карта получателя выпущена в Канаде — если эти сведения не указаны в запросе на открытие платёжной формы, пользователю отображается дополнительная страница с полями для их указания.
    С вопросами о специфике проведения выплат в различных регионах и с учётом различных факторов можно обращаться к курирующему менеджеру Ecommpay.

-   При вызове платёжной формы не должна использоваться возможность ограничения времени работы с ней \([подробнее](ru_pp_time_limit.md)\); время работы с платёжной формой при проведении выплат ограничено по умолчанию и соответствует времени, остающемуся до окончания срока действия идентификатора `uuid`.

    Если в запросе на открытие платёжной формы указаны дата и время завершения работы с ней, пользователю отображается страница платёжной формы с информацией об ошибке.


## Подключение {#section_txr_bgp_1bc .section}

Чтобы подключить возможность проведения выплат с использованием Payment Page, со стороны мерчанта необходимо:

1.  Согласовать с курирующим менеджером Ecommpay подключение этой возможности, необходимость её тестирования и применение ограничений в каждом конкретном случае.
2.  Если была согласована необходимость тестирования, получить от специалистов Ecommpay уведомление о готовности к тестированию, проверить работу платёжной формыс использованием этой возможности и сообщить о готовности к запуску.
3.  Получить от специалистов Ecommpay уведомление о подключении возможности.

## Схема работы {#section_gyn_lx4_1bc .section}

Для проведения выплаты с использованием Payment Page со стороны веб-сервиса необходимо:

1.  Сформировать и отправить в платёжную платформу запрос на регистрацию выплаты.
2.  Принять от платформы оповещение о регистрации выплаты.
3.  Сформировать и отправить в платёжную платформу запрос на открытие Payment Page в режиме Payout.
4.  Принять от платформы оповещение о результате платежа.

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

![UML-scheme](images/ecommpay/ru_payout_pp_uml.svg)

1.  Пользователь на стороне веб-сервиса инициирует выплату.
2.  От веб-сервиса на заданный URL Ecommpay передаётся запрос на регистрацию выплаты.
3.  Запрос на регистрацию выплаты поступает в платёжную платформу Ecommpay.
4.  В платёжной платформе выполняется приём запросас проверкой наличия обязательных параметров и корректной подписи.
5.  От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности\([подробнее](ru_gate_interaction_organisation.md#)\).
6.  В платёжной платформе выполняется обработка запроса.
7.  От платёжной платформы к веб-сервису направляется оповещение с указанием идентификатора выплаты.
8.  От веб-сервиса на заданный URL Ecommpay передаётся запрос на проведение выплаты с использованием Payment Page.
9.  Запрос на проведение выплаты поступает в платёжную платформу.
10. В платёжной платформе выполняется приём запроса, с проверкой наличия обязательных параметров и корректной подписи.
11. Осуществляется подготовка Payment Pageсогласно параметрам проекта и вызова.
12. Пользователю отображается платёжная формас индикатором остающегося времени работы с ней.
13. Пользователь выполняет необходимые действия и подтверждает выплату.
14. В платёжную платформу передаётся запрос на проведение выплаты.
15. В платёжной платформе выполняются обработка полученного запроса и его отправка в платёжную среду.
16. В платёжной среде выполняется обработка платежа.
17. От платёжной среды к платформе направляется информация о результате выплаты.
18. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
19. От платёжной платформы к Payment Page направляется информация о результате выплаты.
20. Информация о результате выплаты отображается пользователю на Payment Page.

## Формат запроса на регистрацию выплаты {#section_hww_lx4_1bc .section}

При работе с запросами на регистрацию выплат необходимо учитывать следующее:

1.  Для регистрации каждый выплаты должен использоваться отдельный POST-запрос к конечной точке [/v2/payment/payout/registration](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-payout-registration).
2.  В каждом запросе должны использоваться следующие объекты и параметры:
    -   `general` — объект, содержащий основные идентификационные сведения запроса:
        -   `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции;
        -   `payment_id` — идентификатор платежа, уникальный в рамках проекта;
        -   `signature` — подпись запроса, составленная после указания всех целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\);
    -   `payment` — объект, содержащий сведения о платеже:
        -   `amount` — сумма платежа в дробных единицах валюты;
        -   `currency` — код валюты платежав формате ISO-4217 alpha-3;
    -   `customer` — объект, содержащий сведения о пользователе:
        -   `id` — идентификатор пользователя, уникальный в рамках проекта;
        -   `email` — адрес электронной почты пользователя;
        -   `phone` — номер телефона пользователя;
        -   `ip_address` — IP-адрес пользователя, актуальный для регистрируемой выплаты.

Таким образом, корректный запрос на регистрацию выплаты должен содержать идентификатор проекта, базовые сведения о платеже \(идентификатор, сумму и код валюты\), идентификатор и IP-адрес пользователя, контактные данные пользователя \(адрес электронной почты и номер телефона\), а также подпись.

```language-json

  "general": {
    "project_id": 91348,
    "payment_id": "cosmoshop_payout_1323",
    "signature": "iehD3ZeW3CM7aGfmdgfjdgneHbCmronMpXom1b/ot1HvOGMV+CT8LA=="
  },
  "customer": {
    "id": "16061314",
    "email": "p.jeltz@mail.com",
    "phone": "44991234567",  
    "ip_address": "93.47.230.225"
  },
  "payment": {
    "amount": 7000,
    "currency": "EUR"
  }
}
```

## Формат оповещения о результате регистрации выплаты {#section_ayp_gtp_1bc .section}

При проведении каждой выплаты с использованием Payment Page необходимо принять промежуточное оповещение от платёжной платформы о результате регистрации выплаты и использовать идентификатор, передаваемый в параметре `uuid`. Формат таких оповещений является типовым \([подробнее](ru_platform_callbacks.md#)\).

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

```language-json

{
    "general": {
        "project_id": "91348",
        "payment_id": "cosmoshop_payout_1323",
        "signature": "V2mxcUcGUcCtAE51lgesBefZgfG9NHpQEbfdI2X1Q=="
    },
    "request_id": "50715",
    "payment": {
        "id": "cosmoshop_payout_1323",
        "type": "payout",
        "status": "awaiting_payout_completion",
     },
    "operation": {
        "id": "500359719",
        "type": "payout",
        "status": "awaiting_payout_completion"
    },
    "customer": {
        "id": "16061314"
    },
    "sum_request":
    {
        "amount": "7000",
        "currency": "EUR"
    },
    "transaction": {
        "type": "payout"
    },
    "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5GTkVvY/sRDLKAnSS+AagnGCJ1nsPg==",
    "uuid_expired_at": "2024-04-24T13:50:37+0000"
}
```

## Формат запроса на открытие платёжной формы {#section_cmq_3fp_1bc .section}

Формат запроса на открытие Payment Page для проведения выплаты с использованием платёжной карты соответствует описанному в статье [Организация взаимодействия](ru_pp_interaction_organisation.md#). При формировании такого запроса необходимо учитывать следующее:

1.  В запросе должны использоваться следующие обязательные параметры:
    -   `mode` — индикатор режима работы Payment Page, для которого следует указывать значение `payout`;
    -   `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции;
    -   `payment_id` — идентификатор платежа, соответствующий указанному в запросе на регистрацию выплаты и уникальный в рамках проекта;

        **Внимание:** Идентификаторы платежа \(`payment_id`\) в запросах на регистрацию выплаты и на открытие платёжной формы должны совпадать; в случае, если идентификаторы не совпадают, платёжная форма не открывается и пользователю отображается сообщение об ошибке.

    -   `uuid` — идентификатор выплаты, полученный в оповещении о результате регистрации;
    -   `customer_id` — идентификатор пользователя, соответствующий указанному в запросе на регистрацию выплаты и уникальный в рамках проекта;
    -   `customer_email` — адрес электронной почты пользователя, соответствующий указанному в запросе на регистрацию выплаты;
    -   `payment_amount` — сумма платежа, соответствующая указанной в запросе на регистрацию выплаты, в дробных единицах валюты;
    -   `payment_currency` — код валюты платежа, соответствующий указанному в запросе на регистрацию выплаты, в формате ISO 4217 alpha-3;
    -   `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\).
2.  Для использования токена платёжной карты, предварительно выбранной пользователем в веб-сервисе, этот токен должен указываться в параметре `account_token`.
3.  Для указания сведений об отправителе выплаты могут использоваться следующие параметры:
    -   `sender_wallet_id` — номер \(идентификатор\) кошелька отправителя.
    -   `sender_first_name` — имя отправителя.
    -   `sender_last_name` — фамилия отправителя.
    -   `sender_country` — код страны местонахождения отправителя в формате ISO 3166-1 alpha-2.
    -   `sender_state` — внутренний код территории местонахождения отправителя\(штата, провинции, региона или иной территориальной области\). Этот код представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса. Например, `ON` для провинции Онтарио в Канаде \(с международным кодом `CA-ON`\).
    -   `sender_city` — название города местонахождения отправителя.
    -   `sender_address` — название улицы и номер дома местонахождения отправителя.
    -   `sender_zip` — почтовый индекс местонахождения отправителя.
4.  Для указания сведений о получателе выплаты могут использоваться следующие параметры:

    -   `recipient_first_name` — имя получателя.
    -   `recipient_last_name` — фамилия получателя.
    -   `recipient_country` — код страны местонахождения получателя в формате ISO 3166-1 alpha-2.
    -   `recipient_state` — внутренний код территории местонахождения получателя\(штата, провинции, региона или иной территориальной области\). Этот код представляет собой вторую часть международного кода территории \(в формате ISO 3166-2\), без двухбуквенного кода страны и разделительного дефиса. Например, `ON` для провинции Онтарио в Канаде \(с международным кодом `CA-ON`\).
    -   `recipient_city` — название города местонахождения получателя.
    -   `recipient_address` — название улицы и номер дома местонахождения получателя.
    В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, из них обязательны к указанию сведения о местоположении получателя: код страны \(`recipient_country`\), название города \(`recipient_city`\), название улицы и номер дома \(`recipient_address`\) и, если код страны получателя соответствует [CA](references/ru/countries/CA.md) или [US](references/ru/countries/US.md), код штата, провинции или территории \(`recipient_state`\).

5.  Для отображения пользователю платёжной формы на заданном языке код этого языка в формате ISO 639-1 alpha-2 должен указываться в параметре `language_code`. Если этот параметр не передан, платёжная страница отображается на языке, определённом автоматически \(по языку браузера или по умолчанию;[подробнее](ru_PP_WigetLanguages.md)\).
6.  Для добавления описания платежа, отображаемого пользователю на странице с информацией о результате выплаты и доступного специалистам мерчанта через оповещения и интерфейс Dashboard, в запросе следует использовать параметр `payment_description`.
7.  Дополнительно в запросах могут использоваться любые другие параметры, доступные при работе в режиме Payout. Полный список параметров вызова Payment Page представлен в статье [Спецификация Payment Page API](ru_PP_Parameters.md).

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

```language-json
{
   "project_id": "91348",
   "payment_id": "cosmoshop_payout_1323",
   "payment_currency": "EUR",
   "payment_amount": "7000",
   "customer_id": "16061314",
   "customer_email": "p.jeltz@mail.com",  
   "mode": "payout",
   "uuid": "Lm3V9lmykig2d51Z/2Yrnue9+o5...",
   "signature": "xxPURAKgVtgW4PY7QlbIdS5u7gdoXkhXvZB..."

// при проведении выплаты по предварительно выбранной карте:
    "account_token":"959c664ad6045679d71d89caff6c242a0..."

}

```

## Формат оповещения о результате выплаты {#section_bh5_mx4_1bc .section}

Формат оповещения о результатах проведения выплат с использованием платёжных карт соответствует описанному в разделе [Работа с оповещениями](ru_platform_callbacks.md#).

**На уровень выше:**[Основные действия](ru_pp_basic_actions.md)