Validate Offer API

The validate_offer API validates the payment request against an offer key. This API doesn’t apply the offer and only validates the request.

Endpoints


Test Environment	https://sandbox.payu.in/offers/transactions/validate
Production Environment	https://api.payu.in/offers/transactions/validate

Request headers

The request header contains the following fields:

The following sample Java code contains the logic used to encrypt as described in the above table:

import com.google.gson.Gson;
import com.google.gson.JsonObject;
import org.apache.commons.codec.binary.Base64;
import org.joda.time.DateTime;
import org.joda.time.format.DateTimeFormat;

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;

public class HmacAuth {

    public static String getSha256(String input) {
        try {
            MessageDigest md = MessageDigest.getInstance("SHA-256");
            byte[] digest = md.digest(input.getBytes());
            return Base64.encodeBase64String(digest);
        } catch (NoSuchAlgorithmException ignored) {}
        return null;
    }

    public static JsonObject getRequestBody(){
        JsonObject requestJson = new JsonObject();
        requestJson.addProperty("firstname","John");
        requestJson.addProperty("lastname","Doe");
        return requestJson;
    }

    public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
        String key = "smsplus";
        String secret = "admin";
        Gson gson = new Gson();
        String date = DateTimeFormat.forPattern("EEE, dd MMM yyyy HH:mm:ss 'GMT'").withZoneUTC().print(new DateTime());
        System.out.println(date);
        JsonObject requestJson = getRequestBody();
        String digest = getSha256(gson.toJson(requestJson));
        System.out.println(digest);
        String signingString = new StringBuilder()
            .append("date: " + date)
            .append("\ndigest: " + digest).toString();
        Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
        SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
        sha256_HMAC.init(secret_key);
        String signature = Base64.encodeBase64String(sha256_HMAC.doFinal(signingString.getBytes()));
        String authorization = new StringBuilder()
            .append("hmac username=\"")
            .append(key)
            .append("\", algorithm=\"hmac-sha256\", headers=\"date digest\", signature=\"")
            .append(signature)
            .append("\"").toString();
        System.out.println(authorization);
    }
}

The sample header is similar to the following:

📘
Note:
You need to include the current date and time in the Date field of the header.

'Date: Tue, 09 Aug 2022 12:14:51 GMT'
'Digest: omlvf5r6yimCxH+TfScrGryCGslY3CIF50/zIt/AMk4='
'Authorization: hmac username="smsplus", algorithm="hmac-sha256", headers="date digest", signature="PojEYoRaldbjj5NgO+B3c8R1Id4Sefm5mYdFN+MYf2E="'

Request parameters

