1. Home
  2. Docs
  3. Developers Guide
  4. Private: Payment Products
  5. Aggregator

Aggregator

Aggregator model is based around split settlements where a merchant has a Marketplace business model and intends to settle all parties involved in a given transaction at a single go. This note describes the understating of aggregator model and the steps for technical integration process between your website and PayU Marketplace APIs.

Our APIs are organized around REST, each API is a server-to-server call from your server to our server and it is designed to have predictable resource-oriented URLs and we use HTTP response codes to indicate API errors (Detailed explanation of Error code in section: HTTP Codes). We support cross-platform resource sharing to allow you to interact securely with our API from a client-side web application. A JSON object will be returned in all responses from the API.

Few benefits of using this model are listed as below:

  • Customer makes a single payment to aggregator
  • Separate accounts for aggregator’s sellers will be created to which money will be settled.
  • Settlement of a single transaction can be done across multiple sellers
  • Aggregator’s commission is settled to the Aggregator’s account.
  • PayUMoney takes care of Nodal Registrations, Settlements and Regulatory Requirements of sub sellers.

Note:-Convenience fee model will not work with aggregator model

Work flow

The backend working model of this payment flow is explained as below:

  • After a successful payment – Marketplace provides merchant ID & order breakup info to PayUMoney.
  • PayUMoney will create sub-transactions based on these amounts for the sellers.
  • Every transaction/order can be split into any number of sub-transactions (depending on the sellers involved).
  • These sub-transactions are settled to the corresponding seller’s account.
  • Marketplace’s commission is settled to the marketplace’s account after deducting PAYUs TDR

Flow chart

Steps to create the splits

Before diving in to the specifics of using Marketplace solution, let’s define a few terms that will be used throughout this document and in the API.

  1. The marketplace owners are referred to as the “aggregator merchant
  2. The individual providers or sub-sellers of that marketplace are referred to as “child Merchants
  3. The fee that the parent Merchant can optionally apply per Sub Merchant transaction is called the “aggregatorCharges“.
  4. The amount that will be settled to a given child Merchants is referred to as “amountToBeSettled“.

Authentication/Authorization

Our API is secured by an authentication mechanism. In order to make a call to an API you first need to authenticate to the API by providing your API key in the request header. It’s a unique key for every marketplace account and will be generated on demand when your test account is created. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

To use your API key, you need set request header of type “Authorization” send this key in each request.

We’ll now go through a basic API setup for Adding a payment, adding splits (subpayment) for a payment and releasing a sub-payment:-

Step1:- Do a transaction in PayU(using the parent key & salt)

Step2:- Implement the Addpaymentsplit API at your end using the transaction id generated.

Step3:- Implement the release payment API.

Please use below credentials for the parent account (all the details are for test mode):

Parent Merchant details:

Username: TestAggregatorRefund@payup.com

Password: Payu@123

Key: tXjTgO

Salt: QYcSzlbk

MID: 393429

Authorization Header:  QmetgiU8HibANxwgv/8GwF02GElmNG5gRoRM/sVAyWI=

Child merchant1: 

Username: TestAggregatorChild1@payup.com

Password: Payu@123

Merchant ID: 393437

Child merchant2: 

Username: TestAggregatorChild2@payup.com

Password: Payu@123

Merchant ID: 393441

Please refer the miscellaneous section for test card details.

Add Payment Splits API

This web-service is used to push splits breakup (suborder level) for a given Order/Parent transaction. This API has a provision to add suborder details for example: child merchant ID, child merchant’s “amounttobesettled”, aggregator commission, suborder ID. An order can have n no. of splits depending upon the no. of sub-orders in a given order.

HTTP METHOD: POST

CONTENT-TYPE: APPLICATION/JSON

REQUIRES AUTHENTICATION: YES

URLs

API Endpoint (Sandbox): https://test.payumoney.com/payment/payment/addPaymentSplit

API Endpoint (Production): https://www.payumoney.com/payment/payment/addPaymentSplit

Requested Parameters:-

Example:-

https://test.payumoney.com/payment/payment/addPaymentSplit?merchantKey=jrjx0g&merchantTransactionId=testjaprefundap12345678&totalAmount=5100&totalDiscount=0&jsonSplits=[{"merchantId":"393437","splitAmount":"2550","aggregatorSubTransactionId":"dsadad123","aggregatorCharges":"50","aggregatorDiscount":"0","sellerDiscount":"0","CODAmount":"3000","CODMode":"1","splitDetails":"SOME_SPLIT","amountToBeSettled":"4000"}]

Request parameters description :

Parameter Type Description
merchantKey int Unique merchant key Provided by PayU
merchantTransactionId String Merchant has to generate a unique reference ID for every transaction request.
totalAmount int Total transaction amount
merchantId String Unique merchant ID need to be posted here
splitAmount int Amount to be split is posted here
aggregatorSubTransactionId int  
aggregatorCharges String  
aggregatorDiscount String  
sellerDiscount String  
CODAmount String  
CODMode String  
splitDetails String  
amountToBeSettled String  

