Fetch Balance All API

Environment


Production	https://api.payu.in/loyalty-points/v1/balance/all
Test	https://apitest.payu.in/loyalty-points/v1/balance/all

HTTP Method: POST

Request header

All PayU Loyalty Points API requests require HMAC-SHA512 header authentication.

Required request headers

Header	Description
Content-Type	`application/json`
Accept	`application/json`
mid	Merchant ID (MID) provided by PayU during onboarding. Some Loyalty Points APIs accept `MID` instead of `mid`.
Date	Current UTC timestamp in RFC 1123 format (for example, `Fri, 24 Jul 2026 05:51:20 GMT`).
Authorization	HMAC signature. Format: `hmac username="<merchant_key>", algorithm="sha512", headers="date", signature="<computed_signature>"`. For field descriptions, refer to the below authorization fields description (inside the Accordion).

authorization fields description

Parameter	Description
username	Merchant key provided by PayU during onboarding.
algorithm	Hashing algorithm used for the signature. Use `sha512`.
headers	Headers included in the signature. Use `date`.
signature	SHA-512 hash of the signing string, in lowercase hexadecimal. For more information, refer to hashing algorithm.

hashing algorithm

Build the signing string using the exact raw JSON request body sent with the request:

sha512(<raw_request_body>|<Date>|<merchant_secret>)

Where:

<raw_request_body> is the exact JSON body string posted with the request.
<Date> is the same value sent in the Date header.
<merchant_secret> is the merchant Salt provided by PayU during onboarding.

Convert the SHA-512 output to lowercase hexadecimal and pass it as signature in the Authorization header:

hmac username="<merchant_key>", algorithm="sha512", headers="date", signature="<signature>"

Signing rules

Use the exact raw JSON request body.
The Date value in the signature must exactly match the Date header.
Regenerate Date and Authorization for every request.

Sample header authentication code

var merchant_key = 'YOUR_MERCHANT_KEY';
var merchant_secret = 'YOUR_MERCHANT_SALT';

// date
var date = new Date();
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;
}

function isEmpty(obj) {
  for (var key in obj) {
    if (obj.hasOwnProperty(key)) return false;
  }
  return true;
}

Request parameters

Parameter	Description	Example
loyaltyProviders `mandatory`	`Array` Array of loyalty provider names to fetch rewards from	["TWID", "ZILLION"]
mobileNumber `mandatory`	`String` User's mobile number (masked for privacy)	88001085**
orderAmount `mandatory`	`Number` Order amount for which reward points are applicable	1000

Sample request

curl -X POST "{{loyalty-service-url}}/v1/balance/all" \
  -H "accept: application/json" \
  -H "Content-Type: application/json" \
  -H "mid: YOUR_MERCHANT_ID" \
  -H "Date: Fri, 24 Jul 2026 05:51:20 GMT" \
  -H "Authorization: hmac username=\"YOUR_MERCHANT_KEY\", algorithm=\"sha512\", headers=\"date\", signature=\"GENERATED_SIGNATURE\"" \
  -d '{
    "loyaltyProviders": ["TWID", "ZILLION"],
    "mobileNumber": "88001085**",
    "orderAmount": 1000
  }'

import requests
import json

url = "{{loyalty-service-url}}/v1/balance/all"

headers = {
  "accept": "application/json",
  "Content-Type": "application/json",
  "mid": "YOUR_MERCHANT_ID",
  "Date": "Fri, 24 Jul 2026 05:51:20 GMT",
  "Authorization": "hmac username=\"YOUR_MERCHANT_KEY\", algorithm=\"sha512\", headers=\"date\", signature=\"GENERATED_SIGNATURE\""
}

payload = {
  "loyaltyProviders": ["TWID", "ZILLION"],
  "mobileNumber": "88001085**",
  "orderAmount": 1000
}

response = requests.post(url, headers=headers, json=payload)
print("Status Code:", response.status_code)
print("Response:", response.text)

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

class Program
{
    static async Task Main(string[] args)
    {
        var client = new HttpClient();
        var url = "{{loyalty-service-url}}/v1/balance/all";
        
        client.DefaultRequestHeaders.Add("accept", "application/json");
        client.DefaultRequestHeaders.Add("Content-Type", "application/json");
        client.DefaultRequestHeaders.Add("mid", "YOUR_MERCHANT_ID");
        client.DefaultRequestHeaders.Add("Date", "Fri, 24 Jul 2026 05:51:20 GMT");
        client.DefaultRequestHeaders.Add("Authorization", "hmac username=\"YOUR_MERCHANT_KEY\", algorithm=\"sha512\", headers=\"date\", signature=\"GENERATED_SIGNATURE\"");

        var json = new
        {
            loyaltyProviders = new[] { "TWID", "ZILLION" },
            mobileNumber = "88001085**",
            orderAmount = 1000
        };
        var jsonString = JsonSerializer.Serialize(json);
        var content = new StringContent(jsonString, Encoding.UTF8, "application/json");
        
        var response = await client.PostAsync(url, content);
        var responseBody = await response.Content.ReadAsStringAsync();
        
        Console.WriteLine($"Status Code: {(int)response.StatusCode}");
        Console.WriteLine($"Response: {responseBody}");
    }
}

