Сплит-платеж

Обзор

При проведении платежей может возникнуть необходимость сделать сплит платежа — распределить его сумму на несколько балансов. Например, такая возможность нужна при работе агрегатора или онлайн-платформы, которые сотрудничают со множеством партнеров — для выделения в платеже доли дохода самого агрегатора, доли его партнера и выплаты оставшейся суммы исполнителю (курьеру, репетитору, водителю такси и т. п.). Использование сплит-платежа гибко автоматизирует процесс распределения денежных средств между всеми участниками и облегчает взаиморасчеты: после оплаты сервиса или услуги клиентом агрегатора платеж сразу же распределяется между балансами всех сторон. Чтобы проводить платежи с такими особенностями, платежная платформа предоставляет возможность распределить сумму платежа между несколькими балансами. Далее рассказывается, как создавать запросы на сплит-платежи.

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

Запрос

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

Табл. 1. Конечные точки для запроса на оплату с использованием сплит-платежа
Конечная точка	Описание
`/v2/payment/card/sale`	Запрос на списание средств со счета пользователя при оплате в одну стадию
`/v2/payment/card/auth`	Запрос на предварительную блокировку средств на счете пользователя при оплате в две стадии
`/v2/payment/card/cancel`	Запрос на отмену блокировки средств на счете пользователя при оплате в две стадии
`/v2/payment/card/capture`	Запрос на списание заблокированных средств со счета пользователя при оплате в две стадии

Чтобы распределить сумму платежа между несколькими балансами, в запросе, помимо обязательных параметров, нужно добавить описанные в следующей таблице параметры в объектах rewards и account.

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

Объект Параметр Описание

rewards
array
strictly required

reward_amount
integer
strictly required

Доход партнера — сумма, которая заносится на баланс партнера. Значение должно быть больше или равно нулю.

Пример: 20000

income_amount
integer
strictly required

Доход агрегатора — сумма, которая заносится на баланс агрегатора. Значение должно быть больше или равно нулю.

Пример: 10000

account
object
strictly required

number
string
strictly required

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

Пример: +71234567890

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

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

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "ktILmxlh6Yxm+U1jR52DnxnF\/bXbgecVXlulASc7Il738fWQ2q9qL9uR=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com",
        "phone": "+79876543210"
    },
"rewards": {      // объект с информацией о сплит-платеже
        "reward_amount": 20000,
        "income_amount": 10000
    },
    "payment": {
        "amount": 100000,
        "currency": "KZT"
    },
    "account": {
        "number": "+71234567890"
    },
    "card": {
        "pan": "1234567890123456",
        "year": 2026,
        "month": 2,
        "card_holder": "John Doe",
        "cvv": "123"
    },
    "return_url": {
        "success": "http://example.com/success",
        "decline": "http://example.com/decline",
        "return": "http://example.com/return"
    }
}

Рис.: Пример запроса для списания средств при оплате в две стадии с использованием сплит-платежа

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "YlA+RIbwvmvjowWJ1tphqBstszAPpq0OIWvrg65nk1EoH6lkt3MWVMA7I/HyDx=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com",
        "phone": "+79876543210"
    },
"rewards": {    // объект с информацией о сплит-платеже  
    "reward_amount": 20000,
    "income_amount": 10000
  },
    "payment": {
        "amount": 100000,
        "currency": "KZT"
    },
    "account": {
        "number": "+71234567890"
    }
}

Сплит-платеж с распределением суммы на разные балансы выполняется следующим образом. При запросе в рамках одностадийной оплаты или на втором этапе двухстадийной оплаты вместе с конечной суммой передаются данные о доходе агрегатора и сумме выплат партнеру, оставшаяся сумма — выплата исполнителю. Это можно описать следующей формулой:

Выплата исполнителю = Сумма платежа − Доход партнера − Доход агрегатора

Допустим, что сумма платежа равна 1 000,00 KZT. Тогда:

Доход партнера составит 200,00 KZT,
Доход агрегатора равен 100,00 KZT,
Выплата исполнителю равна 700,00 KZT (1000 − 100 − 200).

Информация об этих операциях передается агрератору в оповещениях, структура которых описана далее.

Возврат

Для сплит-платежей доступна процедура возврата. Возврат средств пользователю может производиться по разным сценариям в зависимости от баланса (или балансов), с которого будут списываться средства, и того, какую часть платежа требуется вернуть. При возврате всей суммы сплит-платежа могут задействоваться оба сценария. Далее подробнее описаны доступные сценарии.

