API command: _payment
This section describes the _payment API contract for getting split info of the parent transaction in the Aggregator flow.
Environment
| Test Environment | <https://test.payu.in/_payment> |
| Production Environment | <https://secure.payu.in/_payment> |
New parameter (splitRequest) merchant needs to post in the payment request.
Notes:
- Total aggregatorSubAmt must be equal to transaction amount posted by merchant.
- Merchant key posted in split request must belong to parent key.
- Transactions are not allowed on child merchant accounts or child merchant keys.
- You must specify two decimal places for each split, but ensure the sum of percentage of all splits is equal to 100 or sum of split amount is equal to transaction amount.
splitRequest parameter to be included with _payment API
The splitRequest parameter must be included in the _payment API along with the regular parameters. The following are the request parameters used for split settlements:
| Parameter | Description |
|---|---|
<glossary:key> |
|
<glossary:txnid> |
|
amount |
|
productinfo |
|
firstname |
|
email |
|
phone |
|
pg |
|
bankcode |
|
ccnum |
|
ccname |
|
ccvv |
|
ccexpmon |
|
ccexpyr |
|
furl |
|
surl |
|
splitRequest |
|
hash |
|
address1 |
|
address2 |
|
city |
|
state |
|
country |
|
zipcode |
|
udf1 |
|
udf2 |
|
udf3 |
|
udf4 |
|
udf5 |
|
JSON Request structure of splitRequest parameter
The sample JSON structure for the splitRequest field:
Notes:
- For the absolute type split, you must ensure that the sum of the amount of all splits is equal to the parent transaction amount.
- For the percentage type split, you must ensure that the sum of the percentage of all splits is equal to 100. You can use any number of decimal places for each split, but ensure the sum of the percentage of all splits is equal to 100.
{
"type":"<Type of split, absolute or 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>"
}
}
}The following fields are included in the splitRequest parameter in a JSON format to specify the split details. The fields in the JSON format are described in the following table:
| Field | Description | Example |
|---|---|---|
type |
|
absolute |
splitInfo |
JSON` This parameter must include the list of aggregator sub transaction IDs and sub amounts as follows:
|
Hashing request
Added as extra parameter in the calculation of hash in case of providing Split Request at time of payment. This parameter will be at the end of the hash pattern. and required while sending Split Request at time of payment.
You need to generate a string using certain parameters and apply the SHA-512 algorithm to this string. For more information on hashing, refer to Generate Hash.
Note:
Ensure that you use pipe (|) character between these parameters as mentioned in the following code block.
The parameter order is in the following code block:
sha512(key|txnid|amount|productinfo|firstname|email|udf1|udf2|udf3|udf4|udf5||||||SALT|splitRequest)Where, splitRequest will be at the end of the hash pattern string.
Example:
hash('sha512', 'Ax4j7J|payment-txnid-1|10|Product Info|Payu-Admin|[email protected]|||||||||||t5atu4TyCvrJDPxAYrmfJfzd90kbXMfL|{"type":"absolute","splitInfo":{"P41sCY":{"aggregatorSubTxnId":"0e7411799c9f0e96620c11","aggregatorSubAmt":"3","aggregatorCharges":"2"},"P41sCK":{"aggregatorSubTxnId":"0e7411799c9f0e96620c22","aggregatorSubAmt":"5"}}}'));Hash validation logic for payment response (Reverse hashing)
Use the following algorithm for reverse hashing the response from PayU:
sha512(SALT|status|splitInfo||||||udf5|udf4|udf3|udf2|udf1|email|firstname|productinfo|amount|txnid|key)Example scenarios
If a Parent Merchant has two child merchants: Merchant A (Key: P****Y) and Merchant B (Key: P***K). If a customer buys two products from each of the merchants and involves the following:
- Merchant A (Product Cost: 60)
- Merchant B (Product Cost: 40)
- Customer paid Cost: 100 on PayU Gateway.
The following cases can occur:
- **Case 1:**Merchant wants the commission amount from Merchant A (Commission amount: 15) and B (Commission Amount: 10).
So In the final, Merchant wants to settle Amount: 45 to Merchant A and Amount: 30 to Merchant B and Amount: 25 to self account (parent part).
The split JSON Structure for the above scenarios is similar to the following:
{
"type":"absolute",
"splitInfo":{
"P****Y":{
"aggregatorSubTxnId":"9a70ea0155268101001ba",
"aggregatorSubAmt":"45",
"aggregatorCharges":"15"
},
"P***K":{
"aggregatorSubTxnId":"9a70ea0155268101001bb",
"aggregatorSubAmt":"30",
"aggregatorCharges":"10"
}
}
}- Case 2: Merchant wants the commission amount from Merchant A (Commission amount: 15) and Nothing from Merchant B (Commission Amount: 0).
So, the merchant wants to settle an amount: 45 to Merchant A and amount: 40 to Merchant B and an amount: 15 to self account (parent part).
The split JSON Structure for the above scenario is similar to the following:
{
"type":"absolute",
"splitInfo":{
"P****Y":{
"aggregatorSubTxnId":"9a70ea0155268101001ba",
"aggregatorSubAmt":"45",
"aggregatorCharges":"15"
},
"P***K":{
"aggregatorSubTxnId":"9a70ea0155268101001bb",
"aggregatorSubAmt":"40"
}
}
}- Case 3: Merchant does not want any commission amount from Child Merchant A (Commission amount: 0) and B (Commission Amount: 0).
So In the final, Merchant wants to settle Amount: 60 to child merchant A and Amount: 40 to Child Merchant B and Amount: 0 to Self account (Parent Part).
The split JSON Structure for the above scenario is similar to the following:
{
"type":"absolute",
"splitInfo":{
"P****Y":{
"aggregatorSubTxnId":"9a70ea0155268101001ba",
"aggregatorSubAmt":"60"
},
"P***K":{
"aggregatorSubTxnId":"9a70ea0155268101001bb",
"aggregatorSubAmt":"40"
}
}
}Split Transaction with Only Single Child
You may choose to settle 100% for a single child. In such cases, you can pass zero (0) in the child’s key and 100% amount for others. For example, in the following JSON structure:
- The amount is Rs.10 for aggregatorSubAmt.
- The amount of Rs.0 (or no amount settlement) for aggregatorCharges
{
"childKey1":{
"aggregatorSubTxnId":"txnIdForChild",
"aggregatorSubAmt":"10",
"aggregatorCharges":"0"
}
}Passing parent merchant key in the splitInfo parameter
You can pass the parent merchant key along and the child merchant key with the corresponding aggregatorSubTxnId, aggregatorSubAmt, and aggregatorCharges (can be used by only for parent merchants to collect charges) parameters in a JSON format.
Sample Request
A sample value in JSON format for the splitInfo parameter:
{
"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 } }