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 `optional`	`boolean` This parameter contains a flag to specify whether the offer can be automatically applied. Note: If you had enable the Enforce Offer flag with PayU, the best offer out of the all the offers passed will be applied for the customer. While using this API, the autoApply parameter must be set to true if the offer is automatically applied.	false
merchantNceParamActive `mandatory`	`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 `conditional`	`JSON` This parameter is in a JSON format. For the details of fields, refer to the Description of paymentDetail JSON Fields. This parameter is mandatory when the payment method is saved card.	{ "cardNumber": 5123**789012346, "cardToken" : null, "cardTokenType" : null "cardHash": "card hash", "cardMask": "card mask", "category": "DEBITCARD", "paymentCode": null, "vpa": null }
paymentId `optional`	`integer` The transaction ID is submitted using this parameter for logging purpose.
cardBin `conditional`	`integer`Te card bin for cards used in the transaction. This field is mandatory for credit card /debit card offer transaction
category `mandatory`	`string`This parameter must contain any of the following payment category: - CREDITCARD - DEBITCARD - NETBANKING - WALLET - UPI - EMI	UPI
paymentCode `mandatory`	`string` The payment code used to identify the particular payment option.	HDFC
vpa `conditional`	`string`The VPA and it is applicable for UPI transactions.
userDetail `mandatory`	`JSON` This parameter is in a JSON format. For the details of fields, refer to the Description of userDetail JSON Fields.
skuDetail `optional`	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 `optional`	`String`This parameter contains the email ID of the merchant's customer who is eligible for the offer	[email protected]
phoneNo `optional`	`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 `mandatory`	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 and response for normal transactional offers

With autoApply=true

Sample request

{
    "amount": 300,
    "autoApply": true,
    "offerKeys": [],
    "paymentDetail": {
        "cardNumber": 1234567890123456,
        "cardToken": null,
        "cardTokenType": null,
        "category": "CREDITCARD",
        "paymentCode": "CC",
        "vpa": null
    },
    "paymentId": 11111135,
    "platformId": 1,
    "userDetail": {
        "email": "string",
        "phoneNo": "string",
        "userToken": "sds"
    }
}

Sample response

{
    "code": "200",
    "message": "Offer Validated Successfully",
    "status": 1,
    "result": {
        "flagToFail": false,
        "paymentId": 11111135,
        "clientId": 42693,
        "mid": 180012,
        "amount": 300,
        "downPaymentAmount": null,
        "emiAmount": null,
        "paymentCode": "CC",
        "category": "CREDITCARD",
        "isValid": true,
        "offerDiscount": {
            "offerKey": "TestOffer@fY6HdoP7da8L",
            "offerType": "INSTANT",
            "discount": 100.00,
            "discountedAmount": 200.00,
            "discountType": "ABSOLUTE"
        },
        "offerDetail": {
            "offerId": 66057,
            "offerKey": "TestOffer@fY6HdoP7da8L",
            "anchorOfferKey": null,
            "offerType": "INSTANT",
            "offerCategory": null,
            "title": "TestOffer",
            "description": "offer",
            "validFrom": "2024-10-14 00:00:00",
            "validTo": "2024-11-30 23:59:00",
            "tnc": "tnc",
            "tncLink": null,
            "discountType": "ABSOLUTE",
            "offerPercentage": null,
            "maxDiscountPerTxn": 100.00,
            "minTxnAmount": 101.00,
            "maxTxnAmount": 111111.00,
            "minRangeDiscount": null,
            "maxRangeDiscount": null,
            "status": "ACTIVE",
            "isNce": false,
            "disallowTransactionInvalidOffer": null,
            "isSkuOffer": false,
            "isSubventedOffer": false,
            "isBaseOffer": false,
            "amount": 300,
            "discount": 100.00,
            "discountedAmount": 200.00,
            "isValid": true,
            "failureReason": "Offer Validated Successfully",
            "recordType": "OFFER",
            "isGstSubvented": false,
            "isCohortOffer": false,
            "isDpEmi": false,
            "minDpRange": null,
            "maxDpRange": null,
            "downPaymentUnit": null,
            "issuerId": null,
            "issuerName": null
        },
        "totalDiscountDetail": {
            "totalCashbackDiscount": 0,
            "totalInstantDiscount": 100.00,
            "totalDiscountedAmount": 200.00
        },
        "offers": [
            {
                "offerId": 66057,
                "offerKey": "TestOffer@fY6HdoP7da8L",
                "anchorOfferKey": null,
                "offerType": "INSTANT",
                "offerCategory": null,
                "title": "TestOffer",
                "description": "offer",
                "validFrom": "2024-10-14 00:00:00",
                "validTo": "2024-11-30 23:59:00",
                "tnc": "tnc",
                "tncLink": null,
                "discountType": "ABSOLUTE",
                "offerPercentage": null,
                "maxDiscountPerTxn": 100.00,
                "minTxnAmount": 101.00,
                "maxTxnAmount": 111111.00,
                "minRangeDiscount": null,
                "maxRangeDiscount": null,
                "status": "ACTIVE",
                "isNce": false,
                "disallowTransactionInvalidOffer": null,
                "isSkuOffer": false,
                "isSubventedOffer": false,
                "isBaseOffer": false,
                "amount": 300,
                "discount": 100.00,
                "discountedAmount": 200.00,
                "isValid": true,
                "failureReason": "Offer Validated Successfully",
                "recordType": "OFFER",
                "isGstSubvented": false,
                "isCohortOffer": false,
                "isDpEmi": false,
                "minDpRange": null,
                "maxDpRange": null,
                "downPaymentUnit": null,
                "issuerId": null,
                "issuerName": null
            }
        ],
        "skusDetail": null,
        "failureReason": "Offer Validated Successfully",
        "failureReasonsBreakup": [
            {
                "offerKey": "title@xsSMQwiE5wcq",
                "failureCode": "ERR6014"
            }
        ],
        "autoApply": true,
        "isSkuOffer": false
    },
    "traceId": "59bd685f-2923-459c-ab06-5edaf8e0ee50"
}

