Выплаты
В этом разделе представлена информация о проведении выплат. Общая информация, которая дополняет сведения из модели проведения платежей (Выплата), актуальна как для работы с платёжными картами, так и для работы с альтернативными инструментами, а подробная информация актуальна только для работы с картами. Подробная информация о проведении выплат при работе с альтернативными инструментами представлена в разделе Методы.
Общая информация
Выплата — это тип платежа, в рамках которого осуществляется один (разовый) перевод денежных средств от мерчанта к пользователю.
В платёжной платформе поддерживается один вариант для работы с выплатами через Gate — разовые единичные выплаты, в том числе выплаты P2P (person-to-person), но дополнительно обеспечивается возможность проведения массовых выплат через Dashboard (с автоматическим формированием требуемого количества платежей; подробнее — в разделе Контроль и проведение платежей).
В запросах на инициирование выплат реквизиты платёжных инструментов, как правило, необходимо передавать в явном виде, однако при работе с платёжными картами их можно указывать в форме токена, ассоциированного с реквизитами карты (подробнее о токенах — в разделе Использование токенов).
При работе с выплатами в платёжной платформе ecommpay поддерживается возможность повторных попыток их выполнения в тех случаях, когда первоначальная попытка отклонена. Подробная информация об этой возможности представлена в разделе Повторные попытки выплат.
Схема проведения
Для проведения выплаты через Gate со стороны веб-сервиса необходимо:
- Отправить запрос на выплату к конечной точке
/v2/payment/{название метода}/payout[/token]
. - При необходимости выполнить вспомогательную процедуру — дополнить информацию о платеже (в настоящее время процедура не используется для работы с альтернативными платёжными методами).
Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе Дополнение информации о платеже.
- Принять от платёжной платформы оповещение о результате выплаты.
Схема проведения выплаты в базовом случае — без выполнения вспомогательной процедуры — представлена далее.
Рис.: Проведение выплаты через Gate
- Пользователь на стороне веб-сервиса инициирует выплату.
- От веб-сервиса к платёжной платформе передаётся запрос на проведение выплаты через Gate.
- Запрос на проведение выплаты поступает в платёжную платформу.
- Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
- В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в платёжную среду: при работе с платёжными картами — в сервис банка, при работе с альтернативными платёжными инструментами — в платёжную систему.
- Выполняется обработка платежа.
- К платёжной платформе направляется уведомление о результате выплаты.
- От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
- От веб-сервиса пользователю направляется результат выплаты.
Информация о формате запросов и параметрах инициирования выплат по номеру (токену) карты, а также о формате оповещений о результатах выплат приведена далее.
Формат запросов
При формировании запросов для выплаты на платёжную карту необходимо учитывать следующее:
- POST-запрос должен отправляться к одной из следующих конечных точек:
- если выплата по номеру карты — к /v2/payment/card/payout;
- если выплата по токену, ассоциированному с картой, — к /v2/payment/card/payout/token;
- если выплата P2P — к /v2/payment/individual/payout;
- В запросе должны использоваться следующие объекты и параметры:
general
— объект, содержащий основные идентификационные сведения запроса:project_id
— идентификатор проекта, полученный от ecommpay при интеграции;payment_id
— идентификатор платежа, уникальный в рамках проекта мерчанта;signature
— подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
customer
— объект, содержащий сведения о получателе выплаты:id
— идентификатор получателя (пользователя) в рамках проекта мерчанта;first_name
— имя получателя;middle_name
— отчество или среднее имя получателя;last_name
— фамилия получателя;ip_address
— используемый IP-адрес;
Прим.:Имя, отчество (или среднее имя) и фамилию получателя необходимо передавать для всех карт, за исключением выпущенных в Российской Федерации. Для последних допускается не передавать эти параметры, но в некоторых случаях это может приводить к отклонению платежей. Чтобы повысить вероятность проведения платежей со стороны эмитентов, для таких карт рекомендуется передавать фамилию и имя получателя или хотя бы один из этих двух параметров. Информацию о передаче имени, отчества и фамилии пользователя для выплат с использованием российских карт можно уточнять у курирующего менеджера ecommpay.
Сведения об имени, отчестве (или среднем имени) и фамилии получателя должны передаваться базовой латиницей для всех карт, за исключением карт CUP, для которых эти данные передаются китайским иероглифическим письмом.
Также для выплат в рамках программ сервиса MoneySend платёжной системы Mastercard, в которых отправителем является физическое лицо, обязательно передавать сведения об имени и фамилии получателя в объекте
recipient
. В таких случаях сведения об имени и фамилии получателя в объектеcustomer
можно не передавать (подробнее). Это правило действует для всех карт, независимо от страны их выпуска.payment
— объект, содержащий сведения о платеже:amount
— сумма платежа в дробных единицах валюты;currency
— валюта платежа в формате ISO-4217 alpha-3.
- В запросе должны содержаться сведения о платёжной карте пользователя, на которую осуществляется выплата:
-
Если выплата по номеру карты — номер карты в параметре
pan
объектаcard
.Для проведения международных выплат вместе с номером карты также может понадобиться указать срок её действия и имя держателя в параметрах
year
,month
иcard_holder
объектаcard
соответственно. Подробную информацию о проведении таких выплат можно получить у курирующего менеджера ecommpay. - Если выплата по токену — токен, полученный от ecommpay, в параметре
token
.
-
- В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, в запросе необходимо передавать объект
recipient
, содержащий сведения о местонахождении получателя выплаты: - В случае проведения выплаты в рамках программы Money Transfer платёжной системы Visa на карту, выпущенную в Бразилии или Катаре, в запросе необходимо передавать номер телефона отправителя в параметре
phone
объектаsender
. - В случае проведения выплаты в рамках программ сервиса 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 или US, дополнительно следует передать параметр
state
— штат, провинция или другой регион отправителя выплаты.
- номер платёжного инструмента отправителя —
- В случае проведения P2P-выплаты в запросе рекомендуется передавать сведения об отправителе средств:
first_name
— имя отправителя;last_name
— фамилия отправителя;citizenship
— гражданство отправителя;residence
— страна, резидентом которой является отправитель;birthplace
— место рождения отправителя;billing
— объект с информацией о платёжном адресе отправителя.
- Дополнительно могут использоваться любые другие параметры, указанные в спецификации.
Таким образом, корректный запрос для выплаты по номеру (токену) карты должен содержать идентификаторы проекта и платежа, подпись, идентификатор и IP-адрес пользователя, валюту и сумму платежа, а также номер или токен карты для зачисления средств.
Рис.: Пример запроса на выплату
{ 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: "RUB" }, //Токен карты для выплаты по токену token: "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7" }
Рис.: Пример запроса на P2P-выплату
{ "general": { "project_id": 35, "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": "Караганда", "identify": { "doc_number": "4666 123456", "doc_type": "Паспорт гражданина РФ", "doc_issue_date": "20.12.2012", "doc_issue_by": "12346" }, "billing": { "country": "RU", "city": "City 17", "address": "г. Москва, малая Бронная ул., д. 65, кв. 23", "postal": "112233" }, "day_of_birth": "05-06-1981" }, "sender": { "phone": "89999999999", "first_name": "Иванов", "middle_name": "Петрович", "last_name": "Иван", "datetime": "2018-12-05T19:06:31+05:00", "birthplace": "Таймырь", "residence": "BL", "citizenship": "LV", "identify": { "doc_number": "1234 654321", "doc_type": "Паспорт гражданина РФ", "doc_issue_date": "07-08-2014", "doc_issue_by": "23456" }, "billing": { "country": "RU", "city": "Омск", "address": "г. Омск, малая Иркутская ул., д. 78, кв. 56", "postal": "406879" }, "day_of_birth": "07-08-1993" }, "payment": { "amount": 5000, "currency": "RUB" } }
Формат оповещений
Для оповещений о результатах выплат на платёжные карты используется стандартный формат, описание которого представлено в разделе Оповещения.
В следующем примере содержится информация о том, что в рамках проекта 874
проведена выплата в размере 100,00 USD
на карту 553691******0802
пользователя customer_10
.
Рис.: Пример данных о проведённой выплате
{ { "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...==" } }
Далее представлен пример данных из оповещения с информацией об отказе в проведении выплаты. Платёж отклонён из-за превышения максимально допустимого размера выплаты.
Рис.: Пример данных об отказе в проведении выплаты
{ { "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...==" } }