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.
Note: You must specify two decimal places for each split, but ensure the sum of the percentage of all splits is equal to 100.
HTTP Method: POST
Environment
| Test Environment | <https://test.payu.in/merchant/postservice.php?form=2> |
| Production Environment | <https://info.payu.in/merchant/postservice.php?form=2> |
Request parameters
| Parameter | Description | Sample Value |
|---|---|---|
key |
|
vDy3i7 |
command |
|
payment_split |
hash |
|
|
var1 |
|
For an example, refer the Request Structure subsection. |
Request structure for var1 to be included in payment_split API
{ "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)>"
}
}
}JSON request structure
The var1 parameter is in JSON format. The fields in the JSON format are described in the following table:
| Field | Description | Example |
|---|---|---|
type |
The type of split is specified in this field. Use absolute 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. |
absolute |
payuid |
The payment identifier provided by PayU for the transaction. |
403993715525003544 |
splitInfo |
This parameter must include the list of aggregator sub transaction IDs and sub amounts as specified in the Request Structure for var1 subsection:
|
Refer to Request Structure for var1 subsection. |
Sample request
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"Sample response
Sample response for a successful split
When split get saved & created
{
"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 }
]
}Sample response when split gets saved but are not yet created
When split get saved but aren’t yet created)
{
"status": 2,
"message": "Splits saved, but not created yet",
"splitStatus": "PENDING"
}Split creation is failed
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.
{
"status": 0,
"error_code": "AGG-107",
"error_desc": "Invalid split payload in payment request"
}{
"P41sCY":{
"aggregatorSubTxnId":"0e7411799c9f0e96620c1",
"aggregatorSubAmt":"3",
"aggregatorCharges":"2"
},
"P41sCK":{
"aggregatorSubTxnId":"0e7411799c9f0e96620c2",
"aggregatorSubAmt":"5"
}
}
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 } }
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
Environment
| 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 } }
Updated 1 day ago