With autoApply=false

Sample request

{
    "amount": 300,
    "autoApply": false,
    "offerKeys": ["TestOffer@fY6HdoP7da8L"],
    "paymentDetail": {
        "cardNumber": 1234567890123456,
        "cardToken": null,
        "cardTokenType": null,
        "category": "CREDITCARD",
        "paymentCode": "CC",
        "vpa": null
    },
    "paymentId": 11111135,
    "platformId": 1,
    "userDetail": {
        "email": "string",
        "phoneNo": "string",
        "userToken": "sds"
    }
}

Sample response

{
    "code": "200",
    "message": "Offer Validated Successfully",
    "status": 1,
    "result": {
        "flagToFail": false,
        "paymentId": 11111135,
        "clientId": 42693,
        "mid": 180012,
        "amount": 300,
        "downPaymentAmount": null,
        "emiAmount": null,
        "paymentCode": "CC",
        "category": "CREDITCARD",
        "isValid": true,
        "offerDiscount": {
            "offerKey": "TestOffer@fY6HdoP7da8L",
            "offerType": "INSTANT",
            "discount": 100.00,
            "discountedAmount": 200.00,
            "discountType": "ABSOLUTE"
        },
        "offerDetail": {
            "offerId": 66057,
            "offerKey": "TestOffer@fY6HdoP7da8L",
            "anchorOfferKey": null,
            "offerType": "INSTANT",
            "offerCategory": null,
            "title": "TestOffer",
            "description": "offer",
            "validFrom": "2024-10-14 00:00:00",
            "validTo": "2024-11-30 23:59:00",
            "tnc": "tnc",
            "tncLink": null,
            "discountType": "ABSOLUTE",
            "offerPercentage": null,
            "maxDiscountPerTxn": 100.00,
            "minTxnAmount": 101.00,
            "maxTxnAmount": 111111.00,
            "minRangeDiscount": null,
            "maxRangeDiscount": null,
            "status": "ACTIVE",
            "isNce": false,
            "disallowTransactionInvalidOffer": null,
            "isSkuOffer": false,
            "isSubventedOffer": false,
            "isBaseOffer": false,
            "amount": 300,
            "discount": 100.00,
            "discountedAmount": 200.00,
            "isValid": true,
            "failureReason": "Offer Validated Successfully",
            "recordType": "OFFER",
            "isGstSubvented": false,
            "isCohortOffer": false,
            "isDpEmi": false,
            "minDpRange": null,
            "maxDpRange": null,
            "downPaymentUnit": null,
            "issuerId": null,
            "issuerName": null
        },
        "totalDiscountDetail": {
            "totalCashbackDiscount": 0,
            "totalInstantDiscount": 100.00,
            "totalDiscountedAmount": 200.00
        },
        "offers": [
            {
                "offerId": 66057,
                "offerKey": "TestOffer@fY6HdoP7da8L",
                "anchorOfferKey": null,
                "offerType": "INSTANT",
                "offerCategory": null,
                "title": "TestOffer",
                "description": "offer",
                "validFrom": "2024-10-14 00:00:00",
                "validTo": "2024-11-30 23:59:00",
                "tnc": "tnc",
                "tncLink": null,
                "discountType": "ABSOLUTE",
                "offerPercentage": null,
                "maxDiscountPerTxn": 100.00,
                "minTxnAmount": 101.00,
                "maxTxnAmount": 111111.00,
                "minRangeDiscount": null,
                "maxRangeDiscount": null,
                "status": "ACTIVE",
                "isNce": false,
                "disallowTransactionInvalidOffer": null,
                "isSkuOffer": false,
                "isSubventedOffer": false,
                "isBaseOffer": false,
                "amount": 300,
                "discount": 100.00,
                "discountedAmount": 200.00,
                "isValid": true,
                "failureReason": "Offer Validated Successfully",
                "recordType": "OFFER",
                "isGstSubvented": false,
                "isCohortOffer": false,
                "isDpEmi": false,
                "minDpRange": null,
                "maxDpRange": null,
                "downPaymentUnit": null,
                "issuerId": null,
                "issuerName": null
            }
        ],
        "skusDetail": null,
        "failureReason": "Offer Validated Successfully",
        "failureReasonsBreakup": [],
        "autoApply": false,
        "isSkuOffer": false
    },
    "traceId": "9bfb1312-d154-4160-acc6-415b0c78c974"
}

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"
}

