Выплата

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

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

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

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

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

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

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

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

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

Рис.: Проведение выплаты через Gate

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

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

Формат запросов

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

POST-запрос должен отправляться к одной из следующих конечных точек:
- если выплата по номеру карты — к /v2/payment/card/payout;
- если выплата по токену, ассоциированному с картой, — к /v2/payment/card/payout/token;
В запросе должны присутствовать следующие объекты и параметры:
- general — объект, содержащий основные идентификационные сведения запроса:
  - project_id — идентификатор проекта, полученный от ITX при интеграции;
  - payment_id — идентификатор платежа, уникальный в рамках проекта мерчанта;
  - signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Подписывание и проверка подписи);
- customer — объект, содержащий сведения о получателе выплаты:
  - id — идентификатор получателя (пользователя) в рамках проекта мерчанта;
  - first_name — имя получателя;
  - middle_name — отчество или среднее имя получателя;
  - last_name — фамилия получателя;
  - ip_address — используемый IP-адрес;
  Прим.: Имя, отчество (или среднее имя) и фамилию получателя необходимо передавать для всех карт, за исключением выпущенных в Российской Федерации. Для последних передача этих параметров не обязательна.
- payment — объект, содержащий сведения о платеже:
  - amount — сумма выплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют;
  - currency — валюта платежа в формате ISO-4217 alpha-3.
В запросе должны содержаться сведения о платежной карте пользователя, на которую осуществляется выплата:
- card — объект, содержащий сведения о платежной карте:
  - pan — номер платежной карты. Этот параметр обязательный, если выплата выполняется по номеру карты.
  - month — месяц срока действия карты. Этот параметр обязателен, если в объекте payment был передан параметр best_before. В общем случае этот параметр необязательный, но в некоторых случаях он все-таки может быть обязательным, поэтому настоятельно рекомендуем уточнять эту информацию у своего курирующего менеджера ITX.
  - year — год срока действия карты. Этот параметр обязателен, если в объекте payment был передан параметр best_before. В общем случае этот параметр необязательный, но в некоторых случаях он все-таки может быть обязательным, поэтому настоятельно рекомендуем уточнять эту информацию у своего курирующего менеджера ITX.
  - card_holder — имя держателя, как указано на карте. Этот параметр обязательный, если выплата выполняется по номеру карты, а также если выплата осуществляется по токену, при создании которого имя держателя карты не использовалось.
  - token — токен карты. Это параметр обязателен, если выплата осуществляется по токену платежной карты, который вы ранее получили от платежной платформы.
Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

{
    general: {
        project_id: 874,
        payment_id: "ECT_TEST_1553840734526111",
        signature: "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ=="
    },
    //Номер карты для выплаты по номеру карты
    card: {
    pan: "123456123456"
    },
    customer: {
        id: "1",
        ip_address: "185.123.193.224"
    },
    payment: {
        amount: 15000,
        currency: "RUB"
    },
    //Токен карты для выплаты по токену
    token: "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7"
}

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

Для оповещений о результатах выплат на платежные карты используется стандартный формат, описание которого представлено в разделе Оповещения (callbacks) в Gate.

В следующем примере содержится информация о том, что в рамках проекта 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": "payout"
        },
        "account": {
            "number": "553691******0802"
        },
        "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": "payout"
        },
        "account": {
            "number": "553691******0802"
        },
        "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...=="
    }
}