Parameter	Description	Example
amount optional	`float` The offer amount is passed to validate whether the offer is applicable.	10000
clientId conditional	`integer` You can use this parameter to pass the client ID value.	8000123
mid conditional	`integer` You can use this parameter to pass the clientId or merchantId.	7043873219
autoApply	`boolean` This parameter contains a flag to specify whether the offer can be automatically applied. It can contain any of the following:	false
merchantNceParamActive	`boolean` This parameter contains a flag to specify whether the NCE offer needs to be validated. It can contain any of the following:	false
offerKeys mandatory	`string Array` Validate whether offerKey which are passed is valid.	offer@123
paymentDetail mandatory with card number \|	`JSON` This parameter is in a JSON format. For the details of fields, refer to the Description of paymentDetail JSON Fields.
paymentId optional	`integer` The transaction ID is submitted using this parameter for logging purpose.
userDetail mandatory	`JSON` This parameter is in a JSON format. For the details of fields, refer to the Description of userDetail JSON Fields.
skus	JSON` This parameter is in a JSON format. For more information, refer to Description of skusDetail JSON Fields.

Description of paymentDetail JSON fields

Parameter	Description	Example
cardNumber mandatory with card number	`integer` This parameter must contain the card number for which offer needs to be validated. Note: Either the cardNumber or cardToken parameter is mandatory for the credit card or debit card offer transaction.
cardToken mandatory for saved card	`string` This parameter is used to specify the card token of the saved card. Note: Either the cardNumber or cardToken parameter is mandatory for the credit card or debit card offer transaction.	1234 4567 2456 3566
cardTokenType mandatory for save card	`integer` This parameter is used to specify the card token type of the saved card. Currently, only network tokens are supported by PayU Offer Engine, so value of this field must be 1.	1
cardHash optional	`string` This parameter is used to specify the cardHash of the saved card.
cardMask optional	`integer` This parameter is used to specify the card mask of the saved card.
category mandatory	`string` This parameter is used to specify any of the following payment mode used for the transaction:	CREDITCARD
paymentCode mandatory	`string` This parameter used to specify the payment code that is used to identify the particular payment option.
vpa optional	`string` This parameter is applicable only for UPI transactions to specify the VPA or UPI handle. Note: This parameter is mandatory in case of UPI collect flow, that is, isCollect=true)	anything@payu

Sample paymentDetail JSON

"paymentDetail": {
    "cardNumber": 5123**789012346,
    "cardToken" : null,
    "cardTokenType" : null
    "cardHash": "card hash",
    "cardMask": "card mask",
    "category": "DEBITCARD",
    "paymentCode": null,
    "vpa": null
  }

Description of userDetail JSON Fields

Parameter	Description	Example
email	`String`This parameter contains the email ID of the merchant's customer who is eligible for the offer	[email protected]
phoneNo	`String` This parameter contains the phone number of the merchant's customer who is eligible for the offer.	8042296254
userToken mandatory	`String` This parameter is used to uniquely identify a user for a client/merchant.

Sample userDetail JSON

 "userDetail": {
    "email": "string",
    "phoneNo": "string",
    "userToken": "useToken123456"
  }

Description of skusDetails JSON fields

In addition to the request parameters listed in this section, the skusDetail parameter with skus in an JSON array is posted, where each skus contain the following fields are posted in an array:

Field	Description
autoApply	The flag to specify to automatically apply the offer.
skuAmount optional	The price of one/ single unit of SKU is specified in this field.
offerKeys optional	The offer keys to filter at SKU-level is specified in this field.
quantity  optional	The quantity for the product is specified in this field.
skuId mandatory	The product identifier to select offer is specified in this field. For more information on creating a SKU offer, refer to SKU-Based Offer using Merchant Hosted Checkout.

Sample skusDetails

"skusDetail": {
    "skus": [
      {
        "skuAmount": 1000,
        "autoApply": true,
        "offerKeys": [
          "SummerSpecialOffer2021@q1Bh0jsogwqP"
        ],
        "quantity": 1,
        "skuId": "1"
      }
    ]
  }

Sample Request

Using the card number

curl --location --request POST 'https://sandbox.payu.in/offers/transactions/validate' \
--header 'Date: Tue, 09 Aug 2022 12:14:51 GMT' \
--header 'Digest: omlvf5r6yimCxH+TfScrGryCGslY3CIF50/zIt/AMk4=' \
--header 'Authorization: hmac username="smsplus", algorithm="hmac-sha256", headers="date digest", signature="PojEYoRaldbjj5NgO+B3c8R1Id4Sefm5mYdFN+MYf2E="' \
--header 'Content-Type: application/json' \
--header 'Cookie: PHPSESSID=fucavghe82bnd1baej5mdgmaem' \
--data-raw '{
{
  "amount": 500,
  "offerKeys": [
    "SummerSpecialOffer2021@07qIdabo1AHl"
  ],
  "paymentDetail": {
    "cardNumber": 5123***789012346,
    "cardHash": "card hash",
    "cardMask": "card mask",
    "category": "DEBITCARD",
    "paymentCode": null,
    "vpa": null,
  },
  "paymentId": 2500,
  "userDetail": {
    "email": "string",
    "phoneNo": "string",
    "userToken": "userToken"
  }
}
}'

Using a saved card

curl --location --request POST 'https://sandbox.payu.in/offers/transactions/validate' \
--header 'Date: Tue, 09 Aug 2022 12:14:51 GMT' \
--header 'Digest: omlvf5r6yimCxH+TfScrGryCGslY3CIF50/zIt/AMk4=' \
--header 'Authorization: hmac username="smsplus", algorithm="hmac-sha256", headers="date digest", signature="PojEYoRaldbjj5NgO+B3c8R1Id4Sefm5mYdFN+MYf2E="' \
--header 'Content-Type: application/json' \
--header 'Cookie: PHPSESSID=fucavghe82bnd1baej5mdgmaem' \
--data-raw '{
{
  "amount": 500,
  "offerKeys": [
    "SummerSpecialOffer2021@07qIdabo1AHl"
  ],
  "paymentDetail": {
    "cardToken": 1234 4567 2456 3566,
    "cardTokenType": 1,
    "cardHash": "card hash",
    "cardMask": "card mask",
    "category": "DEBITCARD",
    "paymentCode": null,
    "vpa": null,
  },
  "paymentId": 2500,
  "userDetail": {
    "email": "string",
    "phoneNo": "string",
    "userToken": "userToken"
  }
}
}'

Response parameters

The response involves the following parameters and the result parameter contains the offer results:

result parameter JSON Details

The result parameter contains the result in a JSON format and the fields in the JSON are described in the following table. The offerDiscount and offerDetail fields in this JSON contains the offer details as described in the following subsections:

This field contains any of the following values to specify whether the offer is valid or not valid:

Field	Description	Example
paymentid	`Integer` This field contains payment ID for the transaction.	2500
clientId	`Integer` This field contains reference of the merchant.	1
mid	`Integer`This field contains the unique identifier provided by PayU to each merchant.	1
amount	`Float` This field contains the Offer transaction amount	10000.00
paymentcode	`String`The payment code that is used to identify the particular payment option.	HDFC
category	`String`This field payment mode used for the transaction.	creditcard
isValid	This field contains any of the following values to specify whether the offer is valid or not valid: - true: Signifies that the offer is a valid offer - false: Signified that the offer is a valid offer	true
offerDiscount	`JSON Object` This field contains offer discount details in a JSON format. For more information, refer to the offerDiscount Field JSON Details subsection.	Refer to the offerDiscount Field JSON Details subsection.
offerDetail	`JSON Object` This field contains offer details in a JSON format. For more information, refer to the offerDetail Field JSON Details subsection.	Refer to the offerDetail Field JSON Details subsection.
failureReason	`String` This field is used to display the reason for failure.	"Success"
skusDetail	`Array` This parameter contains the product or SKU offer details. For more information, refer to skusParameter Field Description.

The sample value for result parameter in a JSON is similar to the following:

"result": {
        "paymentId": 2500,
        "clientId": 1,
        "mid": 1,
        "amount": 500,
        "paymentCode": null,
        "category": "DEBITCARD",
        "isValid": true,
        "offerDiscount": {
            "offerKey": "SummerSpecialOffer2021@07qIdabo1AHl",
            "offerType": "INSTANT",
            "discount": 100.00,
            "discountedAmount": 400.00,
            "discountType": "ABSOLUTE"
        },
        "offerDetail": {
            "offerId": 10005,
            "offerKey": "SummerSpecialOffer2021@07qIdabo1AHl",
            "offerType": "INSTANT",
            "title": "SummerSpecialOffer",
            "description": "SummerSpecialOffer discount",
            "validFrom": "2021-07-01 17:02:11",
            "validTo": "2022-08-05 15:53:16",
            "tnc": "abc",
            "tncLink": "abcd",
            "discountType": "ABSOLUTE",
            "offerPercentage": null,
            "maxDiscountPerTxn": 100.00,
            "minTxnAmount": 10.00,
            "maxTxnAmount": 25000.00,
            "status": "ACTIVE",
            "isNce": false,
            "disallowTransactionInvalidOffer":true
        },
        "failureReason": "Success"
    }

offerDiscount Field JSON Details

The offerDiscount field in the result JSON contains the offer discount details in a JSON format as described in the following table:

Field	Description	Example
offerKey	`String` This field contains the unique identifier for a particular offer.	SummerSpecialOffer2021@q1Bh0jsogwqP
offerType	`String` The field contains any of the following type of offer: - INSTANT  - CASHBACK	INSTANT
discount	This field contains the total discount available on the transaction once applied the specific offer.	100.00
discountedAmount	This field contains the final Net amount of the transaction after applying the specific offer.	400.00
discountType	This field contains any of the following discount type that were defined: - ABSOLUTE  - PERCENTAGE	ABSOLUTE

The sample value for offerDiscount field in a JSON is similar to the following:

"offerDiscount": {
            "offerKey": "SummerSpecialOffer2021@07qIdabo1AHl",
            "offerType": "INSTANT",
            "discount": 100.00,
            "discountedAmount": 400.00,
            "discountType": "ABSOLUTE"
        },

offerDetail Field JSON Details

The offerDetail field in the result JSON contains the offer details in a JSON format as described in the following table:

Field	Description	Example
offerId	`Integer` This field contains the unique identifier to identify an offer.	10005
offerKey	`String` This field contains the unique identifier for a particular offer.	SummerSpecialOffer2021@q1Bh0jsogwqP
offerType	`String` This field contains the offer owner.	MERCHANT
title	`String` This field contains the title of the offer that will be displayed for customers.	festive_500
description	`String` This field contains the description of offer for the merchant's reference.	festive discount
validFrom	`String` The field contains the offer start time.	2021-07-01 17:02:11
validTo	`String` The field contains the offer end time.	2022-08-05 15:53:16
tnc	`String` This field contains the Terms & Conditions for applying promo that will be displayed to customers while accessing the link provided in the tncLink field.	abc
tncLink	`String` This field contains URL to fetch details on Terms & Conditions and details specified in the tnc is displayed.	abcd
discountType	`String`This field contains any of the following discount type that was defined:	ABSOLUTE
offerPercentage	`Float`This field contains the define the discount percentage for the offer.	10
maxDiscountPerTxn	`String` The field contains the max discount available for a transaction.	100.00
minTxnAmount	`Float` The field contains the minimum transaction amount offer will be applicable.	10.00
maxTxnAmount	`Float` The field contains the maximum transaction amount offer will be applicable	25000.00
status	`String`This field contains any of the following current offer status: - DRAFTED - DEACTIVEATED - PAUSED - ACTIVE	ACTIVE
isNce	`Boolean`This field contains any of the following values to specify whether the offer is a no cost EMI offer or not: - true: The offer is a No Cost EMI offer - false: The offer is not a No Cost EMI offer
disallowTransactionI nvalidOffer	Boolean` This field contains any of the following values to specify whether the transaction should continue without offer or with offer: - true: The transaction should continue without offer - false: The transaction should continue with offer	true