const url = "{{loyalty-service-url}}/v1/balance/all";

const headers = {
  "accept": "application/json",
  "Content-Type": "application/json",
  "mid": "YOUR_MERCHANT_ID",
  "Date": "Fri, 24 Jul 2026 05:51:20 GMT",
  "Authorization": "hmac username=\"YOUR_MERCHANT_KEY\", algorithm=\"sha512\", headers=\"date\", signature=\"GENERATED_SIGNATURE\""
};

const payload = {
  "loyaltyProviders": ["TWID", "ZILLION"],
  "mobileNumber": "88001085**",
  "orderAmount": 1000
};

async function makeRequest() {
    try {
        const response = await fetch(url, {
            method: "POST",
            headers: headers,
            body: JSON.stringify(payload)
        });
        
        const data = await response.text();
        console.log("Status Code:", response.status);
        console.log("Response:", data);
    } catch (error) {
        console.error("Error:", error);
    }
}

makeRequest();

import java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
import java.nio.charset.StandardCharsets;
import com.google.gson.Gson;
import java.util.Arrays;
import java.util.List;

public class ApiRequest {
    public static void main(String[] args) throws Exception {
        URL url = new URL("{{loyalty-service-url}}/v1/balance/all");
        HttpURLConnection conn = (HttpURLConnection) url.openConnection();
        conn.setRequestMethod("POST");
        conn.setDoOutput(true);
        
        conn.setRequestProperty("accept", "application/json");
        conn.setRequestProperty("Content-Type", "application/json");
        conn.setRequestProperty("mid", "YOUR_MERCHANT_ID");
        conn.setRequestProperty("Date", "Fri, 24 Jul 2026 05:51:20 GMT");
        conn.setRequestProperty("Authorization", "hmac username=\"YOUR_MERCHANT_KEY\", algorithm=\"sha512\", headers=\"date\", signature=\"GENERATED_SIGNATURE\"");

        Gson gson = new Gson();
        String jsonInputString = "{\"loyaltyProviders\":[\"TWID\",\"ZILLION\"],\"mobileNumber\":\"88001085**\",\"orderAmount\":1000}";
        
        try (OutputStream os = conn.getOutputStream()) {
            byte[] input = jsonInputString.getBytes(StandardCharsets.UTF_8);
            os.write(input, 0, input.length);
        }
        
        int responseCode = conn.getResponseCode();
        System.out.println("Status Code: " + responseCode);
        
        try (BufferedReader br = new BufferedReader(
                new InputStreamReader(conn.getInputStream(), StandardCharsets.UTF_8))) {
            StringBuilder response = new StringBuilder();
            String responseLine;
            while ((responseLine = br.readLine()) != null) {
                response.append(responseLine.trim());
            }
            System.out.println("Response: " + response.toString());
        }
    }
}

<?php

$url = "{{loyalty-service-url}}/v1/balance/all";

$headers = [
  "accept" => "application/json",
  "Content-Type" => "application/json",
  "mid" => "YOUR_MERCHANT_ID",
  "Date" => "Fri, 24 Jul 2026 05:51:20 GMT",
  "Authorization" => "hmac username=\"YOUR_MERCHANT_KEY\", algorithm=\"sha512\", headers=\"date\", signature=\"GENERATED_SIGNATURE\""
];

$payload = [
  "loyaltyProviders" => ["TWID", "ZILLION"],
  "mobileNumber" => "88001085**",
  "orderAmount" => 1000
];

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));
curl_setopt($ch, CURLOPT_HTTPHEADER, array_map(function($key, $value) {
    return "$key: $value";
}, array_keys($headers), $headers));

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo "Status Code: " . $httpCode . "\n";
echo "Response: " . $response . "\n";
?>

Response parameters

Parameter	Description	Example
data[].loyaltyProvider	`String` - Loyalty provider identifier for this response entry	`"TWID"`
data[].usableAmount	`Number` - Maximum monetary amount that can be saved	`500.0`
data[].usablePoints	`Number` - Required reward points for maximum savings	`500`
data[].title	`String` - Display title describing the reward offer	`"Save Rs 500 using 500 TWID Cash Points"`
data[].earnConfig.points	`Number` - Points that can be earned	`0`
data[].issuerDetailDTO.logo	`String` - Logo URL of the brand/issuer	`"https://cdn.twidpay.com/brand_logo.png"`
data[].holdApplicable	`Boolean` - Indicates if points can be held for the reward	`false`
data[].customErrorMessage	`String` - Error message for specific provider (if applicable)	`"Unable to process request for provider"`

Sample response

{
  "data": [
    {
      "loyaltyProvider": "TWID",
      "usableAmount": 500.0,
      "usablePoints": 500,
      "title": "Save Rs 500 using 500 TWID Cash Points",
      "earnConfig": { 
        "points": 0, 
        "amount": null, 
        "title": null 
      },
      "issuerDetailDTO": {
        "brandName": "TWID Cash",
        "logo": "https://cdn.twidpay.com/brand_image.png",
        "issuerType": "brand"
      },
      "holdApplicable": false
    },
    {
      "loyaltyProvider": "ZILLION",
      "customErrorMessage": "Unable to process request for provider",
      "usableAmount": null,
      "usablePoints": null
    }
  ]
}