Response:-

Parameter Type Description
status int Status will be 0 if API call is a success  Status will be -1 in case of failure you’ll get system handled failure reasons in this case
message String Message string for both success and failure cases  (PFB map for error/success messages)
result String Case Success => We’ll receive a json object containing parent payment ID and an array of all the child payment IDs corresponding to splits pushed.   Result Object { “paymentId”: 574341,”splitIdMap”: { “suborderid5”: 574342 “suborderid6”: 574343 } }   Where: is the parent paymentIDis the subpayment Id corresponding to suborderid5 574343 is the subpayment Id corresponding to suborderid6   Case Failure =>NULL

Messages with description:-

  message   Description
Splits added   Splits added successfully.
Payment no t initiated MerchantID is null
Invalid mer chant key merchantKey not found in payumoney or is Null
Parent tran found saction not merchanttransactionID is invalid or not present in our system
Payment sta success tus is not Payment status is not success in PayuMoney wait for 40 mins till it gets success
Splits empt y   JsonSplit passed is null
Split alread y added In case if Splits already added ie: splits API is already called

Release Payment API

This web-service will be used to flag the sub-payment you want to settle, So after adding splits for a particular payment the money will not be settled directly into child-merchant’s account unless you call a release event corresponding to individual suborder you want to settle.

Use Case: In most of the marketplace models owners waits for the delivery/dispatch to happen first from the sub-seller’s end and only after the successful dispatch the owner will release the funds into the sub-seller’s bank account. This API gives them the flexibility to do so. 

Note: Release event will be called on sub-order level, so to call this web-service you need to pass sub-paymentID and merchantId.

HTTP METHOD : POST

CONTENT-TYPE: APPLICATION/JSON REQUIRES AUTHENTICATION: YES

URLs

API Endpoint (Sandbox): https://test.payumoney.com/payment/merchant/releasePayment

API Endpoint (Production): https://www.payumoney.com/payment/merchant/releasePayment

Requested Parameters:-

Parameter Required Type Description
paymentId Yes String Payu money generated subPaymentId for the split
merchantId Yes String Payumoney merchant id of the seller for which the split was added

Example:-

https://test.payumoney.com/payment/merchant/releasePayment?paymentId=383193 &merchantId=370159  

Response:-

Parameter Type Description
Status int Status will be 0 if API call is a success  Status will be -1 in case of failure you’ll get system handled failure reasons in this case
Message String Message string for both success and failure cases  (PFB map for error/success messages)
Result String Case Success => Payment ID of split  Case Failure => NULL
Message Description
Successful Response { “status”: 0, “message”: “Release payment successful”, “result”: 574342, “errorCode”: null }  
Failure Response in case when MerchantId passed is not linked to that payment { “status”: -1, “message”: “Merchant id’s do not match”, “result”: null, “errorCode”: null }  
Failure Response in case when Attempt to release an already released subpayment { “status”: -1, “message”: “Payment already released”, “result”: 574342, “errorCode”: null }
Message Description
Release payment successful Payment released successfully
Merchant id’s do not match MerchantId passed is not linked to that payment or vice-versa
Payment already released Attempt to release an already released sub-payment
Payment not found When payment ID passed is invalid

Message with description:-


Refund API
This web-service is used to refund or partially-refund a given sub-order, only aggregator merchant is authorized to call refund API for a given sub-order.

Note: Please use this API only or your PayUMoney aggregator dashboard to initiate the refunds in aggregator flow.

HTTP METHOD: POST

CONTENT-TYPE: APPLICATION/JSON

REQUIRES AUTHENTICATION: YES

URLs

API Endpoint (Sandbox): https://test.payumoney.com/payment/refund/refundPayment

API Endpoint (Production): https://www.payumoney.com/payment/refund/refundPayment

Request Parameters:-

Parameter Required Type Description
paymentId Yes Integer PayumoneyPaymentId of the sub-order that is to be refunded
refundAmount Yes String Amount to be refunded
refundType Yes String Always set to 1
merchantId Yes Integer merchant ID of the sub-merchant to whom this sub-order belongs
merchantAmount Yes String In case of partial refund:  Amount that is to be debited from the submerchant’s amount to be settled
aggregatorAmount Yes String In case of partial refund: Amount that is to be debited from the aggregator commision

Example:-

https://test.payumoney.com/payment/refund/refundPayment?paymentId=123456 &refundAmount=56&refundType=1&merchantId=765433&merchantAmount=6&aggregatorAm ount=50

Response:-

Parameter Type Description
Status int Status will be 0 if API call is a success Status will be -1 in case of failure you’ll get system handled failure reasons in this case
Message String Message string for both success and failure cases (system handled failure reasons)
Result String Case Success =>RefundId Case Failure => NULL

Messages with description:-

Message Description
Refund Initiated Refund succesfully Initiated
PaymentId is not valid for this merchant When PaymentID is not linked with the merchantID passed
Payment is not allowed for refund as status is: refundinprogress Refund on this sub order is already initiated