Возврат по Сценарию 1

Сценарий 1 подразумевает возврат средств пользователю за счет списания средств с балансов агрегатора и партнера. В этом случае используется стандартная процедура возврата, подробнее о которой см. Возврат средств после оплаты. Этот сценарий позволяет вернуть комиссию агрегатора или партнера, а также сумму, выплаченную исполнителю — если списать ее с баланса исполнителя невозможно.

Далее представлена информация, необходимая для создания и отправки запроса на возврат средств пользователю путем списания средств с баланса агрегатора (сценарий 1).

HTTP-метод запроса	POST
Формат тела запроса	JSON
Конечная точка	/v2/payment/card/refund
Полная спецификация конечной точки	/v2/payment/card/refund

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

Объект Параметр Описание

general
object
strictly required

project_id
integer
strictly required

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

Пример: 123

payment_id
string
strictly required

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

Пример: payment_47

signature
string
strictly required

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

customer
object
strictly required

id
string
strictly required

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

Пример: customer_123

ip_address
string
strictly required

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

Пример: 198.51.100.47

first_name
string
strictly required

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

Пример: John

last_name
string
strictly required

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

Пример: Doe

email
string
strictly required

Адрес электронной почты пользователя.

Пример: johndoe@example.com

payment
object
strictly required

amount
string
strictly required

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

Пример: 700.00 KZT передается как 70000

currency
string
strictly required

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

Пример: KZT

description
string
strictly required

Комментарий или описание возврата.

Пример: refund

При необходимости добавьте в запрос необязательные параметры, указанные в спецификации Gate: API Reference.

Вот пример тела запроса на возврат за счет средств агрегатора (сценарий 1):

Рис.: Пример запроса на возврат за счет средств агрегатора (сценарий 1)

{
    "general": {
        "payment_id": "payment_47",
        "project_id": 123,
        "signature": "8N9ZT4oDSHKbjhmNDYuompnSft7kcdQPL5Emfr4jrrWi2jqZ1aFIhLQ=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "amount": 7000,
        "currency": "KZT",
        "description": "refund"
    }
}

Возврат по Сценарию 2

Сценарий 2 подразумевает возврат средств пользователю за счет списания средств с баланса исполнителя. В этом случае с баланса списывается вся сумма, выплаченная исполнителю. Возврат может быть недоступен из-за недостатка средств на балансе исполнителя или из-за того, что истекло время блокировки средств в кошельке исполнителя. В таком случае агрегатор может инициировать повторный возврат по сценарию 1, а сумма, равная выплате исполнителю, спишется с баланса агрегатора. Время блокировки средств в кошельке исполнителя ограничено, но его можно изменять. Подробности уточняйте у вашего курирующего менеджера JetPay.

Далее представлена информация, необходимая для создания и отправки запроса на возврат средств пользователю за счет списания средств с баланса исполнителя (Сценарий 2).

HTTP-метод запроса	POST
Формат тела запроса	JSON
Конечная точка	/v2/payment/card/payout_refund

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

Объект Параметр Описание

general
object
strictly required

project_id
integer
strictly required

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

Пример: 123

payment_id
string
strictly required

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

Пример: payment_47

signature
string
strictly required

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

customer
object
strictly required

id
string
strictly required

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

Пример: customer_123

ip_address
string
strictly required

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

Пример: 198.51.100.47

first_name
string
strictly required

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

Пример: John

last_name
string
strictly required

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

Пример: Doe

email
string
strictly required

Адрес электронной почты пользователя.

Пример: johndoe@example.com

payment
object
strictly required

description
string
strictly required

Комментарий или описание возврата.

Пример: Refund operation

При необходимости добавьте в запрос необязательные параметры, указанные в спецификации Gate: API Reference.

Вот пример тела запроса на возврат за счет средств исполнителя (Сценарий 2):

Рис.: Пример запроса на возврат за счет средств исполнителя (Сценарий 2)

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "VG8l/v4Up+hK0Tqy0GbY3E6gt6IaZHn7T3gR2g5ersnSK0GPuiAuqRf7=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47",
        "first_name": "John",
        "last_name": "Doe",
        "email": "johndoe@example.com"
    },
    "payment": {
        "description": "Refund operation"
    }
}

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

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

Рис.: Пример оповещения об успешном проведении оплаты в одну стадию

