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

EnvironmentURL
Productionhttps://apitest.payu.in/card/altid

Request Headers

The request header contains the following fields:


Field

Description

Example

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/dmfoDupA LPplYGucJAln9gS2 9g5Orn+8TC0=

Authorization
mandatory

This field is in the format described in Authorization format.

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

Authorization 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

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

Parameter

Description

Example

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 Ssenarios

  • 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
}
  • Mastercard DPA creation in progress
{
    "statusCode": "EA082",
    "errorDesc": "Mastercard DPA creation in progress. Please retry after 15 mins.",
    "status": 0,
    "clientReferenceId": "befd87386aebf388206",
    "errorMsgFromNetwork": "DPA entity data not found for the given clientId or dpaId in getDpaEntityData request."
}
  • Invalid Acquired Merchant ID Code configuration
{
    "statusCode": "EA07",
    "errorDesc": "Invalid Acq ID Code configuration. Please raise this to PayU support team",
    "status": 0,
    "clientReferenceId": "bf117fe66fa5148e4e5d"
}
  • Invalid expiry month
 
{
    "statusCode": "EA025",
    "errorDesc": "Expiry month is Invalid. Please check and initiate again..",
    "status": 0
}