The sample value for offerDetail field in a JSON is similar to the following:

"offerDetail": {
            "offerId": 10005,
            "offerKey": "SummerSpecialOffer2021@07qIdabo1AHl",
            "offerType": "INSTANT",
            "title": "SummerSpecialOffer",
            "description": "SummerSpecialOffer discount",
            "validFrom": "2021-07-01 17:02:11",
            "validTo": "2022-08-05 15:53:16",
            "tnc": "abc",
            "tncLink": "abcd",
            "discountType": "ABSOLUTE",
            "offerPercentage": null,
            "maxDiscountPerTxn": 100.00,
            "minTxnAmount": 10.00,
            "maxTxnAmount": 25000.00,
            "status": "ACTIVE",
            "isNce": false,
            "disallowTransactionInvalidOffer":true
        },

skusDetail Parameter Description

In addition to the request parameters listed in the Fetch Offers API section, the skusDetail parameter is posted with the following fields are posted in an array:

Field	Description
skuAmount optional	`String` The price of one/ single unit of SKU is specified in this field.
skuId mandatory	`String` The product identifier to select offer is specified in this field.
quantity  optional	`String` The quantity for the product is specified in this field.
offerKeys optional	`String`The offer keys to filter at SKU-level is specified in this field.

Sample response

Success scenario

