Выплаты

Notice: Эта статья посвящена тому, как проводить выплаты через Gate и какие запросы и оповещения при этом актуальны в случае прямого использования платёжных карт.

Помимо этой статьи для работы с выплатами могут быть полезны:

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

Общая информация

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

В платёжной платформе поддерживается один вариант для работы с выплатами через Gate — разовые единичные выплаты, в том числе выплаты P2P (person-to-person), но дополнительно обеспечивается возможность проведения массовых выплат через Dashboard (с автоматическим формированием требуемого количества платежей; подробнее — в разделе Контроль и проведение платежей).

В запросах на инициирование выплат реквизиты платёжных инструментов, как правило, необходимо передавать в явном виде, однако при работе с платёжными картами их можно указывать в форме токена, ассоциированного с реквизитами карты (подробнее о токенах — в разделе Использование токенов).

Схема проведения

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

Отправить запрос на выплату к конечной точке /v2/payment/{название метода}/payout[/token].
При необходимости выполнить вспомогательную процедуру — дополнить информацию о платеже (в настоящее время процедура не используется для работы с альтернативными платёжными методами).
Эта процедура используется, когда по запросу одной из сторон, участвующих в проведении платежа, требуется предоставить дополнительную информацию. Подробная информация о процедуре представлена в разделе Дополнение информации о платеже.
Принять от платёжной платформы оповещение о результате выплаты.

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

Рис. 1. Проведение выплаты через 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.
  - cryptocurrency_type — указатель категории цифровой валюты, обязательный при выполнении операций, связанных с использованием криптовалют через платёжную систему Visa, и допускающий одно из следующих значений:
    - cbdc — цифровая валюта центрального банка или токенизированный депозит, выпущенные определённым государством;
    - stablecoins_fiat_backed — цифровая валюта (в виде стейблкоина), чья стабильность обеспечивается за счёт резервов в определённой фиатной валюте;
    - native_tokens — цифровая валюта определённого блокчейна, необходимая для выполнения операций в его сети, в том числе для оплаты комиссий;
    - other — нефиатная валюта, которая заведомо не относится ни к одной из других категорий либо не может быть отнесена ни к одной из категорий при инициировании операции.
В запросе должны содержаться сведения о платёжной карте пользователя, на которую осуществляется выплата:
- Если выплата по номеру карты — номер карты в параметре pan объекта card.
  
  Для проведения международных выплат вместе с номером карты также может понадобиться указать срок её действия и имя держателя в параметрах year, month и card_holder объекта card соответственно. Подробную информацию о проведении таких выплат можно получить у курирующего менеджера ecommpay.
- Если выплата по токену — токен, полученный от ecommpay, в параметре token.
В случае проведения выплаты на карту платёжной системы Visa в запросе необходимо передавать дату рождения пользователя, указываемую в формате ДД-ММ-ГГГГ в параметре day_of_birth объекта sender.
В случае проведения выплаты на карту платёжной системы Visa, выпущенную в Канаде, в запросе необходимо передавать объект recipient, содержащий сведения о местонахождении получателя выплаты:
- country — код страны получателя в формате ISO 3166-1 alpha-2;
- city — город получателя;
- address — адрес получателя;
- если код страны соответствует CA или US, дополнительно следует передать параметр state — штат, провинция или другой регион получателя выплаты.
В случае проведения выплаты в рамках программы Money Transfer платёжной системы Visa на карту, выпущенную в Бразилии или Катаре, в запросе необходимо передавать номер телефона отправителя в параметре phone объекта sender.
В случае проведения выплаты на карту платёжной системы Mastercard стоит учитывать, что при передаче адреса пользователя в параметре address объекта customer его длина не должна превышать 50 символов.
В случае проведения выплаты в рамках программ сервиса 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-адрес пользователя, валюту и сумму платежа, а также номер или токен карты для зачисления средств.

Рис. 2. Пример запроса на выплату

{
    "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"
}

Рис. 3. Пример запроса на P2P-выплату

{
    "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"
    }
}

Формат оповещений

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

В следующем примере содержится информация о том, что в рамках проекта 874 проведена выплата в размере 100,00 USD на карту 553691******0802 пользователя customer_10.

Рис. 4. Пример данных о проведённой выплате

{
    {
        "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...=="
    }
}

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

Рис. 5. Пример данных об отказе в проведении выплаты

{
    {
        "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...=="
    }
}