Documentation

Overview

This document describes the steps for technical integration process between your website and PayUMoney Marketplace APIs for enabling split settlements between you and your sub-sellers. PayuMoney API is organized around REST, each API is a server-to-server call from your server to PayuMoney's server. Our API 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.

Getting Started

This section will help you get everything set up so you can start your integration with PayuMoney aggregator platform. If you aren't a PayuMoney user, sign up for an account; you will need an account to use the API.

There are two integration guides to help you get started:

Aggregator integration with
PayuMoney as a Payment Gateway

Step by step technical integration process between your website and PayUMoney.

Learn More

Aggregator integration with
PayU Enterprise as a Payment Gateway

Aggregator APIs integration for PayU Enterprise users.

Learn More

Before diving in to the specifics of using PayuMoney's Marketplace solution, let's define a few terms that will be used throughout this guide 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"

We'll now go through a basic API setup for Adding a payment, adding splits (sub-payment) for a payment and releasing a sub-payment but before that we need to get the basics of authentication procedures, standard error codes and their meanings etc.

Authentication

PayuMoney 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. Below is the implemantation of authorization header in 3 languages C#.NET, ASP.NET, PHP.

Code Examples expandCollapse

  • C#.NET
  • ASP.NET
  • PHP
copy C#.NET 

string URI ="https://test.payumoney.com/payment/payment/chkMerchantTxnStatus?";
string myParameters ="merchantKey=0yW16s&merchantTransactionIds=TSN3000056599_
2062014173214";using (WebClient wc = new WebClient())
   {
      wc.Headers[HttpRequestHeader.ContentType] = "application/x-www-form-urlencoded";                
      wc.Headers.Add("Authorization", "E6LgK9vJOwwDFdfu7wUBxiulpw/KDkZNhKHL5Iq+D6I=";
      HtmlResult += wc.UploadString(URI, myParameters);
      var jss = new JavaScriptSerializer();
      var dict = jss.Deserialize<Dictionary<dynamic, dynamic>>(HtmlResult);
      Console.WriteLine(dict["message"]);
   }
copy ASP.NET 

Dim URI As String = "https://test.payumoney.com/payment/payment/chkMerchantTxnStatus?"
Dim merchantKey As String = TextBox1.Text
Dim txnId As String = TextBox2.Text
Dim authorizationHeader As String = TextBox3.Text
Dim myParameters As String = "merchantKey=" & merchantKey  
& "&merchantTransactionIds="   & txnId
' string myParameters = "merchantKey=0yW16s&merchantTransactionIds=TSN3000056599_
2062014173214";
Using wc As New WebClient()
wc.Headers(HttpRequestHeader.ContentType) = "application/x-www-form-urlencoded"
wc.Headers.Add("Authorization", authorizationHeader)
Dim HtmlResult As String = wc.UploadString(URI, myParameters)
Label1.Text = HtmlResult
End Using
copy Php 

function curlCall($postUrl, $toSend)
{
  $ch = curl_init();
  curl_setopt($ch, CURLOPT_POST, 1);
  curl_setopt($ch, CURLOPT_POSTFIELDS, $toSend);
  curl_setopt($ch, CURLOPT_URL, $postUrl);
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
  curl_setopt($ch, CURLOPT_HTTPHEADER, array('authorization: 
  tGmNEyYrMX9ZF7C7xpBJBjQ+6Xx5BH8n8t/DVvl1LbI='));
  curl_setopt($ch, CURLOPT_FOLLOWLOCATION, 1);
  curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
  curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
  $out = curl_exec($ch);
}

HTTP Response Code

We use conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing etc.), and codes in the 5xx range indicate an error with PayuMoney's servers.

Below is a list of PayuMoney's status codes that you may receive via the API

Error message
Description
200 OK

Everything worked as expected.
400 Bad Request

Often missing a required parameter.
401 Unauthorized

No valid API key provided.
403 Forbidden

The current does not have access to this method
402 Request Failed

Parameters were valid but request failed.
404 Not Found

The requested item doesn't exist.
500, 502, 503, 504 Server errors

something went wrong on PayuMoney's end.

PayUMoney as Payment Gateway

PayUMoney offers electronic payment service to your website through its various partnerships with banks and payment instrument companies. Through PayUMoney, your clients would be able to make electronic payments through credit card, debit card and online net banking account

PayUMoney also offers an online interface where the merchant can view transaction details, settlement reports, analytic reports etc. This online interface can be accessed through https://www.payumoney.com by using the username and password provided to you.

Download sample code and API help doc
  • ASP.Net
  • VB.Net
  • PHP

API Content

API / Add Payment

This web-service is used to push pure COD and pure GV transactions into payumoney system. Unlike Prepaid transactions which directly syns. Into our system from Payu system, COD/GV transactions are generally orders placed for offline payments which needs to be settled to the child- merchant so we need to push these payments into payumoney explicitly using an API.

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test APIexpandCollapse

copy 

https://test.payumoney.com/payment/payment/createPayment?sourceReferenceId=
testjaprefunda646475767&merchantKey=jrjx0g&merchantTransactionId=testjaprefunda
456546p464646&totalAmount=5000&customerName=CUSTOMER2&customerEmail=ABC@XYZ.COM
&customerPhone=0123456789&productInfo=SOMEPRODUCT&paymentDate=31-07-2014
&paymentMode=COD&paymentStatus=Success

Request Parameters expandCollapse

Parameter
Required
Type
Description
merchantTransactionId

Yes

String

Unique orderId to be pushed corresponding to COD, GV type transactions
merchantKey

Yes

String

Merchant's Payu Key
sourceReferenceId

Yes

String

Same as merchant transaction id
totalAmount

Yes

String

Total amount of transaction/Order
customerName

Yes

String

Buyer Name for this Order
customerEmail

Yes

String

Buyer Email for this Order
customerPhone

Yes

String

Buyer Phone No. for this Order
productInfo

Yes

String

Product info. (string)
paymentDate

Yes

String

Date on which the order is made
paymentMode

Yes

String

For full Discount type orders use payment mode as "GV" For full COD type orders use payment mode as "COD"
paymentStatus

Yes

String

Always pass "Success"

Response expandCollapse

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 => payumoney Payment Id of the order pushed
Case Success => Failure => NULL
errorCode

String

Always Null

Sample Response Format expandCollapse

Message
Description
Successful Response
 
{
   "status": 0,
    "message": "Payment successfully initiated",
    "result": 571882,
    "errorCode": null
}
Failure Response in case when totalAmount passed is equal to 0
 
{
   "status": -1,
    "message": "Amount Should Be Greater Than Zero",
    "result": null,
    "errorCode": null
}
Failure Response in case when merchant transaction Id passed was already added before 
{
   "status": -1,
    "message": "Payment already added with the merchant transaction 
    id:testhk76767887",
    "result": 571882,
    "errorCode": null
}

API / Add Payment Splits

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: childmerchant ID, childmerchant's amounttobesettled, aggregatorcommission, suborderID.

An order can have n no. of splits depending upon the no. of sub-orders in a given order, you can also send in COD and GV component value corresponding to the sub-order (for more details on cases please refer to section:
Add Payment splits Cases)

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test API expandCollapse

copy 

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

Request Parameters expandCollapse

Parameter
Required
Type
Description
merchantKey

Yes

String

Merchant's Payu Key
merchantTransactionId

Yes

String

Unique orderId posted by aggregator to payu for every transaction made.

totalAmount

Yes

String

Total order Amount
(Sum of all the splits)
totalDiscount

Yes

String

(Seller Discount + Aggregator Discount)
jsonSplits

Yes

JSON array with multiple fields
A

aggregatorSubTransactionId
(Unique sub order ID)
B

merchantId
(Payumoney merchant id)
C

splitAmount
(suborderAmount without discount)
D

aggregatorCharges
(Aggregator's Commision)
E

sellerDiscount
(implicit and explicit seller discount)
F

aggregatorDiscount
(Aggregator funded GV)
G

CODAmount
(Amount of the split that will be COD. To be used only in case of Prepaid + COD transactions)
H

AmountToBeSettled
I

CODMode
(non-mandatory) - Values:
{1-Aggregator Logistics Service,
2- Non-Aggregator Logistics Service}
J

SplitDetails
{html formatted text}
K

holdPayout
(Non mandatory)
(set value to 1 to Hold payout)
(Do not pass value if not to hold)

Response expandCollapse

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:

574341 is the parent paymentID

574342 is the subpayment Id corresponding to suborderid5

574343 is the subpayment Id corresponding to suborderid6


Case Failure =>NULL

Success Message Text with description expandCollapse

Error message
Description
Splits added

Splits added successfully

Error Message Text with description expandCollapse

Error message
Description
Payment not initiated

MerchantID is null
Invalid merchant key

merchantKey not found in payumoney or is Null
Parent transaction not found

merchanttransactionID is invalid or not present in our system
Payment status is not success

Payment status is not success in PayuMoney wait for 40 mins till it gets success
Splits empty

JsonSplit passed is null
Split already added

In case if Splits already added ie: splits API is already called
Payment total plus sum of discount and COD amount from splits does not match the sent total amount

In case if COD+GV amount do not match total amount
Calculated total amount from splits does not match the sent total amount

In case if sum of all the splits do not match the Total transaction amount

Sample casesexpandCollapse

Case 1: Prepaid + COD transaction

Total selling price of cart => 8000

Prepaid component (Payu): 3000

COD component: 4000

Aggregator Discount: 1000

Aggregator charges: 1000

Add payment of amount 3000 via Payu (Prepaid) transaction.

Add Split as follow

copy 

https://test.payumoney.com/payment/payment/addPaymentSplit?merchantKey=fIvCne
&merchantTransactionId=test543&totalAmount=8000&totalDiscount=1000&jsonSplits=
[{"merchantId":"370159","splitAmount":"8000","aggregatorSubTransactionId":
"pretest9011001","aggregatorCharges":"1000","aggregatorDiscount":"1000",
"sellerDiscount":"0","CODAmount":"4000","CODMode":"1","splitDetails":"SOME_SPLIT",
"amountToBeSettled":"7000"}]

Case 2: COD transaction

Total selling price of cart => 5000

COD: 4000

Aggregator Discount: 1000

Aggregator charges: 1000

Add payment of amount 4000 via addPayment API(Mode COD):

Add Split as follow

copy 

https://test.payumoney.com/payment/payment/addPaymentSplit?merchantKey=fIvCne
&merchantTransactionId=test543&totalAmount=5000&totalDiscount=1000&jsonSplits=
[{"merchantId":"370159","splitAmount":"5000","aggregatorSubTransactionId":
"pretest9011001","aggregatorCharges":"1000","aggregatorDiscount":"1000",
"sellerDiscount":"0","CODAmount":"0","CODMode":"1","splitDetails":"SOME_SPLIT",
"amountToBeSettled":"4000"}]

Case 3: COD+GV+Seller Discount transaction

Total selling price of cart => 1000

COD : 800

Aggregator Discount: 100

Seller Discount: 100

Aggregator charges: 100

AmountToBeSettled: 800

Sum of amount from all sources – (Seller Discount+ aggregator Charges)
(1000-(100+100))
Add payment of amount 800 via Addpayment API (COD type) transaction.

Add Split as follow

copy 

https://test.payumoney.com/payment/payment/addPaymentSplit?merchantKey=fIvCne
&merchantTransactionId=hhjgj7886767hghj&totalAmount=1000&totalDiscount=200
&jsonSplits=[{"merchantId":"370159","splitAmount":"1000","aggregatorSubTransactionId":
"test87678","aggregatorCharges":"100","aggregatorDiscount":"100","sellerDiscount":
"100","CODAmount":"0","splitDetails":"SOME_SPLIT","amountToBeSettled":"800",
"holdPayout":"0"}]

API / Release Payment Split

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.

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

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.

URL's expandCollapse

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

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

Test API expandCollapse

copy 

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

Request Parameters expandCollapse

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

Response expandCollapse

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 Text with description expandCollapse

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

Sample Response Format expandCollapse

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 sub-payment
 
{
   "status": -1,
   "message": "Payment already released",
   "result": 574342,
   "errorCode": null
}

API / Unhold Payouts

This API will unhold the Payment which is held back while adding splits in API 2. We have this provision in split API to hold a suborder even when it is released. To unhold the transaction we need to pass the sub-paymentID.

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test API expandCollapse

copy 

https://test.payumoney.com/payment/payment/unholdPayout?paymentId=321234

Request Parameters expandCollapse

Parameter
Required
Type
Description
paymentId

Yes

String

subPaymentId for the split to unhold

Response expandCollapse

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 Text with description expandCollapse

Message
Description
Payment unholded successfully

When Payment unhold successfully
Please pass parent payment id

When the payment ID passed is invalid

Sample Response Format expandCollapse

Message
Description
Successful Response
 
{
   "status": 0,
   "message": "Payment unholded successfully",
   "result"
   {
      "paymentId": 574439,
   }
}
Failure Response in case when payment ID passed is invalid
 
{
   "status": -1,
   "message": "Please pass parent payment id",
   "result": null,
   "errorCode": null
}

API / Add Adjustment

This web-service is used to add adjustment of some amount that a marketplace merchant wants to credit to a sub-seller or recover from a sub-seller corresponding to some adjustment made. Adjustment can be of "CREDIT" or "DEBIT" type depending on the use case.

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

Use Case: Apart from normal settlements (credits) or refunds (Debits) there can be certain other scenarios in which a parent merchant wants to debit or credit one of its sub-seller with some random amount. This API provides them the flexibility to add adjustments corresponding to a reference ID.

URL's expandCollapse

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

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

Test API expandCollapse

copy 

https://www.payumoney.com/payment/addAdjustmentItem?amount=4000&referenceId=test123
&merchantId=987654&remark=adjustremark1credit&adjustmentType=credit&blockType=none
&aggregatorKey =fIbC54

Request Parameters expandCollapse

Parameter
Required
Type
Description
Amount

Yes

String

Amount to be adjusted
referenceId

Yes

String

Payu money PaymentId of the split order that is to be adjusted or any system generated string in case of explicit adjustments
merchantId

Yes

String

Payu money merchant id of the seller for whom the adjustment is to be added.
Remark

Yes

String

Text field for description/details.
adjustmentType

Yes

String

Pass string "debit" to make debit type adjustments Pass string "credit" to make credit type adjustments
blockType

Yes

String

send 'none' always
aggragatorKey

Yes

String

Payu key of the parent merchant

Response expandCollapse

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

Success msg: Adjustment Item has been added
Result

String

Case Success => Object containing adjustmentItemId
Case Failure => NULL

Sample Response Format expandCollapse

Message
Description
Successful Response
 
{
   "status": 0,
   "message": "Adjustment Item has been added",
   "result"
   {
      "adjustmentItemId": 693,
      "merchantId": 170690,
      "referenceId": test1224,
      "adjustmentType": debit,
      "amount": 100,
      "remarks": null,
      "addedOn": 1387139948740,
      "updatedOn": 1387139948740,
      "completedOn": null,
      "status": new,
      "settlementId": null,
      "blockType": none,
      "aggregatorId": 170690,
      "complementAdjustmentItemId": -1,
   }
}

How to add an adjustment ?

Every adjustment has a debit party and a credit party. If the adjustment to be added is of "CREDIT" type then we need to debit the marketplace first and credit the merchant, if the type is "DEBIT" then we need to debit the merchant first and then credit the marketplace.

USECASE 1: If aggregator merchant wants to debit it's sub-merchant with some random amount.

So now aggregator wants to debit merchantId=123456 with amount=4900, so below is the API format

copy 

https://www.payumoney.com/payment/addAdjustmentItem?amount=4900&referenceId=refId123
&merchantId=123456&remark=adjustremark1debit&adjustmentType=debit&blockType=none
&aggragatorKey=fIvCne

Upon adding the above adjustment the merchant (123456) will be debited from its upcoming settlement and once money is debited, the aggregator merchant will be credited with the same amount into its next settlement from payumoney.

USECASE 2: If aggregator merchant wants to credit it's sub-merchant with some random amount.

So now aggregator wants to credit merchantId=123456 with amount=4900, so below is the API format

copy 

https://www.payumoney.com/payment/addAdjustmentItem?amount=4900&referenceId=refId456
&remark=adjustremark1credit&adjustmentType=credit&blockType=none&aggragatorKey=fIvCne

Upon adding the above adjustment the aggregator merchant will be debited from its upcoming settlement and once money is debited, the merchant (123456) will be credited with the same amount into its next settlement from payumoney.

API / Refund

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

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test API expandCollapse

copy 

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

Request Parameters expandCollapse

Parameter
Required
Type
Description
paymentId

Yes

Integer

Payumoney PaymentId 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 sub-merchant's amount to be settled
aggregatorAmount

Yes

String

In case of partial refund:
Amount that is to be debited from the aggregator commision

Following are the conditions on the refund API

  • Refund can only be called at sub-order level i.e. The payment Id passed should always be a child payment ID

  • The amount to be refunded should always be <= total split/sub-order amount

  • Set refund type to 1 always

  • Sum of merchantAmount and aggregatorAmount should always be equal to the refundAmount

Response expandCollapse

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

Message Text with description expandCollapse

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

Sample Response Format expandCollapse

Message
Description
Successful Response:
 
{
   "status": 0,
   "message": "Refund Initiated",
   "result": 9301,
   "errorCode": null,
}

API / Get Refund status

This web-service is used to get the current status of a particular refund by searching it with RefundID, PaymentId or both.

HTTP Method : GET Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test API expandCollapse

copy 

https://test.payumoney.com/payment/payment/getRefundStatus?paymentId=567890
&refundId=556999

Request Parameters expandCollapse

Parameter
Required
Type
Description
paymentId

Yes

String

Payment Id of the sub-order against which the refund has been fired
RefundId

Yes

String

It's the refund Id of the fired refund

Response expandCollapse

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 => refund status of that RefundId
Case Failure => NULL

Sample Response Format expandCollapse

Message
Description
Successful Response
 
{
   "status": 0,
   "message": "Result Is",
   "result"
   {
      "paymentId": 574908,
      "refunds"
      [{
         "refundId": 9301,
         "paymentId": 574908,
         "refundAmount": 500,
         "merchantId": 370159,
         "refundStatus": Refund In Progress,
         "merchantTxnId": suborderid5,
      }]       
   },
}
Failure Response when refund ID is not valid
 
{
   "status": -1,
   "message": "Given Refund Doesn't Exsist",
   "result": null,
   "errorCode": null,
}
Failure Response when refund ID is not passed
 
{
   "status": 0,
   "message": "Pass Valid RefundId",
   "result": null,
   "errorCode": null,
}

Refund Status in responseexpandCollapse

Response Status
Status meaning
Refund In Progress

Refund is initiated and under process
Failed

Refund has failed
Completed

Refund completed

API / Get settlement status

This web-service will provide the list of all the parent payment Ids and Child payment Id's settled for a given marketplace in a given interval of time, there is an additional parameter Last N hours (Where N is the no. of hours backward from current time)

So the response will contain the list of all payment ID's which got settled in last N hours. Where N ranges from 1-24 hours so basically payment settled during previous day.

HTTP Method : GET Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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


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

Test API expandCollapse

copy 

https://test.payumoney.com/payment/payment/getsettledPaymentsLastNHours?Ncount=22

Request Parameters expandCollapse

Parameter
Required
Type
Description
Ncount

Yes

String

Ncount is the number of hours and it ranges from 1 to 24 hrs

Sample Response Format expandCollapse

Message
Description
Successful Response
 
{
   "status": 0,
   "message": "Result Is",
   "result"
   {
      'settledparentPaymentId' : '565656,767676,676767'
      'SettledChildPaymentId' : '565656,767676,676767'
   },
}

Result object will contain two sets

  • settledparentPaymentId : it'll contain the comma separated parentPayment IDs settled

  • SettledChildPaymentId : It'll contains the comma separated child payment IDs settled

API / Check payment status

This web-service will be used by aggregator merchant to reconcile a list of transactions with PayUMoney. You will post us a list of merchantTransactionIds (in pipe separated format). And we will provide the status of the paymentIds with those merchantTransactionIds.

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test API expandCollapse

copy 

https://test.payumoney.com/payment/payment/chkMerchantTxnStatus?merchantKey=flv4re
&merchantTransactionIds=100123abc|100124abc|100125abc

Request Parameters expandCollapse

Parameter
Required
Type
Description
merchantKey

Yes

Payu money key of the merchant

xbch78J
merchantTransactionIds

Yes

Pipe separated merchant transaction ids(txnid) (Limit = 50)

100123abc|100124abc|100125abc

Sample Response Format expandCollapse

Message
Description
Successful Response
 
{
   "status": 0,
   "message": "Result Is",
   "result"
   [{
      "merchantTransactionId" : "100123abc",
      "paymentId" : "456789",
      "status" : "Settlementinprocess",
      "amount" : "1235.55",
   }
   {
      "merchantTransactionId" : "100125abc",
      "paymentId" : "456791",
      "status" : "Completed",
      "amount" : "4535.55",
   }
   {
      "merchantTransactionId" : "100124abc",
      "paymentId" : "456790",
      "status" : "Success",
      "amount" : "125.0",
   }]
}

API / Hold Payouts

This API will be used to hold a particular sub-order, please make sure you haven't call the refund API for this sub-order and you need to pass Authorization header along with this API.

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test API expandCollapse

copy 

https://test.payumoney.com/payment/payment/holdPayout?paymentId=5656566

Request Parameters expandCollapse

Parameter
Required
Type
Description
paymentId

Yes

String

subPaymentId for the split to hold

Response expandCollapse

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 Text with description expandCollapse

Message
Description
Payment unholded successfully

When Payment unhold successfully

Payment ID is not associated with this Aggregator ID

When the payment ID passed is invalid or not linked to the sub-merchant of the calling aggregator

Can't hold now as the payment has been picked for settlement

Payment is already picked in settlement process

Can't hold now as the payment status is refunded/Refund in progress

Aggregator has called refund API for this sub-paymentID
Payment Id already on hold

Payment ID is already on hold

Sample Response Format expandCollapse

Message
Description
Successful Response
 
{
   "status": 0,
   "message": "PaymentId hold successfully",
   "result": null,
   "errorCode": null,
}

API / Update Split

This API will be used to update the details of a particular suborder for example: merchantId, aggregator commission, merchant's amount to be settled.

HTTP Method : POST Content-Type: Application/json Requires Authentication: YES

URL's expandCollapse

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

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

Test API expandCollapse

copy 

https://test.payumoney.com/payment/payment/updatePaymentSplit?paymentId=7576576
&merchantId=7575675&aggregatorSubTransactionId=sub1-2345&aggregatorCharges=78
&splitDetails=dummysplitdetails&amountToBeSettled=45&holdPayout=0

Request Parameters expandCollapse

Parameter
Required
Type
Description
paymentId

Yes

String

Payumoney Payment Id of that split
merchantId

Yes

String

revised Payumoney merchant Id of the sub-seller
aggregatorSubTransactionId

Yes

String

revised Suborder Id for that suborder
aggregatorCharges

Yes

String

revised aggregator commission
splitDetails

Yes

String

revised splits details
amountToBeSettled

Yes

String

revised amount to be settled to the seller
holdPayout

Yes

String

revised value of hold payout flag

Response expandCollapse

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 => updated Payment object of split
Case Failure => NULL