Retrieve information about upcoming and pending settlements for a merchant. This API provides visibility into future settlements, helping merchants with cash flow planning and financial forecasting.
Environment
| Test Environment | https://test.payu.in/settlement/v1/merchantUpcomingSettlement |
| Production Environment | https://info.payu.in/settlement/v1/merchantUpcomingSettlement |
HTTP Method: GET
Request Parameters
Request Header
| Parameter | Description |
|---|---|
| date | The current date and time. For example, format of the date is Wed, 28 Jun 2023 11:25:19 GMT. |
| authorization | The actual HMAC signature generated using the specified algorithm (sha512) and includes the hashed data. For more information, refer to authorization fields description table below. |
authorization fields description
| Parameter | Description |
|---|---|
| username | Represents the username or identifier for the client or merchant, in this case, it's "smsplus". |
| algorithm | Use SHA512 algorithm for hashing and send this as header value. |
| headers | Specifies which headers have been used in generating the hash. In this case, only the "date" header is used. |
| signature | The actual HMAC signature generated using the specified algorithm (sha512) and includes the hashed data. For more information, refer to hashing algorithm. |
hashing algorithm
You must hash the request parameters using the following hash logic:
sha512(<Body data> + '|' + date + '|' + merchant_secret}Where, <Body data> contains the request Body posted with the request.
Sample authorization header code
var merchant_key = '<merchant_key>';
var merchant_secret = '<merchant_salt>';
// date
var date = new Date();
// var date = "Wed, 28 Jun 2023 11:25:19 GMT";
date = date.toUTCString();
// authorization
var authorization = getAuthHeader(date);
console.log(authorization);
function getAuthHeader(date) {
var AUTH_TYPE = 'sha512';
var data = isEmpty(request['data'])?"":request['data'];
var hash_string = data + '|' + date + '|' + merchant_secret;
console.log("Hash String is ", hash_string);
var hash = CryptoJS.SHA512(hash_string).toString(CryptoJS.enc.Hex);
var authHeader = 'hmac username="' + merchant_key + '", ' + 'algorithm="' + AUTH_TYPE + '", headers="date", signature="' + hash + '"'
return authHeader;
}
pm.environment.set('date', date);
pm.environment.set('authorization', authorization);
pm.environment.set('merchant_key',merchant_key);
pm.environment.set('merchant_secret',merchant_secret);
function isEmpty(obj) {
for(var key in obj) {
if(obj.hasOwnProperty(key))
return false;
}
return true;
}Other Header Parameters
| Parameter | Description | Example |
|---|---|---|
midmandatory | String Merchant identifier that the integration was registered with | 12202 |
Sample Request
curl --location 'https://test.payu.in/settlement/v1/merchantUpcomingSettlement' \
--header 'mid: 12202' \
--header 'Authorization: {{authorization}}' \
--header 'Date: {{date}}'
Sample Response
Success Scenario
{
"code": "2000",
"message": "Success",
"status": 0,
"result": {
"holdSettlementStatus": 0,
"lastSettledAmount": 2197.19,
"lastSettlementTime": "2026-04-06 14:22:12",
"upcomingSettlementAmount": 235129.81,
"upcomingSettlementTime": "2026-04-08 09:15:00",
"totalSettlementPendingAmount": 73224295.78,
"currencyType": "USD",
"merchantId": 8515874,
"pendingSettlementBreakdown": {
"saleAmount": 77328963.90,
"adjustmentAmount": 0.00,
"refundAmount": -975745.51,
"chargebackAmount": -120622.04,
"refundReversalAmount": 0.00,
"chargebackReversalAmount": 0.00,
"serviceFee": -2778968.71,
"serviceTax": -226059.93,
"convenienceFee": 0.00,
"convenienceTax": 0.00,
"additionalServiceFee": -158.58,
"additionalServiceTax": -28.54,
"txnCount": 53057
}
}
}No merchant found for ID
{
"code": "4000",
"message": "no Merchant found for id: <INVALID_ID> in settlement",
"status": 1
}Response Parameters
| Parameter | Type | Description |
|---|---|---|
| code | String | Business result code; success is typically 2000 |
| message | String | Short response text, e.g., Success |
| status | Integer | Application status: 0 = Success '1'= Failure |
| result | Object | Main response data container in JSON format. For more information, refer to result JSON Field Descriptions |
result JSON Field Descriptions
| Field | Description |
|---|---|
holdSettlementStatus | Indicator whether merchant settlements are on hold. Values: 1 = on hold, 0 = not on hold |
lastSettledAmount | Monetary amount that was settled in the most recent settlement |
lastSettlementTime | Timestamp of the last settlement in IST date-time format |
upcomingSettlementAmount | Monetary amount expected to be settled in the next settlement cycle |
upcomingSettlementTime | Timestamp (IST date-time format) of the next scheduled settlement |
totalSettlementPendingAmount | Total monetary amount still pending settlement (aggregate outstanding balance) |
currencyType | Currency code for amounts (e.g., "INR") |
merchantId | Identifier of the merchant for whom the snapshot is returned |
pendingSettlementBreakdown | JSON Object providing a component-wise breakdown of the pending/upcoming settlement amount. Numeric amounts may be 0 or omitted; negative values denote deductions/credits. For more information, refer to pendingSettlementBreakdown JSON Fields Description |
pendingSettlementBreakdown JSON Fields Description
| Field | Description |
|---|---|
saleAmount | Total transaction (sales) amount |
adjustmentAmount | Adjustments applied (positive or negative adjustments) |
refundAmount | Total refunds (usually negative when reducing payable amount) |
chargebackAmount | Total chargebacks (reductions due to disputes) |
refundReversalAmount | Amounts from reversed refunds (restored to merchant) |
chargebackReversalAmount | Amounts from reversed chargebacks |
serviceFee | Service fees charged |
serviceTax | Tax on service fee |
convenienceFee | Convenience fees charged to customer (affect settlement) |
convenienceTax | Tax on convenience fee |
additionalServiceFee | Any additional service fees |
additionalServiceTax | Tax on additional service fee |
txnCount | Number of transactions contributing to the breakdown |