{
    "code": "200",
    "message": "Offer Validated Successfully",
    "status": 1,
    "result": {
        "paymentId": 2500,
        "clientId": 1,
        "mid": 1,
        "amount": 500,
        "paymentCode": null,
        "category": "DEBITCARD",
        "isValid": true,
        "offerDiscount": {
            "offerKey": "SummerSpecialOffer2021@07qIdabo1AHl",
            "offerType": "INSTANT",
            "discount": 100.00,
            "discountedAmount": 400.00,
            "discountType": "ABSOLUTE"
        },
        "offerDetail": {
            "offerId": 10005,
            "offerKey": "SummerSpecialOffer2021@07qIdabo1AHl",
            "offerType": "INSTANT",
            "title": "SummerSpecialOffer",
            "description": "SummerSpecialOffer discount",
            "validFrom": "2021-07-01 17:02:11",
            "validTo": "2022-08-05 15:53:16",
            "tnc": "abc",
            "tncLink": "abcd",
            "discountType": "ABSOLUTE",
            "offerPercentage": null,
            "maxDiscountPerTxn": 100.00,
            "minTxnAmount": 10.00,
            "maxTxnAmount": 25000.00,
            "status": "ACTIVE",
            "isNce": false,
            "disallowTransactionInvalidOffer":true
        },
        "failureReason": "Success"
    }
}

Failure scenarios

Merchant ID does not exists

{
    "code": "404",
    "message": "Merchant with merchant Id :1800122 does not exists",
    "status": 0,
    "exceptionId": "9cf201ab-2ad3-439e-a7a6-f707d2f76e48"
}

Client ID does not exist or not matching with platform ID

{
    "code": "404",
    "message": "client with clientId :4 , platformId :12 does not exists.",
    "status": 0,
    "exceptionId": "6985749b-9de4-4d39-9242-d19d35a82d0c"
}

Service Unavailable


{
    "code": "500",
    "message": "Service Unavailable",
    "status": 0,
    "exceptionId": "65466805-5be1-4fa4-912d-d28cf620d687"
}

Request headers

📘Note:

Request parameters

Description of paymentDetail JSON fields

Sample paymentDetail JSON

Description of userDetail JSON Fields

Sample userDetail JSON

Description of skusDetails JSON fields

Sample skusDetails

Sample Request

Response parameters

result parameter JSON Details

offerDiscount Field JSON Details

offerDetail Field JSON Details

skusDetail Parameter Description

Sample response

Success scenario

Failure scenarios

📘
Note: