# Выплаты {#ru_Gate_payout} статья о порядке проведения через Gate выплат **Прим.:** Эта статья посвящена тому, как проводить выплаты через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт. Помимо этой статьи для работы с выплатами могут быть полезны: - статья [Выплата](ru_platform_payout_model.md) модели проведения платежей с описанием того, как в целом проводятся выплаты в платёжной платформе Ecommpay, какие операции при этом используются и как меняются статусы этих платежей и операций; - статьи раздела [Платёжные методы](ru_pm_about.md) с описанием того, как проводить выплаты через Gate при работе с различными платёжными методами и какие запросы и оповещения могут быть актуальны при этом. ## Общая информация {#section_htd_ylv_cjb .section} Выплата — это тип платежа, в рамках которого осуществляется один \(разовый\) перевод денежных средств от мерчанта к пользователю. В платёжной платформе поддерживается один вариант для работы с выплатами через Gate — разовые единичные выплаты,в том числе выплаты P2P \(person-to-person\), но дополнительно обеспечивается возможность проведения массовых выплат через Dashboard \(с автоматическим формированием требуемого количества платежей; подробнее — в разделе [Контроль и проведение платежей](ru_dbl_payments.md#)\). В запросах на инициирование выплат реквизиты платёжных инструментов, как правило, необходимо передавать в явном виде, однако при работе с платёжными картами их можно указывать в форме токена, ассоциированного с реквизитами карты\(подробнее о токенах — в разделе [Использование токенов](ru_Gate_Token.md)\). ## Схема проведения {#section_lsx_3jl_ggb .section} Для проведения выплаты через Gate со стороны веб-сервиса необходимо: 1. Отправить запрос на выплату к конечной точке `/v2/payment/{название метода}/payout[/token]`. 2. При необходимости выполнить вспомогательную процедуру — дополнить информацию о платеже\(в настоящее время процедура не используется для работы с альтернативными платёжными методами\). Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе [Дополнение информации о платеже](ru_Gate_Clarification.md). 3. Принять от платёжной платформы оповещение о результате выплаты. Схема проведения выплаты в базовом случае — без выполнения вспомогательной процедуры — представлена далее. ![](images/ru_uml_gate_payout.svg) 1. Пользователь на стороне веб-сервиса инициирует выплату. 2. От веб-сервиса к платёжной платформе передаётся запрос на проведение выплаты через Gate. 3. Запрос на проведение выплаты поступает в платёжную платформу. 4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи. 5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности. 6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в платёжную среду: при работе с платёжными картами — в сервис банка, при работе с альтернативными платёжными инструментами — в платёжную систему. 7. Выполняется обработка платежа. 8. К платёжной платформе направляется уведомление о результате выплаты. 9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты. 10. От веб-сервиса пользователю направляется результат выплаты. Информация о формате запросов и параметрах инициирования выплат по номеру \(токену\) карты, а также о формате оповещений о результатах выплат приведена далее. Информацию о возможных статусах выплаты можно найти [в соответствующей статье](ru_platform_payout_model.md). ## Формат запросов {#section_t11_mfk_1jb .section} При формировании запросов для выплаты на платёжную карту необходимо учитывать следующее: 1. POST-запрос должен отправляться к одной из следующих конечных точек: - если выплата по номеру карты — к [/v2/payment/card/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout); - если выплата по токену, ассоциированному с картой, — к [/v2/payment/card/payout/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-payout-token); - если выплата P2P — к [/v2/payment/individual/payout](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-individual-payout); 2. В запросе должны использоваться следующие объекты и параметры: - `general` — объект, содержащий основные идентификационные сведения запроса: - `project_id` — идентификатор проекта, полученный от Ecommpay при интеграции; - `payment_id` — идентификатор платежа, уникальный в рамках проекта мерчанта; - `signature` — подпись запроса, составленная после указания целевых параметров \(подробнее — в разделе [Работа с подписью к данным](ru_platform_signature.md#)\); - `customer` — объект, содержащий сведения о получателе выплаты: - `id` — идентификатор получателя \(пользователя\) в рамках проекта мерчанта; - `first_name` — имя получателя; - `middle_name` — отчество или среднее имя получателя; - `last_name` — фамилия получателя; - `ip_address` — используемый IP-адрес. **Прим.:** Имя, отчество \(или среднее имя\) и фамилию получателя необходимо передавать для всех карт, за исключением выпущенных в Российской Федерации. Для последних допускается не передавать эти параметры, но в некоторых случаях это может приводить к отклонению платежей. Чтобы повысить вероятность проведения платежей со стороны эмитентов, для таких карт рекомендуется передавать фамилию и имя получателя или хотя бы один из этих двух параметров. Информацию о передаче имени, отчества и фамилии пользователя для выплат с использованием российских карт можно уточнять у курирующего менеджера Ecommpay. Сведения об имени, отчестве \(или среднем имени\) и фамилии получателя должны передаваться базовой латиницей для всех карт, за исключением карт CUP, для которых эти данные передаются китайским иероглифическим письмом. Также для выплат в рамках программ сервиса MoneySend платёжной системы Mastercard, в которых отправителем является физическое лицо, обязательно передавать сведения об имени и фамилии получателя в объекте `recipient`. В таких случаях сведения об имени и фамилии получателя в объекте `customer` можно не передавать \([подробнее](ru_Gate_payout.md#li_mpn_wmt_tqb)\). Это правило действует для всех карт, независимо от страны их выпуска. - `payment` — объект, содержащий сведения о платеже: - `amount` — сумма платежа в дробных единицах валюты; - `currency` — валюта платежа в формате ISO-4217 alpha-3. - `cryptocurrency_type` — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжные системы Mastercard и Visa, и допускающий одно из следующих значений: - `cbdc` — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством; - `stablecoins_fiat_backed` — цифровая валюта \(в виде стейблкоина\), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте; - `native_tokens` — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий; - `other` — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции. 3. В запросе должны содержаться сведения о платёжной карте пользователя, на которую осуществляется выплата: - Если выплата по номеру карты — номер карты в параметре `pan` объекта `card`. Для проведения международных выплат вместе с номером карты также может понадобиться указать срок её действия и имя держателя в параметрах `year`, `month` и `card_holder` объекта `card` соответственно. Подробную информацию о проведении таких выплат можно получить у курирующего менеджера Ecommpay. - Если выплата по токену — токен, полученный от Ecommpay, в параметре `token`. 4. В случае проведения выплаты на карту платёжной системы Visa в запросе необходимо передавать дату рождения пользователя, указываемую в формате `ДД-ММ-ГГГГ` в параметре `day_of_birth` объекта `sender`. 5. В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, в запросе необходимо передавать объект `recipient`, содержащий сведения о местонахождении получателя выплаты: - `country` — код страны получателя в формате ISO 3166-1 alpha-2; - `city` — город получателя; - `address` — адрес получателя; - если код страны соответствует [CA](references/ru/countries/CA.md) или [US](references/ru/countries/US.md), дополнительно следует передать параметр `state` — штат, провинция или другой регион получателя выплаты. 6. В случае проведения выплаты в рамках программы Money Transfer платёжной системы Visa на карту, выпущенную в Бразилии или Катаре, в запросе необходимо передавать номер телефона отправителя в параметре `phone` объекта `sender`. 7. В случае проведения выплаты на карту платёжной системы Mastercard стоит учитывать, что при передаче адреса пользователя в параметре `address` объекта `customer` его длина не должна превышать 50 символов. 8. В случае проведения выплаты в рамках программ сервиса MoneySend платёжной системы Mastercard, в которой отправителем является физическое лицо, в запросе необходимо передавать информацию об имени и фамилии получателя в параметрах `first_name` и `last_name` объекта `recipient`, а также информацию об отправителе выплаты в объекте `sender`: - номер платёжного инструмента отправителя — `pan` для карты или `wallet_id` для электронного кошелька; - `first_name` — имя отправителя; - `last_name` — фамилия отправителя; - `address` — адрес отправителя; - `city` — город отправителя; - `zip` — почтовый индекс отправителя; - `country` — код страны отправителя в формате ISO 3166-1 alpha-2; - если код страны соответствует [CA](references/ru/countries/CA.md) или [US](references/ru/countries/US.md), дополнительно следует передать параметр `state` — штат, провинция или другой регион отправителя выплаты. 9. В случае проведения P2P-выплаты в запросе рекомендуется передавать сведения об отправителе средств: - `first_name` — имя отправителя; - `last_name` — фамилия отправителя; - `citizenship` — гражданство отправителя; - `residence` — страна, резидентом которой является отправитель; - `birthplace` — место рождения отправителя; - `billing` — объект с информацией о платёжном адресе отправителя. 10. Дополнительно могут использоваться любые другие параметры, указанные в спецификации. Таким образом, корректный запрос для выплаты по номеру \(токену\) карты должен содержать идентификаторы проекта и платежа, подпись, идентификатор и IP-адрес пользователя, валюту и сумму платежа, а также номер или токен карты для зачисления средств. ```language-json { "general": { "project_id": 874, "payment_id": "1553840734526111", "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ==" }, //Номер карты для выплаты по номеру карты "card": { "pan": "5413330000000019" }, "customer": { "id": "1", "ip_address": "185.123.193.224" }, "payment": { "amount": 15000, "currency": "EUR" }, //Токен карты для выплаты по токену "token": "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7" } ``` ``` {#codeblock_xbn_spb_f1c} { "general": { "project_id": 100, "payment_id": "Payment 12", "signature": "2tlMuYxLW9Yu6RETr8pdCfmi0UPE8euD+2AbrQgJgu...==" }, "card": { "pan": "4242424242424242", "year": 2020, "month": 11 }, "customer": { "ip_address": "127.0.0.1", "id": "New", "phone": "999123456", "first_name": "John", "middle_name": "Jr", "last_name": "Jonson", "datetime": "2017-10-04T19:06:31+05:00", "birthplace": "Manchester", "identify": { "doc_number": "4666 123456", "doc_type": "Passport", "doc_issue_date": "20.12.2012", "doc_issue_by": "12346" }, "billing": { "country": "GB", "city": "London", "address": "Level st, 23", "postal": "112233" }, "day_of_birth": "05-06-1981" }, "sender": { "phone": "39999999999", "first_name": "Jack", "middle_name": "Willy", "last_name": "Jackson", "datetime": "2018-12-05T19:06:31+05:00", "birthplace": "Manchester", "residence": "BL", "citizenship": "LV", "identify": { "doc_number": "1234 654321", "doc_type": "Passport", "doc_issue_date": "07-08-2014", "doc_issue_by": "23456" }, "billing": { "country": "GB", "city": "London", "address": "Level st, 25", "postal": "406879" }, "day_of_birth": "07-08-1993" }, "payment": { "amount": 5000, "currency": "GBP" } } ``` ## Формат оповещений {#section_wsx_3jl_ggb .section} Для оповещений о результатах выплат на платёжные карты используется стандартный формат, описание которого представлено в разделе [Работа с оповещениями](ru_platform_callbacks.md#). В следующем примере содержится информация о том, что в рамках проекта `874` проведена выплата в размере `100,00 USD` на карту `553691******0802` пользователя `customer_10`. ```language-json { { "project_id": 874, "payment": { "id": "3013", "type": "payout", "status": "success", "date": "2019-06-24T11:08:49+0000", "method": "card", "sum": { "amount": 10000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019" }, "customer": { "id": "customer_10" }, "operation": { "id": 14, "type": "payout", "status": "success", "date": "2019-06-24T11:08:49+0000", "created_date": "2019-06-24T11:07:42+0000", "request_id": "71228f54d21e776a481", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 1496, "payment_id": "60-1c6072de6000", "date": "2019-06-24T11:08:47+0000", "auth_code": "" }, "code": "0", "message": "Success" }, "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...==" } } ``` Далее представлен пример данных из оповещения с информацией об отказе в проведении выплаты. Платёж отклонён из-за превышения максимально допустимого размера выплаты. ```language-json { { "project_id": 874, "payment": { "id": "3013", "type": "payout", "status": "decline", "date": "2019-06-24T11:08:49+0000", "method": "card", "sum": { "amount": 10000, "currency": "USD" }, "description": "" }, "account": { "number": "541333******0019" }, "customer": { "id": "customer_10" }, "operation": { "id": 14, "type": "payout", "status": "decline", "date": "2019-06-24T11:08:49+0000", "created_date": "2019-06-24T11:07:42+0000", "request_id": "71228f54d21e776a481", "sum_initial": { "amount": 10000, "currency": "USD" }, "sum_converted": { "amount": 10000, "currency": "USD" }, "provider": { "id": 1496, "payment_id": "60-1c6072de6000", "date": "2019-06-24T11:08:47+0000", "auth_code": "" }, "code": "3104", "message": "Payment Constraint Invalid Payout Amount" }, "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...==" } } ``` **На уровень выше:**[Gate](ru_Gate_Integration_About.md)