{
        "customer": {
            "id": "customer_123"
        },
        "account": {
            "number": "123456******3456",
            "token": "3e08a2e6c16938ad3ae...ab32e6648f4ca8e9d549",
            "type": "visa",
            "id": 123456,
            "card_holder": "John Doe",
            "expiry_month": "02",
            "expiry_year": "2026"
        },
        "project_id": 123,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "success",
            "date": "2025-01-17T10:54:07+0000",
            "method": "card",
            "sum": {
                "amount": 100000,
                "currency": "KZT"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 100000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "KZT"
            },
            "code": "0",
            "message": "Success",
            "provider": {
                "id": 11451,
                "payment_id": "payment_47",
                "auth_code": "556764",
                "endpoint_id": 11451
            },
            "id": 28,
            "type": "sale",
            "status": "success",
            "date": "2025-01-17T10:54:07+0000",
            "created_date": "2025-01-17T10:54:04+0000",
            "request_id": "518dd5de58de0f660bd1d1cb0dc4a947f7a400...9ec26827"
        },
        "signature": "4dL6PkYjtoGA09LByGbZaxdeFCl4MqtSnGNvLJVBiPvJXSUWjj0RV"
    }

Рис.: Пример оповещения о неуспешной оплате в одну стадию из-за недостатка средств на карте

{
        "customer": {
            "id": "customer_123"
        },
        "account": {
            "number": "123456******3456",
            "token": "2f192a181507193439...0ac902380d33db5087376",
            "type": "mastercard",
            "card_holder": "John Doe",
            "expiry_month": "05",
            "expiry_year": "2026"
        },
        "project_id": 123,
        "payment": {
            "id": "payment_47",
            "type": "purchase",
            "status": "decline",
            "date": "2025-01-17T10:54:05+0000",
            "method": "card",
            "sum": {
                "amount": 100000,
                "currency": "KZT"
            },
            "description": ""
        },
        "operation": {
            "sum_initial": {
                "amount": 100000,
                "currency": "KZT"
            },
            "sum_converted": {
                "amount": 100000,
                "currency": "KZT"
            },
            "code": "10105",
            "message": "Insufficient funds on card",
            "provider": {
                "id": 15681,
                "payment_id": "payment_47",
                "auth_code": "",
                "endpoint_id": 15681
            },
            "id": 31,
            "type": "sale",
            "status": "decline",
            "date": "2025-01-17T10:54:05+0000",
            "created_date": "2025-01-17T10:54:01+0000",
            "request_id": "5b1ff18755b383e4d705f5f9f8c475a536856901...4b7cec9"
        },
        "signature": "OSmZfuikSNs3q3MEnENf5l8gE08rXevGZdcRoUsQvghr2QJstoO0uV"
    }

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

{
    "payment": {
      "date": "2025-01-14T03:00:52+0000",
      "method": "card",
      "sum": {
        "amount": 100000,
        "currency": "KZT"
      },
      "id": "payment_47",
      "type": "purchase",
      "status": "success",
      "description": ""
    },
    "customer": {
      "id": "customer_123"
    },
    "account": {
      "number": "12345678901234567",
      "token": "4770f7cbda8d43da43b9a...26813a75dbd76906527fb95",
      "type": "visa",
      "id": 1234567890,
      "card_holder": "John Doe",
      "expiry_month": "12",
      "expiry_year": "2029"
    },
    "project_id": 123,
    "card_country": "KZ",
    "operation": {
      "provider": {
        "id": 10771,
        "payment_id": "payment_47",
        "auth_code": "",
        "endpoint_id": 10771
      },
      "id": 28,
      "type": "capture",
      "status": "success",
      "date": "2025-01-14T03:00:52+0000",
      "sum_initial": {
        "amount": 100000,
        "currency": "KZT"
      },
      "created_date": "2025-01-14T03:00:47+0000",
      "request_id": "17b2b4c9aa1f41374c2ee6db4a8803e7c141b114...28a044ad96bd",
      "sum_converted": {
        "amount": 100000,
        "currency": "KZT"
      },
      "code": "0",
      "message": "Success"
    },
    "signature": "N4lFW+DKlTL4/FxwCntMfZBHwr2EMP7GwOkwKS5SazFOqgb6BSgGGp+AX"
  }

Рис.: Пример оповещения о неуспешной оплате из-за недостатка средств на карте