Sample request and response for SKU-based offers

With autoApply=true

Sample request

{
    "amount": 300,
    "autoApply": false,
    "offerKeys": [],
    "paymentDetail": {
        "cardNumber": 1234567890123456,
        "cardToken": null,
        "cardTokenType": null,
        "category": "CREDITCARD",
        "paymentCode": "CC",
        "vpa": null
    },
    "paymentId": 11111135,
    "platformId": 1,
    "userDetail": {
        "email": "string",
        "phoneNo": "string",
        "userToken": "sds"
    },
    "skusDetail": {
        "skus": [
            {
                "skuCategory": "sku_only",
                "skuAmount": 300,
                "quantity": 1,
                "autoApply": true,
                "skuId": "sampleProductId",
                "offerKeys": []
            }
        ]
    }
}

Sample response

{
    "code": "200",
    "message": "Offer Validated Successfully",
    "status": 1,
    "result": {
        "flagToFail": false,
        "paymentId": 11111135,
        "clientId": 42693,
        "mid": 180012,
        "amount": null,
        "downPaymentAmount": null,
        "emiAmount": null,
        "paymentCode": "CC",
        "category": "CREDITCARD",
        "isValid": false,
        "offerDiscount": null,
        "offerDetail": null,
        "totalDiscountDetail": null,
        "offers": null,
        "skusDetail": {
            "skusDiscountDetail": {
                "totalCashbackDiscount": 0,
                "totalInstantDiscount": 50.00,
                "totalDiscountedAmount": 250.00
            },
            "skus": [
                {
                    "skuId": "sampleProductId",
                    "skuCategory": "sku_only",
                    "skuName": "sampleProductName",
                    "quantity": 1,
                    "skuAmount": 300,
                    "isValid": true,
                    "discountDetail": {
                        "offerKey": "hellosku@rFTxczzbDmj6",
                        "offerType": "INSTANT",
                        "discount": 50.00,
                        "discountedAmount": 250.00,
                        "discountType": "ABSOLUTE"
                    },
                    "skuTotalDiscountDetail": {
                        "totalCashbackDiscount": 0,
                        "totalInstantDiscount": 50.00,
                        "totalDiscountedAmount": 250.00
                    },
                    "offerDetail": {
                        "offerId": 66067,
                        "offerKey": "hellosku@rFTxczzbDmj6",
                        "anchorOfferKey": null,
                        "offerType": "INSTANT",
                        "offerCategory": null,
                        "title": "hello sku",
                        "description": "qwe4",
                        "validFrom": "2024-10-15 00:00:00",
                        "validTo": "2024-10-16 23:59:59",
                        "tnc": "123e",
                        "tncLink": null,
                        "discountType": "ABSOLUTE",
                        "offerPercentage": null,
                        "maxDiscountPerTxn": 50.00,
                        "minTxnAmount": 11.00,
                        "maxTxnAmount": 1000000.00,
                        "minRangeDiscount": null,
                        "maxRangeDiscount": null,
                        "status": "ACTIVE",
                        "isNce": false,
                        "disallowTransactionInvalidOffer": null,
                        "isSkuOffer": true,
                        "isSubventedOffer": false,
                        "isBaseOffer": false,
                        "amount": 300,
                        "discount": 50.00,
                        "discountedAmount": 250.00,
                        "isValid": true,
                        "failureReason": "Offer Validated Successfully",
                        "recordType": "OFFER",
                        "isGstSubvented": false,
                        "isCohortOffer": false,
                        "isDpEmi": false,
                        "minDpRange": null,
                        "maxDpRange": null,
                        "downPaymentUnit": null,
                        "issuerId": null,
                        "issuerName": null
                    },
                    "offers": [
                        {
                            "offerId": 66067,
                            "offerKey": "hellosku@rFTxczzbDmj6",
                            "anchorOfferKey": null,
                            "offerType": "INSTANT",
                            "offerCategory": null,
                            "title": "hello sku",
                            "description": "qwe4",
                            "validFrom": "2024-10-15 00:00:00",
                            "validTo": "2024-10-16 23:59:59",
                            "tnc": "123e",
                            "tncLink": null,
                            "discountType": "ABSOLUTE",
                            "offerPercentage": null,
                            "maxDiscountPerTxn": 50.00,
                            "minTxnAmount": 11.00,
                            "maxTxnAmount": 1000000.00,
                            "minRangeDiscount": null,
                            "maxRangeDiscount": null,
                            "status": "ACTIVE",
                            "isNce": false,
                            "disallowTransactionInvalidOffer": null,
                            "isSkuOffer": true,
                            "isSubventedOffer": false,
                            "isBaseOffer": false,
                            "amount": 300,
                            "discount": 50.00,
                            "discountedAmount": 250.00,
                            "isValid": true,
                            "failureReason": "Offer Validated Successfully",
                            "recordType": "OFFER",
                            "isGstSubvented": false,
                            "isCohortOffer": false,
                            "isDpEmi": false,
                            "minDpRange": null,
                            "maxDpRange": null,
                            "downPaymentUnit": null,
                            "issuerId": null,
                            "issuerName": null
                        }
                    ],
                    "statusMessage": "Offer Validated Successfully",
                    "autoApply": true
                }
            ]
        },
        "failureReason": null,
        "failureReasonsBreakup": [],
        "autoApply": false,
        "isSkuOffer": false
    },
    "traceId": "d2851fa2-cf37-4669-b316-41b7143282f4"
}

