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

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

integerTe card bin for cards used in the transaction.
This field is mandatory for credit card /debit card offer transaction

category
mandatory

stringThis 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

stringThe 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

StringThis 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

IntegerThis field contains the unique identifier provided by PayU to each merchant.

1

amount

Float This field contains the Offer transaction amount

10000.00

paymentcode

StringThe payment code that is used to identify the particular payment option.

HDFC

category

StringThis 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

StringThis field contains any of the following discount type that was defined:

ABSOLUTE

offerPercentage

FloatThis 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

StringThis field contains any of the following current offer status:

  • DRAFTED
  • DEACTIVEATED
  • PAUSED
  • ACTIVE

ACTIVE

isNce

BooleanThis 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

BooleanThis field contains flag to indicate if it is an SKU-based offer.

true

isSubventedOffer

BooleanThis field contains flag to indicate if it is a subvented offer.

false

isBaseOffer

BooleanThis field contains flag to indicate if it a base offer.

false

amount

FloatThis 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

BooleanThis field contains flag to indicate if it is a valid offer.

failureReason

StringThis field contains failure reason.

Offer Validated Successfully

recordType

StringThis field contains the record type.

OFFER

isGstSubvented

BooleanThis field contains flag to indicate if it is a GST subvented.

false

isCohortOffer

BooleanThis field contains flag to indicate if it is a cohort offer.

false

isDpEmi

BooleanThis 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

StringThis field contains issuer ID.

issuerName

StringThis 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

StringThe offer keys to filter at SKU-level is specified in this field.