{
    "payment": {
      "date": "2025-01-02T10:06:39+0000",
      "method": "card",
      "sum": {
        "amount": 100000,
        "currency": "KZT"
      },
      "id": "payment_47",
      "type": "purchase",
      "status": "decline",
      "description": ""
    },
    "customer": {
      "id": "customer_123"
    },
    "account": {
      "number": "123456******3456",
      "token": "d9ff53c30a1575dc166a95...5611afb172df53493c6",
      "type": "visa",
      "card_holder": "John Doe",
      "expiry_month": "09",
      "expiry_year": "2030"
    },
    "project_id": 123,
    "card_country": "KZ",
    "operation": {
      "provider": {
        "id": 15681,
        "payment_id": "payment_47",
        "auth_code": "",
        "endpoint_id": 15681
      },
      "id": 31,
      "type": "auth",
      "status": "decline",
      "date": "2025-01-02T10:06:39+0000",
      "sum_initial": {
        "amount": 100000,
        "currency": "KZT"
      },
      "created_date": "2025-01-02T10:06:36+0000",
      "request_id": "58ee05b37d847cda1c98f67bc824510962ddeea579b...88c92a833e4f0c75ec92",
      "sum_converted": {
        "amount": 100000,
        "currency": "KZT"
      },
      "code": "10105",
      "message": "Insufficient funds on card"
    },
    "signature": "0pcxo1NMe7aW4Aq15pw4ke0HerCi+lLo2OUuPm41SgnYP+wgUqO/a8qS4vkOI/8QTV"
  }
}

Рис.: Пример оповещения об успешном возврате за счет средств с баланса агрегатора (сценарий 1)

{
    "payment": {
        "date": "2025-01-25T12:43:35+0000",
        "method": "qckwallet",
        "sum": {
            "amount": 0,
            "currency": "KZT"
        },
        "id": "payment_48",
        "type": "payout",
        "status": "refunded",
        "associated_payment_id": "payment_47",
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "+7123456789"
    },
    "project_id": 123,
    "operation": {
        "provider": {
            "id": 22652,
            "payment_id": "",
            "auth_code": ""
        },
        "id": 58988010158936,
        "type": "payout refund",
        "status": "success",
        "date": "2025-01-25T12:43:35+0000",
        "sum_initial": {
            "amount": 1000,
            "currency": "KZT"
        },
        "created_date": "2025-01-25T12:43:32+0000",
        "request_id": "d45942fe5d913aa94ddd42226118d08bc98e6882-b...36609b7574a5-00058989",
        "sum_converted": {
            "amount": 1000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "pE/Gsxb8PH9Y6fS6IiL3YqOsoz7FEUjg/4Ho54pg16ZtoRi...LZ4LoK8UqMtNCc/MrJvQ=="
}

Рис.: Пример оповещения об успешном возврате за счет средств с баланса исполнителя (сценарий 2)

{
    "payment": {
        "date": "2025-01-27T08:54:20+0000",
        "method": "card",
        "sum": {
            "amount": 0,
            "currency": "KZT"
        },
        "id": "payment_47",
        "type": "purchase",
        "status": "refunded",
        "description": ""
    },
    "customer": {
        "id": "customer_123"
    },
    "account": {
        "number": "123456******3456",
        "token": "87e2dd36d9460b8c83bbf9b28bba496de0eafa28b8993271c9e2174eb587ecc5",
        "type": "visa",
        "id": 1234567890,
        "card_holder": "John Doe",
        "expiry_month": "09",
        "expiry_year": "2027"
    },
    "project_id": 123,
    "card_country": "KZ",
    "operation": {
        "provider": {
            "id": 15681,
            "payment_id": "payment_47",
            "auth_code": "211296",
            "endpoint_id": 15681
        },
        "id": 39249010129186,
        "type": "refund",
        "status": "success",
        "date": "2025-01-27T08:54:21+0000",
        "sum_initial": {
            "amount": 7000,
            "currency": "KZT"
        },
        "created_date": "2025-01-27T08:54:07+0000",
        "request_id": "18f13a6f126c77b05af0c7a54586d793a2cbe041-435c0...c053bc752a0b-00039250",
        "sum_converted": {
            "amount": 7000,
            "currency": "KZT"
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "NBWjBbzZQFqvcHOC3sTF9AcN6kN03ehMV4qK69iP7PEEjMoXUMJL...OO5RoNycEGQk5hespQ=="
}