Provision Alt ID API

The Provision Alt ID API is used to provision Alt ID from PayU, but process transaction outside PayU. This section describes the request parameters with sample request and response.

HTTP Method: POST

Environment

Request Headers

The request header contains the following fields:

FieldDescriptionExample
Date
mandatory
The date and time should be in the GMT time conversion(not the IST). For example, current time in India is 18:00:00 IST, the time in the date header should be 12:30:00 GMT.Thu, 17 Feb 2022 08:17:59 GMT
Digest
mandatory
Base 64 encode of (sha256 hash of the JSON data (post to server).vpGay5D/dmfoDupALPplYGucJAln9gS29g5Orn+8TC0=
Authorization
mandatory
This field is in the following format:
hmac username="smsplus", algorithm="hmac-sha256", headers="date digest", signature="CkGfgbho69uTMMOGU0mHWf+1CUAlIp3AjvsON9n9/E4="
Where the above format includes the following:
- username: The merchant key of the merchant.
- algorithm: This must have the value as hmac-sha256 that is used for this API
- headers: This must have the value as date digest
- signature: This must contain the hmacsha256 of (signing_string, merchant_secret), where:
- signing_string: This is in the "Date"+"\n"+"Digest" format. Here, the Date and Digest is the same values in the fields listed in this table For example, "Thu, 17 Feb 2022 08:17:59 GMT""\n"+“vpGay5D/dmfoDupALPplYGucJAln9gS29g5Orn+8TC0=“
- merchant_secret: The merchant Salt of the merchant. For more information on getting the merchant Salt, refer to Generate Merchant Key and Salt on PayU Dashboard
 hmac username="smsplus", algorithm="hmac-sha256", headers="date digest", signature="zGmP5Zeqm1pxNa+d68DWfQFXhxoqf3st353SkYvX8HI="
platformId
mandatory
This field contains the platform ID and include the value as 1.1

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);
    }
}

Request Parameters

ParameterDescriptionExample
clientReferenceId
optional
The alphanumeric value to track the request.DKSAI80033U2BRRE90FD0SDJAOSA
cardNumber
mandatory
The card number entered by the customer.XXXXXXXXXXXX3669
nameOnCard
optional
The name on card entered by the customer.Ashish K
cardType
optional
The type card used by the customer.AMEX
expiryMonth
mandatory
The expiry date of card entered by the customer.12
expiryYear
mandatory
The expiry year of the card entered by the customer.26
cvv
mandatory
The CVV or secret code found behind the cardentered by the customer.000
mail
optional
The mail ID of the customer.[email protected]
amount
mandatory
The amount of the transaction.100
authenticationCode
conditional
The authentication code for the transaction.
Note: This parameter is required for RUPAY cards.
 

Sample Request

curl --location --request POST 'https://apitest.payu.in/card/altid' \
--header 'Content-Type: application/json' \
--header 'date: Fri, 12 Jan 2024 10:13:08 GMT' \
--header 'digest: n6XDOH1fAUrD+WC47SFsa+mNxmm1+yTrUAupmxbYMoc=' \
--header 'authorization: hmac username="DGy1hY", algorithm="hmac-sha256", headers="date digest", signature="FBp5QsOIxBzxyDnRXPCt76htkdm5ijc4nm/Hvyvaw/s="' \
--data-raw '{
    "clientReferenceId": null,
    "cardNumber": "5299920970259709",
    "nameOnCard": "Jagadesh Reddy",
    "cardType": "MAST",
    "expiryMonth": "06",
    "expiryYear": "2024",
    "cvv": "000",
    "mail": "[email protected]",
    "amount": "100",
    "authenticationCode": null
}'

Response Parameters

ParameterValue
statusCodeTK0000, INV001, ONB001, TK0002
status0(failure), 1(success)
clientReferenceIdSame id sent in request
cryptogramCryptogram details
altIdTokenALT ID
expiryMonthExpiry month of AltId Token
expiryYearExpiry year of AltId Token
las4Last 4 digits of the card
parPayment Account Reference(Unique Id of the card)
msgSuccess or failure message
errorDescError description
errorMsgFromNetworkMessage received from the network

Sample Response

Success Scenario

{
    "statusCode": "EA01",
    "status": 1,
    "clientReferenceId": "339c6c458ac3161da90839",
    "tokenReferenceId": "018b90aa-b9c5-41c0-8528-71dd22b6b65e",
    "cryptogram": "IjDso7oA5xFBdiOd/m035meW5UpImrSRAXWMe7406m0=",
    "altInfo": {
        "altIdToken": "3612143521818338",
        "expiryMonth": "09",
        "expiryYear": "2026",
        "last4": "6622"
    },
    "msg": "AltID created successful",
    "par": "799F3ED865F5965CC760A32682BA8A80F19E99ECB3F7F03574C14F5B6C3EB2C1"
}

Failure Scenarios

  • Invalid card number
{
    "statusCode": "EA02",
    "errorDesc": "CardNo is Invalid. Please check and initiate again",
    "status": 0
}
  • Invalid expiry month of card
{
    "statusCode": "EA02",
    "errorDesc": "Expiry year is Invalid. Please check and initiate again",
    "status": 0
}
  • Invalid CVV specified for card
{
    "statusCode": "EA02",
    "errorDesc": "CVV is Invalid. Please check and initiate again",
    "status": 0
}
  • Internal error
{
    "statusCode": "EA03",
    "errorDesc": "Technical error. Please try again",
    "status": 0,
    "clientReferenceId": "6751c7ca1365415b6b0a"
}
  • Invalid Acquired Merchant ID
{
    "statusCode": "EA04",
    "errorDesc": "Invalid merchant ID configuration. Please reachout to PayU support team",
    "status": 0,
    "clientReferenceId": "6b831fb451717be74130"
}
  • Card Network Failure

    {
        "statusCode": "EA05",
        "errorDesc": "Card network seems to be down. Please retry after some time",
        "status": 0,
        "clientReferenceId": "6700ac2393ec5091af75"
    }
    
  • Invalid Authentication Code (RUPAY)

    {
        "statusCode": "EA06",
        "errorDesc": "Invalid auth code configuration. Please raise this to PayU support team",
        "status": 0,
        "clientReferenceId": "6bf002e42595130f3b5d"
    }
    
  • Invalid AcquirerInstance id Code (MASTER)

    {
        "statusCode": "EA07",
        "errorDesc": "Invalid Acq ID Code configuration. Please raise this to PayU support team",
        "status": 0,
        "clientReferenceId": "6c3d6d35a5982a3d9637"
    }
    
  • Merchant Not Onboarded(AMEX)

    {
        "statusCode": "EA09",
        "errorDesc": "Invalid merchant ID configuration. Please reach out to PayU support team",
        "status": 0,
        "clientReferenceId": "85096f63e4366f9d199"
    }
    
  • Merchant Invalid Or Merchant AltId is InActive

    {
        "statusCode": "EA10",
        "errorDesc": "The MID is not active. Please raise this to PayU support team",
        "status": 0
    }