Split payment

General information

When processing payments, you may need to split payment amount and allocate it to multiple balances. For example, this option can be useful for an aggregator or an online platform that works with several partner companies—to include information about the amount intended for the aggregator itself, as well as the amount for its partner company within the original payment, leaving the rest of the payment for the subcontractor (courier, tutor, taxi driver, etc.). Split payment allows you to automate the process of cash distribution between all the parties and makes it easier to exchange financial documents: after the customer pays for the aggregator's services, the payment is split between all the participants. To aid in processing such payments, the payment platform supports splitting payment amount between several accounts. This section describes how to process split payments.

Split payment is supported for one-time purchases processed in one or two steps with direct use of payment cards. Contact your JetPay key account manager for information on the methods for which split payment is supported.

Request format

Depending on the operation, you sent your request to one of the following endpoints.

Table 1. Endpoints for purchase request with split payment
Endpoint Description
/v2/payment/card/sale Request for withdrawal of funds from customer account in a one-step purchase
/v2/payment/card/auth Request for holding of funds on customer account, as the first step in a two-step purchase
/v2/payment/card/cancel Request for cancellation of holding of funds on customer account in a two-step purchase
/v2/payment/card/capture Request for withdrawal of held funds from customer account in a two-step purchase

To have the payment amount split and allocated to multiple balances, you need add to your ordinary purchase request the rewards and account objects along with their parameters.

Table 2. Additional parameters for purchase request with split payment

strictly required—the parameter must be in the initial request.
Object Parameter Description

rewards
array
strictly required

reward_amount
integer
strictly required

 Partner company income; in other words, it's the amount debited to the partner company balance. The value must be greater than or equal to zero.

Example: 20000

income_amount
integer
strictly required

 Aggregator income—the amount debited to the aggregator balance. The value must be greater than or equal to zero.

Example: 10000

account
object
strictly required

number
string
strictly required

 Subcontractor's phone number to which their account is linked. The payment amount will be debited to this account less the aggregator's and the partner company's income.

Example: +71234567890

The following are examples of requests for a one-step and two-step purchase. Note that the highlighted object contains information about splitting payment amount into separate balances.

Figure: Example of a one-step purchase request with split payment

{
    "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": {      // object with split payment information
        "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"
    }
}

Figure: Example of a two-step purchase request with split payment

{
    "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": {    // object with split payment information 
    "reward_amount": 20000,
    "income_amount": 10000
  },
    "payment": {
        "amount": 100000,
        "currency": "KZT"
    },
    "account": {
        "number": "+71234567890"
    }
}

Splitting payment between accounts is processed as follows. When requested as part of a one-step purchase or as the second step of a two-step purchase, the information on the aggregator's income and partner company's income are specified in the request along with the final amount of the purchase, the rest of the amount is credited to the subcontractor's account. The process follows the formula:

Subcontractor payout = Payment amount − Partner company income − Aggregator income
Let's say the payment amount is 1 000,00 KZT. Then:
  • Partner company income will be 200,00 KZT
  • Aggregator income will be 100,00 KZT
  • Subcontractor payout will be 700,00 KZT (1000 − 100− 200).

Information about each transaction is sent to the aggregator's system in callbacks, the structure of which is described below.

Refund

As part of a split payment purchase, the aggregator can initiate a refund. There are two scenarios for the refund depending on the balance from where the funds are withdrawn and the part of the initial payment that needs to be refunded. If the entire amount needs to be refunded, then you combine both scenarios. The scenarios are described in the next section.

Refund Scenario 1

In Scenario 1, the refund to the customer is made from the aggregator's balance. In this case, the standard refund process is performed, described in more detail in Purchase refund. This scenario is used to refund the aggregator's or partner's commission to the customer, as well as the subcontractor's income—in case it is not possible to withdraw it from the subcontractor's balance.

Use the information below to create and submit the request for refund funds from the aggregator's balance (Scenario 1).

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/card/refund
Full API endpoint specification /v2/payment/card/refund
Table 3. Basic parameters for a refund request to withdraw funds from the aggregator's balance (Scenario 1).

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from JetPay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

id
string
strictly required

 Unique ID of the customer within your project.

Example: customer_123

ip_address
string
strictly required

 IP address of the customer's device.

Example: 198.51.100.47

first_name
string
strictly required

 Customer's first name.

Example: John

last_name
string
strictly required

 Customer's last name.

Example: Doe

email
string
strictly required

 Customer's email.

Example: johndoe@example.com

payment
object
strictly required

amount
integer
strictly required

 Integer payout amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. The payout amount must be strictly integer, otherwise the payment will be declined. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 700.00 KZT is sent as 70000.

currency
string
strictly required

 Code of the payout currency in the ISO-4217 alpha-3 format.

Example: KZT

description
string
strictly required

 Comment or refund description.

Example: Refund operation
You can also add any other optional parameters to the payout request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here's an example of data from a request to a refund from the aggregator's balance (Scenario 1):

Figure: Example of a refund request to withdraw funds from the aggregator's balance (Scenario 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"
    }
}

Refund Scenario 2

In Scenario 2, the refund is made from the subcontractor's balance. In this case, the full amount of subcontractor's payout is withdrawn from the subcontractor's balance. Refund might not be possible due to low subcontractor's balance or because the hold time for the transferred funds in the subcontractor's wallet has expired. If that is the case, the aggregator can use Scenario 1 and the amount equal to the subcontractor's payout will be withdrawn from the aggregator's balance. The hold time for the subcontractor's wallet is limited but you can have it changed by contacting your JetPay key account manager.

Use the information below to create and sent the request for a refund from the subcontractor's balance (Scenario 2).

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/card/payout_refund
Table 4. Basic parameters for a refund request to withdraw funds from the subcontractor's balance (Scenario 2).

strictly required—the parameter must be in the initial request.
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

 Project ID you obtained from JetPay when integrating.

Example: 123

payment_id
string
strictly required

 Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

id
string
strictly required

 Unique ID of the customer within your project.

Example: customer_123

ip_address
string
strictly required

 IP address of the customer's device.

Example: 198.51.100.47

first_name
string
strictly required

 Customer's first name.

Example: John

last_name
string
strictly required

 Customer's last name.

Example: Doe

email
string
strictly required

 Customer's email.

Example: johndoe@example.com

payment
object
strictly required

description
string
strictly required

 Comment or refund description.

Example: Refund operation
You can also add any other optional parameters to the payout request, if necessary. For the list of all the parameters available in Gate, see API Reference.

Here's an example of data from a refund request to withdraw funds from the subcontractor's balance (Scenario 2):

Figure: Example of a refund request to withdraw funds from the subcontractor's balance (Scenario 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"
    }
}

Callbacks

The standard format for callbacks is used to deliver the results of split payment. For more information, see Callbacks in Gate.

Figure: Callback example for a successful one-step purchase with split payment

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

Figure: Callback example for a one-step purchase with split payment canceled due to a lack of funds

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

Figure: Callback example for a successful two-step purchase with split payment

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

Figure: Callback example for a two-step purchase with split payment canceled due to a lack of funds

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

Figure: Callback example for a successful refund by withdrawing funds from the aggregator's balance (Scenario 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=="
}

Figure: Callback example for a successful refund by withdrawing funds from the subcontractor's balance (Scenario 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=="
}