With autoApply=false

Sample request

{
    "amount": 300,
    "autoApply": false,
    "offerKeys": [],
    "paymentDetail": {
        "cardNumber": 1234567890123456,
        "cardToken": null,
        "cardTokenType": null,
        "category": "CREDITCARD",
        "paymentCode": "CC",
        "vpa": null
    },
    "paymentId": 11111135,
    "platformId": 1,
    "userDetail": {
        "email": "string",
        "phoneNo": "string",
        "userToken": "sds"
    },
    "skusDetail": {
        "skus": [
            {
                "skuCategory": "sku_only",
                "skuAmount": 300,
                "quantity": 1,
                "autoApply": false,
                "skuId": "sampleProductId",
                "offerKeys": [
                    "hellosku@rFTxczzbDmj6"
                ]
            }
        ]
    }
}

Sample response

{
    "code": "200",
    "message": "Offer Validated Successfully",
    "status": 1,
    "result": {
        "flagToFail": false,
        "paymentId": 11111135,
        "clientId": 42693,
        "mid": 180012,
        "amount": null,
        "downPaymentAmount": null,
        "emiAmount": null,
        "paymentCode": "CC",
        "category": "CREDITCARD",
        "isValid": false,
        "offerDiscount": null,
        "offerDetail": null,
        "totalDiscountDetail": null,
        "offers": null,
        "skusDetail": {
            "skusDiscountDetail": {
                "totalCashbackDiscount": 0,
                "totalInstantDiscount": 50.00,
                "totalDiscountedAmount": 250.00
            },
            "skus": [
                {
                    "skuId": "sampleProductId",
                    "skuCategory": "sku_only",
                    "skuName": "sampleProductName",
                    "quantity": 1,
                    "skuAmount": 300,
                    "isValid": true,
                    "discountDetail": {
                        "offerKey": "hellosku@rFTxczzbDmj6",
                        "offerType": "INSTANT",
                        "discount": 50.00,
                        "discountedAmount": 250.00,
                        "discountType": "ABSOLUTE"
                    },
                    "skuTotalDiscountDetail": {
                        "totalCashbackDiscount": 0,
                        "totalInstantDiscount": 50.00,
                        "totalDiscountedAmount": 250.00
                    },
                    "offerDetail": {
                        "offerId": 66067,
                        "offerKey": "hellosku@rFTxczzbDmj6",
                        "anchorOfferKey": null,
                        "offerType": "INSTANT",
                        "offerCategory": null,
                        "title": "hello sku",
                        "description": "qwe4",
                        "validFrom": "2024-10-15 00:00:00",
                        "validTo": "2024-10-16 23:59:59",
                        "tnc": "123e",
                        "tncLink": null,
                        "discountType": "ABSOLUTE",
                        "offerPercentage": null,
                        "maxDiscountPerTxn": 50.00,
                        "minTxnAmount": 11.00,
                        "maxTxnAmount": 1000000.00,
                        "minRangeDiscount": null,
                        "maxRangeDiscount": null,
                        "status": "ACTIVE",
                        "isNce": false,
                        "disallowTransactionInvalidOffer": null,
                        "isSkuOffer": true,
                        "isSubventedOffer": false,
                        "isBaseOffer": false,
                        "amount": 300,
                        "discount": 50.00,
                        "discountedAmount": 250.00,
                        "isValid": true,
                        "failureReason": "Offer Validated Successfully",
                        "recordType": "OFFER",
                        "isGstSubvented": false,
                        "isCohortOffer": false,
                        "isDpEmi": false,
                        "minDpRange": null,
                        "maxDpRange": null,
                        "downPaymentUnit": null,
                        "issuerId": null,
                        "issuerName": null
                    },
                    "offers": [
                        {
                            "offerId": 66067,
                            "offerKey": "hellosku@rFTxczzbDmj6",
                            "anchorOfferKey": null,
                            "offerType": "INSTANT",
                            "offerCategory": null,
                            "title": "hello sku",
                            "description": "qwe4",
                            "validFrom": "2024-10-15 00:00:00",
                            "validTo": "2024-10-16 23:59:59",
                            "tnc": "123e",
                            "tncLink": null,
                            "discountType": "ABSOLUTE",
                            "offerPercentage": null,
                            "maxDiscountPerTxn": 50.00,
                            "minTxnAmount": 11.00,
                            "maxTxnAmount": 1000000.00,
                            "minRangeDiscount": null,
                            "maxRangeDiscount": null,
                            "status": "ACTIVE",
                            "isNce": false,
                            "disallowTransactionInvalidOffer": null,
                            "isSkuOffer": true,
                            "isSubventedOffer": false,
                            "isBaseOffer": false,
                            "amount": 300,
                            "discount": 50.00,
                            "discountedAmount": 250.00,
                            "isValid": true,
                            "failureReason": "Offer Validated Successfully",
                            "recordType": "OFFER",
                            "isGstSubvented": false,
                            "isCohortOffer": false,
                            "isDpEmi": false,
                            "minDpRange": null,
                            "maxDpRange": null,
                            "downPaymentUnit": null,
                            "issuerId": null,
                            "issuerName": null
                        }
                    ],
                    "statusMessage": "Offer Validated Successfully",
                    "autoApply": false
                }
            ]
        },
        "failureReason": null,
        "failureReasonsBreakup": [],
        "autoApply": false,
        "isSkuOffer": false
    },
    "traceId": "c80dde13-cfcb-473a-b200-b3be788ac7f2"
}

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"
}

