Выплата по токену

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

В данном разделе описана выплата через Gate по токену платежной карты.

Токен — это идентификатор, представляющий собой уникальную строку из 64 символов и связанный с определенной банковской картой и пользователем. Токен не содержит конфиденциальной информации и может храниться в вашей системе, не создавая угрозы нарушения стандартов безопасности по хранению данных банковских карт. Более подробную информацию о токенах см. в разделе Использование токенов.

Шаги проведения выплаты

Чтобы выполнить выплату через Gate по токену:

  1. Отправьте запрос с нужными параметрами и подписью на рабочий URL-адрес платежной платформы Rocketpay.
  2. При необходимости предоставьте дополнительную информацию о платеже.

    Подробнее о предоставлении дополнительной информации, см. Дополнение информации о платеже.

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

Далее в данном разделе представлена схема проведения выплаты в базовом случае, то есть без дополнения информации о платеже.



Рис.: Здесь описаны шаги выплаты через Gate

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

Далее рассказывается о структуре запроса на выплату по токену карты, а также о структуре оповещений с результатами выплаты.

Запрос

Далее представлена информация, необходимая для составления и отправки запроса на выплату.

HTTP-метод запроса POST
Формат тела запроса JSON
Конечная точка /v2/payment/card/payout/token
Полная спецификация конечной точки /v2/payment/card/payout/token
Табл. 1. Базовые параметры запроса на выплату

strictly required — параметр обязательно должен присутствовать в начальном запросе

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

required conditionally — обязательность параметра зависит от ситуации. Подробнее узнавайте в описании параметра.
Объект/массив Параметр Описание

general
object
strictly required

project_id
integer
strictly required

 Идентификатор проекта, полученный от Rocketpay при интеграции.

Пример: 123

payment_id
string
strictly required

 Идентификатор платежа, уникальный в рамках проекта.

Пример: payment_47

signature
string
strictly required

 Подпись запроса, составленная после определения всех параметров запроса. Подробнее о составлении подписи см. Использование подписи к данным.

customer
object
strictly required

id
string
strictly required

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

Пример: customer_123

first_name
string
strictly required

Имя пользователя.

Пример: John

middle_name
string
strictly required

Отчество или среднее имя пользователя.

Пример: Paul

last_name
string
strictly required

Фамилия пользователя.

Пример: Doe

ip_address
string
strictly required

IP-адрес устройства пользователя.

Пример: 198.51.100.47

payment
object
strictly required

amount
integer
strictly required

 Сумма выплаты в дробных единицах валюты без десятичной точки и пробелов за исключением случаев, когда у валюты нет дробной части. Если у валюты нет дробных единиц (то есть количество разрядов дробных единиц равно нулю), то в этом параметре нужно указывать сумму в основных единицах валюты. Подробнее о разрядах дробных единиц у валют см. Коды валют.

Пример: 100,00 USD передается как 10000

currency
string
strictly required

 Код валюты выплаты в формате ISO-4217 alpha-3.

Пример: USD

token
string
strictly required

   Токен банковской карты пользователя. Токен представляет собой уникальную строку из 64 символов, связанную с банковской картой.

Пример: f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654

Подробнее см. Использование токенов

card
object
required conditionally

card_holder
string
required conditionally

Имя держателя карты (в соответствии с указанным на карте).

Этот параметр обязателен, если выплата выполняется по токену, при создании которого имя держателя карты не использовалось.

Пример: JOHN DOE
При необходимости добавьте в запрос необязательные параметры, указанные в спецификации Gate: API Reference.
Прим.: Имя, отчество (или среднее имя) и фамилию получателя необходимо передавать для всех карт, за исключением выпущенных в Российской Федерации. Для последних передача этих параметров не обязательна.

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

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47"
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    },
    "token": "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7"
}

Оповещение (callback)

Уведомление о проведении выплаты платежная платформа возвращает в оповещении. Подробнее о структуре оповещений см. Оповещения (callbacks) в Gate.

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

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

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "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_123"
    },
    "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": 123,
    "payment": {
        "id": "payment_47",
        "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_123"
    },
    "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...=="
}

Ссылки по теме