Выплаты

В этом разделе представлена информация о проведении выплат. Общая информация, которая дополняет сведения из модели проведения платежей (Выплата), актуальна как для работы с платёжными картами, так и для работы с альтернативными инструментами, а подробная информация актуальна только для работы с картами. Подробная информация о проведении выплат при работе с альтернативными инструментами представлена в разделе Альтернативные платежные методы.

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

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

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

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

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

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

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

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

  3. Принять от платёжной платформы оповещение о результате выплаты.

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



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

  1. Пользователь на стороне веб-сервиса инициирует выплату.
  2. От веб-сервиса к платёжной платформе передаётся запрос на проведение выплаты через Gate.
  3. Запрос на проведение выплаты поступает в платёжную платформу.
  4. Выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  5. От платёжной платформы к веб-сервису направляется ответ с информацией о получении запроса и его корректности.
  6. В платёжной платформе выполняются дальнейшая обработка запроса и его отправка в платёжную среду: при работе с платёжными картами — в сервис банка, при работе с альтернативными платёжными инструментами — в платёжную систему.
  7. Выполняется обработка платежа.
  8. К платёжной платформе направляется уведомление о результате выплаты.
  9. От платёжной платформы к веб-сервису направляется оповещение о результате выплаты.
  10. От веб-сервиса пользователю направляется результат выплаты.

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

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

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

  1. POST-запрос должен отправляться к одной из следующих конечных точек:
  2. В запросе должны использоваться следующие объекты и параметры:
    • general — объект, содержащий основные идентификационные сведения запроса:
      • project_id — идентификатор проекта, полученный от ECommPay при интеграции;
      • payment_id — идентификатор платежа, уникальный в рамках проекта мерчанта;
      • signature — подпись запроса, составленная после указания целевых параметров (подробнее — в разделе Работа с подписью к данным);
    • customer — объект, содержащий сведения о получателе выплаты:
      • id — идентификатор получателя (пользователя) в рамках проекта мерчанта;
      • first_name — имя получателя;
      • middle_name — отчество или среднее имя получателя;
      • last_name — фамилия получателя;
      • ip_address — используемый IP-адрес;
      Прим.: Имя, отчество (или среднее имя) и фамилию получателя необходимо передавать для всех карт, за исключением выпущенных в Российской Федерации. Для карт CUP эти сведения должны передаваться на китайском языке.
    • payment — объект, содержащий сведения о платеже:
      • amount — сумма платежа в минорных единицах валюты;
      • currency — валюта платежа в формате ISO-4217 alpha-3.
  3. В запросе должны содержаться сведения о платёжной карте пользователя, на которую осуществляется выплата:
    • Если выплата по номеру карты — номер карты в параметре pan объекта card.

      Для проведения международных выплат вместе с номером карты также может понадобиться указать срок её действия и имя держателя в параметрах year, month и card_holder объекта card соответственно. Подробную информацию о проведении таких выплат можно получить у курирующего менеджера ECommPay.

    • Если выплата по токену — токен, полученный от ECommPay, в параметре token.
  4. В случае проведения P2P-выплаты в запросе рекомендуется передавать сведения об отправителе средств:
    • first_name — имя отправителя;
    • last_name — фамилия отправителя;
    • citizenship — гражданство отправителя;
    • residence — страна, резидентом которой является отправитель;
    • birthplace — место рождения отправителя;
    • billing — объект с информацией о платёжном адресе отправителя.
  5. При передаче параметра срока действия платежа payment.best_before необходимо также передавать параметры срока действия карты: card.month и card.year.
  6. Дополнительно могут использоваться любые другие параметры, указанные в спецификации.

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

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

{
    general: {
        project_id: 874,
        payment_id: "ECT_TEST_1553840734526111",
        signature: "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ==",
    },
    //Номер карты для выплаты по номеру карты
    card: {
        pan: "5536913256780802"
    },
    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": "4000135855554444",   
        "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-01-1995",
            "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": "sale"
        },
        "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": "sale"
        },
        "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...=="
    }
}