Create the Split
Before diving into the specifics of using the Marketplace solution, you need to understand a few terms used throughout this document and in the API. 1.
Creating a split involves the following:
- The marketplace owners are referred to as the “aggregator merchant”
- The individual providers or sub-sellers of that marketplace are referred to as “child merchants”
- The fee that the parent Merchant can optionally apply per Sub Merchant transaction is called the “aggregatorCharges”.
- The amount that will be settled to given child merchants is referred to as the “amountToBeSettled”.
To perform a basic API setup for adding a payment, adding splits (sub-payment) for payment, and releasing a sub-payment:
1. Implement Split
Implement payment splitting functionality to distribute funds among multiple parties
2. Get Aggregator/Parent Transaction Info
Retrieve information about the aggregator or parent transaction for split payments
3. Release Settlement API
Use the Release Settlement API to manage fund disbursement for split transactions
Step 1: Implement split
You must specify two decimal places for each split, but ensure the sum split amounts are equal to the transaction amount.
<Callout icon="📘" theme="info">
**Note**: You must specify two decimal places for each split, but ensure the sum of the percentage of all splits is equal to 100.
</Callout>
HTTP Method: **POST**
<GENERALAPIsEnvironment />
<Accordion title="Request parameters" icon="fa-table">
<HTMLBlock>{`
<table style="width: 100%; border-collapse: collapse;">
<thead>
<tr>
<th style="border: 1px solid #ddd; padding: 8px;"><strong>Parameter</strong></th>
<th style="border: 1px solid #ddd; padding: 8px;"><strong>Description</strong></th>
<th style="border: 1px solid #ddd; padding: 8px;"><strong>Sample Value</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>key</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p><code>string</code> This parameter must include the Merchant key that was provided by PayU.</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>vDy3i7</p>
</td>
</tr>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>api_version</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p><code>String</code> Version of the API must be 7 for Split Settlements.</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>7</p>
</td>
</tr>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>command</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p><code>string</code> The parameter must contain the name of the web service.</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>payment_split</p>
</td>
</tr>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>hash</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p><code>String</code> The hash string encryption is specified in this parameter. The format of the hash is:<br>|sha512(key|command|var1|salt)<br>Where, var1 contains the fields as described in the var1 description.</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p> </p>
</td>
</tr>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>var1</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p><code>string (JSON)</code> This parameter is in a JSON format and fields included in the JSON format are explained the <a href="#json-request-structure">JSON request structure table</a>.</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>For an example, refer the <a href="#request-structure-for-var1-to-be-included-in--payment_split-api">Request Structure</a> subsection.</p>
</td>
</tr>
</tbody>
</table>
`}</HTMLBlock>
<Accordion title="Request structure for var1 to be included in payment_split API" icon="fa-code">
```plaintext
{ "type": "absolute",
"payuId": "<PayuID of parent transaction which needs to be split>",
"splitInfo":
{
"<Child Merchant 1 key>":{
"aggregatorSubTxnId":"<unique transaction ID for this specific sub-transaction>",
"aggregatorSubAmt":"<amount to be transferred to this child merchant>",
"aggregatorCharges":"<charges associated with this entity's part of the transaction to be transferred to parent (optional)>"
},
"<Child merchant 2 key>":{
"aggregatorSubTxnId":"<unique transaction ID for this specific sub-transaction>",
"aggregatorSubAmt":"<amount to be transferred to this child merchant>"
},
"Child merchant 3 key":
{
"aggregatorSubTxnId": "<unique transaction ID for this specific sub-transaction>",
"aggregatorSubAmt": "<amount to be transferred to this child merchant>",
"aggregatorCharges": "<charges associated with this entity's part of the transaction to be transferred to parent (optional)>"
}
}
}
```
<Accordion title="JSON request structure" icon="fa-table">
The **var1** parameter is in JSON format. The fields in the JSON format are described in the following table:
<HTMLBlock>{`
<table style="width: 100%; border-collapse: collapse;">
<thead>
<tr>
<th style="border: 1px solid #ddd; padding: 8px;"><strong>Field</strong></th>
<th style="border: 1px solid #ddd; padding: 8px;"><strong>Description</strong></th>
<th style="border: 1px solid #ddd; padding: 8px;"><strong>Example</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>type</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>The type of split is specified in this field. Use <strong>absolute</strong> in this field. The absolute amount is specified for each part of the split. The absolute amount is specified in the aggregatorSubAmt field of the JSON for each child or aggregator.</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>absolute</p>
</td>
</tr>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>payuid</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>The payment identifier provided by PayU for the transaction.</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>403993715525003544</p>
</td>
</tr>
<tr>
<td style="border: 1px solid #ddd; padding: 8px;"><p>splitInfo</p>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>This parameter must include the list of aggregator sub transaction IDs and sub amounts as specified in the <a href="#request-structure-for-var1-to-be-included-in--payment_split-api">Request Structure for var1</a> subsection: </p>
<ul>
<li><strong>aggregatorSubTxnId</strong>: The aggregator sub transaction ID is specified in this field.</li>
<li><strong>aggregatorSubAmt</strong>: The aggregator sub amount is specified in this field.</li>
<li><strong>aggregatorCharges</strong>: The aggregator charges is specified in this field.<strong>Note</strong>: The aggregatorCharges field can only be used by parent merchant to get the aggregator commission.</li>
</ul>
</td>
<td style="border: 1px solid #ddd; padding: 8px;"><p>Refer to <a href="#request-structure-for-var1-to-be-included-in--payment_split-api">Request Structure for var1</a> subsection.</p>
</td>
</tr>
</tbody>
</table>
`}</HTMLBlock>
</Accordion>
</Accordion>
</Accordion>
<Accordion title="Sample request" icon="fa-code">
```curl
curl -X POST "https://info.payu.in/merchant/postservice?form=2"
-H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d
“key=A6lB8r&command=payment_splity&var1="type":"absolute","payuId":"403993715525003544","splitInfo":{"imAJ7I":{"aggregatorSubTxnId":"CHild101","aggregatorSubAmt":"50"},"qOoYIv":{"aggregatorSubTxnId":"Child202","aggregatorSubAmt":"50"}}}&hash=6692a8b560c51e8a4bb830206d3b8fac3678fb5b08443c7590047545beba66ec97257fec11775abbc339eabbaf1b1bf5e1c50d2c6bbf67e1a69ad597480d3691"
```import requests
import json
url = "https://info.payu.in/merchant/postservice?form=2"
headers = {
"accept": "application/json",
"Content-Type": "application/x-www-form-urlencoded"
}
var1_data = {
"type": "absolute",
"payuId": "403993715525003544",
"splitInfo": {
"imAJ7I": {
"aggregatorSubTxnId": "CHild101",
"aggregatorSubAmt": "50"
},
"qOoYIv": {
"aggregatorSubTxnId": "Child202",
"aggregatorSubAmt": "50"
}
}
}
data = {
"key": "A6lB8r",
"command": "payment_split",
"var1": json.dumps(var1_data),
"hash": "6692a8b560c51e8a4bb830206d3b8fac3678fb5b08443c7590047545beba66ec97257fec11775abbc339eabbaf1b1bf5e1c50d2c6bbf67e1a69ad597480d3691"
}
response = requests.post(url, headers=headers, data=data)
print("Status Code:", response.status_code)
print("Response:", response.json())import java.io.IOException;
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
public class PayUPaymentSplit {
public static void main(String[] args) throws IOException, InterruptedException {
String url = "https://info.payu.in/merchant/postservice?form=2";
String var1Json = "{\"type\":\"absolute\",\"payuId\":\"403993715525003544\",\"splitInfo\":{\"imAJ7I\":{\"aggregatorSubTxnId\":\"CHild101\",\"aggregatorSubAmt\":\"50\"},\"qOoYIv\":{\"aggregatorSubTxnId\":\"Child202\",\"aggregatorSubAmt\":\"50\"}}}";
String formData = "key=" + URLEncoder.encode("A6lB8r", StandardCharsets.UTF_8)
+ "&command=" + URLEncoder.encode("payment_split", StandardCharsets.UTF_8)
+ "&var1=" + URLEncoder.encode(var1Json, StandardCharsets.UTF_8)
+ "&hash=" + URLEncoder.encode("6692a8b560c51e8a4bb830206d3b8fac3678fb5b08443c7590047545beba66ec97257fec11775abbc339eabbaf1b1bf5e1c50d2c6bbf67e1a69ad597480d3691", StandardCharsets.UTF_8);
HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create(url))
.header("accept", "application/json")
.header("Content-Type", "application/x-www-form-urlencoded")
.POST(HttpRequest.BodyPublishers.ofString(formData))
.build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println("Status Code: " + response.statusCode());
System.out.println("Response: " + response.body());
}
}<?php
$url = "https://info.payu.in/merchant/postservice?form=2";
$var1Data = array(
'type' => 'absolute',
'payuId' => '403993715525003544',
'splitInfo' => array(
'imAJ7I' => array(
'aggregatorSubTxnId' => 'CHild101',
'aggregatorSubAmt' => '50'
),
'qOoYIv' => array(
'aggregatorSubTxnId' => 'Child202',
'aggregatorSubAmt' => '50'
)
)
);
$data = array(
'key' => 'A6lB8r',
'command' => 'payment_split',
'var1' => json_encode($var1Data),
'hash' => '6692a8b560c51e8a4bb830206d3b8fac3678fb5b08443c7590047545beba66ec97257fec11775abbc339eabbaf1b1bf5e1c50d2c6bbf67e1a69ad597480d3691'
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
'accept: application/json',
'Content-Type: application/x-www-form-urlencoded'
));
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
echo "Status Code: " . $httpCode . "\n";
echo "Response: " . $response . "\n";
$jsonResponse = json_decode($response, true);
print_r($jsonResponse);
?>#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
use HTTP::Request::Common;
use JSON;
my $url = "https://info.payu.in/merchant/postservice?form=2";
my $var1_data = {
type => 'absolute',
payuId => '403993715525003544',
splitInfo => {
imAJ7I => {
aggregatorSubTxnId => 'CHild101',
aggregatorSubAmt => '50'
},
qOoYIv => {
aggregatorSubTxnId => 'Child202',
aggregatorSubAmt => '50'
}
}
};
my %data = (
key => 'A6lB8r',
command => 'payment_split',
var1 => encode_json($var1_data),
hash => '6692a8b560c51e8a4bb830206d3b8fac3678fb5b08443c7590047545beba66ec97257fec11775abbc339eabbaf1b1bf5e1c50d2c6bbf67e1a69ad597480d3691'
);
my $ua = LWP::UserAgent->new;
$ua->timeout(30);
my $response = $ua->post($url,
Content_Type => 'application/x-www-form-urlencoded',
Content => \%data
);
if ($response->is_success) {
print "Status Code: " . $response->code . "\n";
print "Response: " . $response->decoded_content . "\n";
my $json_response = decode_json($response->decoded_content);
use Data::Dumper;
print Dumper($json_response);
} else {
print "Error: " . $response->status_line . "\n";
print "Response: " . $response->decoded_content . "\n";
}</Accordion>
<Accordion title="Sample response" icon="fa-code">
<Accordion title="Sample response for a successful split" icon="fa-code">
When split get saved & created
```plaintext
{
"status": 1,
"message": "Splits creation successful.",
"splitStatus": "success",
"splitSegments": [
{
"merchantKey": "imAJ7I",
"amount": 50,
"subvention_amount": 0,
"txnId": "CHild101",
"additional_charges": 0,
"transaction_fee": 50 },
{
"merchantKey": "qOoYIv",
"amount": 50,
"subvention_amount": 0,
"txnId": "Child202",
"additional_charges": 0,
"transaction_fee": 50 }
]
}
```
</Accordion>
<Accordion title="Sample response when split gets saved but are not yet created" icon="fa-code">
When split get saved but aren’t yet created)
```plaintext
{
"status": 2,
"message": "Splits saved, but not created yet",
"splitStatus": "PENDING"
}
```
</Accordion>
<Accordion title="Split creation is failed" icon="fa-code">
In this sample response, the **error\_code** and **error\_desc** parameters display based on the failure. For the list of error\_codes, refer to [Error Codes & Error Messages](https://devguide.payu.in/split-apis/steps-to-create-the-split/payment_split-api/#Error).
```plaintext
{
"status": 0,
"error_code": "AGG-107",
"error_desc": "Invalid split payload in payment request"
}
```
```plaintext
{
"P41sCY":{
"aggregatorSubTxnId":"0e7411799c9f0e96620c1",
"aggregatorSubAmt":"3",
"aggregatorCharges":"2"
},
"P41sCK":{
"aggregatorSubTxnId":"0e7411799c9f0e96620c2",
"aggregatorSubAmt":"5"
}
}
```
</Accordion>
</Accordion>
> 📘 Refunds for Split Transactions:
>
> You must include the var8 parameter similar to the following JSON array format with the refund details of split where **child\_merchant\_key\_x** must be substituted with the child merchant key. For more information, refer to [Refund Transaction API > Other request parameters](ref:refund_transaction_api#other-request-parameters)
>
> ```plaintext
> {
> "child_merchant_key_1":{
> "amount":100,
> "aggregatorRefundAmount":40
> },
> "child_merchant_key_2":{
> "amount":20,
> "aggregatorRefundAmount":0
> }
> }
> ```Step 2. Get Aggregator/Parent Transaction Info
The Get Aggregator Transactions API is for getting the transaction info of parent merchants in the Aggregator flow.
Environment
| Test Environment | <https://uat-onepayuonboarding.payu.in> |
| Production Environment | <https://onboarding.payu.in> |
Sample request
curl --location --request POST 'https://info.payu.in/merchant/postservice?form=2' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'key=A****J' \
--data-urlencode 'command=get_aggregator_transactions' \
--data-urlencode 'var1=2021-12-29 22:00' \
--data-urlencode 'hash=586e3379b3d9f90682329cf7efd27273aeb290936d9edf98686370bc59fdc67b06c57a5201b9bd193dc0f00fe6ecd821f60d81d5789ca2ee516db309f28025e9' \
--data-urlencode 'var2=2021-12-29 22:30' \
--data-urlencode 'var3=1' \
--data-urlencode 'var4=100' \
--data-urlencode 'var5='Sample response
{
"status": 1,
"msg": "Transaction Fetched Successfully",
"Transaction_details": [
{
"id": "412345678912384148",
"status": "captured",
"key": "A***J",
"merchantname": "Aggregator-Parent",
"txnid": "2c1c4431f3fcf5a98a66",
"base_id": null,
"firstname": "Payu-Admin",
"lastname": "",
"addedon": "2021-12-29 22:11:08",
"bank_name": "Credit Cards",
"payment_gateway": "AxisCYBER",
"phone": "1234567890",
"email": "[email protected]",
"transaction_fee": "10.00",
"amount": "10.00",
"discount": "0.00",
"additional_charges": "0.00",
"productinfo": "Product Info",
"error_code": "E000",
"bank_ref_no": "5192296867061049177385",
"ibibo_code": "CC",
"mode": "CC",
"address2": "",
"city": "",
"zipcode": "",
"pg_mid": null,
"offer_type": null,
"splitCreated": true,
"is_parent_transaction": true,
"splitInfo": [
{
"id": "412345678912384152",
"status": "captured",
"merchantId": "39032915",
"key": "P****Y",
"txnid": "2c1c4431f3fcf5a98a661",
"addedon": "2021-12-29 22:11:53",
"transaction_fee": "3.00",
"amount": "3.00",
"discount": "0.00",
"additional_charges": "0.00"
},
{
"id": "412345678912384153",
"status": "captured",
"merchantId": "39032916",
"key": "P****K",
"txnid": "2c1c4431f3fcf5a98a662",
"addedon": "2021-12-29 22:11:53",
"transaction_fee": "5.00",
"amount": "5.00",
"discount": "0.00",
"additional_charges": "0.00"
},
{
"id": "412345678912384154",
"status": "captured",
"merchantId": "39032914",
"key": "A****J",
"txnid": "2c1c4431f3fcf5a98a66",
"addedon": "2021-12-29 22:11:53",
"transaction_fee": "2.00",
"amount": "2.00",
"discount": "0.00",
"additional_charges": "0.00"
}
]
},
{
"id": "412345678912384155",
"status": "bounced",
"key": "A****J",
"merchantname": "Aggregator-Parent",
"txnid": "02b3e5b6bc97dc3a3418",
"base_id": null,
"firstname": "Payu-Admin",
"lastname": "",
"addedon": "2021-12-29 22:13:08",
"bank_name": "Credit Cards",
"payment_gateway": "AxisCYBER",
"phone": "1234567890",
"email": "[email protected]",
"transaction_fee": "11.00",
"amount": "11.00",
"discount": "0.00",
"additional_charges": "0.00",
"productinfo": "Product Info",
"error_code": "E501",
"bank_ref_no": null,
"ibibo_code": "CC",
"mode": "CC",
"address2": "",
"city": "",
"zipcode": "",
"pg_mid": null,
"offer_type": null,
"splitCreated": false,
"is_parent_transaction": true,
"splitInfo": null
},
{
"id": "412345678912384156",
"status": "captured",
"key": "A****J",
"merchantname": "Aggregator-Parent",
"txnid": "61c21439bbd4609e258b",
"base_id": null,
"firstname": "Payu-Admin",
"lastname": "",
"addedon": "2021-12-29 22:14:23",
"bank_name": "Credit Cards",
"payment_gateway": "AxisCYBER",
"phone": "1234567890",
"email": "[email protected]",
"transaction_fee": "11.00",
"amount": "11.00",
"discount": "0.00",
"additional_charges": "0.00",
"productinfo": "Product Info",
"error_code": "E000",
"bank_ref_no": "6333825950714879001604",
"ibibo_code": "CC",
"mode": "CC",
"address2": "",
"city": "",
"zipcode": "",
"pg_mid": null,
"offer_type": null,
"splitCreated": true,
"is_parent_transaction": true,
"splitInfo": [
{
"id": "412345678912384160",
"status": "captured",
"merchantId": "39032915",
"key": "P****Y",
"txnid": "61c21439bbd4609e258b1",
"addedon": "2021-12-29 22:14:40",
"transaction_fee": "3.00",
"amount": "3.00",
"discount": "0.00",
"additional_charges": "0.00"
},
{
"id": "412345678912384161",
"status": "captured",
"merchantId": "39032916",
"key": "P****K",
"txnid": "61c21439bbd4609e258b2",
"addedon": "2021-12-29 22:14:40",
"transaction_fee": "6.00",
"amount": "6.00",
"discount": "0.00",
"additional_charges": "0.00"
},
{
"id": "412345678912384162",
"status": "captured",
"merchantId": "39032914",
"key": "A****J",
"txnid": "61c21439bbd4609e258b",
"addedon": "2021-12-29 22:14:40",
"transaction_fee": "2.00",
"amount": "2.00",
"discount": "0.00",
"additional_charges": "0.00"
}
]
}
]
}Step 3. Release Settlement API
The Release Settlement API is used to flag the sub-payment you want to settle; after adding splits for a particular payment, the money will not be settled directly into the child merchants account unless you call a release event corresponding to the individual suborder you want to settle.
The Release Settlement API can be used to release the settlement of all the blocked child transactions in the aggregator workflow.
HTTP Method: POST
Environments
| Test Environment | https://test.payu.in/merchant/postservice.php?form=2 |
| Production Environment | https://info.payu.in/merchant/postservice.php?form=2 |
Sample request
curl -X POST "https://test.payu.in/merchant/postservice?form=2"
-H "accept: application/json" -H "Content-Type: application/x-www-form-urlencoded" -d
"key=A****r&command=release_settlement&var1=8000123&var2=8000123&hash=6692a8b560c51e8a4bb830206d3b8fac3678fb5b0844"Sample Response
Success Scenario
-
Successful Transaction
Sample Success Response for Release Settlement
{"status":1,"msg":"Release request is accepted"}
Failure Scenarios
-
Failure Response when PayU ID is empty
Failure Response when PayUID is empty
{"status":0,"msg":"payuId is empty"}- Failure response when child merchant ID is empty
Failure response when child merchant ID is empty
{"status":0,"msg":"Mid passed is empty"}- Failure Response when child merchant ID and PayU ID do not match
Failure Response when child merchant ID and PayU ID do not match
{"status":0,"msg":"Invalid childMid and payuId"}- Failure response when attempting to release an already released sub-payment
Failure response when attempt to release an already released sub- payment
{"status":0,"msg":"Release request is already accepted"}
Refunds for Split Transactions:You must include the var8 parameter similar to the following JSON array format with the refund details of split where child_merchant_key_x must be substituted with the child merchant key. For more information, refer to Refund Transaction API > Other request parameters
{ "child_merchant_key_1":{ "amount":100, "aggregatorRefundAmount":40 }, "child_merchant_key_2":{ "amount":20, "aggregatorRefundAmount":0 } }