Invalid request

{
    "code": "400",
    "message": "Invalid Request",
    "status": 0,
    "exceptionId": "252e1602-2a9a-449a-8f17-f55fe1f0949a"
}

Offer key is mandatory when autoApply=false

{
    "code": "400",
    "message": "Offer key is mandatory when offer is not auto applied",
    "status": 0,
    "exceptionId": "0e2012e76b4347f48d58808bf3c39122",
    "traceId": "4baa1329-b3c5-479c-b98e-b3f2a99f0158"
}

Sample request with 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
anchorOfferKey	`Boolean` This field contains the flag to indicate if it an anchor offer key.
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
isSkuOffer	`Boolean`This field contains flag to indicate if it is an SKU-based offer.	true
isSubventedOffer	`Boolean`This field contains flag to indicate if it is a subvented offer.	false
isBaseOffer	`Boolean`This field contains flag to indicate if it a base offer.	false
amount	`Float`This field contains the offer amount.	300
discount	`Float` This field contains the offer amount.
discountedAmount	`Float` This field contains the discounted offer amount.	true
isValid	`Boolean`This field contains flag to indicate if it is a valid offer.
failureReason	`String`This field contains failure reason.	Offer Validated Successfully
recordType	`String`This field contains the record type.	OFFER
isGstSubvented	`Boolean`This field contains flag to indicate if it is a GST subvented.	false
isCohortOffer	`Boolean`This field contains flag to indicate if it is a cohort offer.	false
isDpEmi	`Boolean`This field contains flag to indicate if it is a downpayment EMI.	false
minDpRange	`Float` This field contains the minimum downpayment amount.
maxDpRange	`Float` This field contains the maximum downpayment amount.
downPaymentUnit	`Float` This field contains the downpayment unit.
issuerId	`String`This field contains issuer ID.
issuerName	`String`This field contains issuer name.

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

"offerDetail" {
            "offerId": 66057,
            "offerKey": "TestOffer@fY6HdoP7da8L",
            "anchorOfferKey": null,
            "offerType": "INSTANT",
            "offerCategory": null,
            "title": "TestOffer",
            "description": "offer",
            "validFrom": "2024-10-14 00:00:00",
            "validTo": "2024-11-30 23:59:00",
            "tnc": "tnc",
            "tncLink": null,
            "discountType": "ABSOLUTE",
            "offerPercentage": null,
            "maxDiscountPerTxn": 100.00,
            "minTxnAmount": 101.00,
            "maxTxnAmount": 111111.00,
            "minRangeDiscount": null,
            "maxRangeDiscount": null,
            "status": "ACTIVE",
            "isNce": false,
            "disallowTransactionInvalidOffer": null,
            "isSkuOffer": false,
            "isSubventedOffer": false,
            "isBaseOffer": false,
            "amount": 300,
            "discount": 100.00,
            "discountedAmount": 200.00,
            "isValid": true,
            "failureReason": "Offer Validated Successfully",
            "recordType": "OFFER",
            "isGstSubvented": false,
            "isCohortOffer": false,
            "isDpEmi": false,
            "minDpRange": null,
            "maxDpRange": null,
            "downPaymentUnit": null,
            "issuerId": null,
            "issuerName": null
        }

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.

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 and response for normal transactional offers

With autoApply=true

With autoApply=false

Failure scenarios

Sample request and response for SKU-based offers

With autoApply=true

With autoApply=false

Failure scenarios

Sample request with Using a saved card

Response parameters

result parameter JSON Details

offerDiscount Field JSON Details

offerDetail Field JSON Details

skusDetail Parameter Description

📘
Note: