JWT Validation

Owned by Nick Simone
Last updated: Jul 02, 2018 by Jacob Gries (Unlicensed)
5 min read

Centinel API will respond back with all requests in JWT form when able to.

Required Fields

Please note that each Claim key is case sensitive.

ClaimDescription
audMerchant jti Id - This is the 'jti' field from your request JWT echoed back. This field allows you to match up your request JWT with Cardinals response JWT.
jtiJWT Id - A unique identifier for this response JWT. This value is generated by Cardinal.
iatIssued At Time - This is a timestamp of when the JWT was created.
issIssuer - The request JWT's iss field echoed back.
ConsumerSessionIdThe unique session Id for the current user.
PayloadThe response object for your request. This field will contain any actual state information on the transaction. This is the decoded data object that is passed into the payments.validated event as the first argument.

JWT Payload Example

Below is an example of the JSON content of a basic response JWT Payload where we are passing an object within the Payload claim:

Raw JWT Sample
{
    "iss": "56560a358b946e0c8452365ds",
    "iat": 1471014492,
    "exp": 1471021692,
    "jti": "8af34811-f97d-495a-ad19-ec2f68004f28",
    "ConsumerSessionId": "0e1ae450-df2b-4872-94f7-f129a2ddab18",
    "Payload": {
        "Validated": true,
        "Payment": {
            "Type": "CCA",
            "ExtendedData": {
                "CAVV": "AAABAWFlmQAAAABjRWWZEEFgFz+=",
                "ECIFlag": "05",
                "PAResStatus": "Y",
                "SignatureVerification": "Y",
                "XID": "MHEyQjFRQkttemdpaFlRdHowWTA=",
                "Enrolled": "Y"
            }
        },
        "ActionCode": "SUCCESS",
        "ErrorNumber": 0,
        "ErrorDescription": "Success"
    }
}

Below is an example of the JSON content of a basic response JWT Payload where we are passing a string within the Payload claim. This would occur when the request JWT included a ObjectifyPayload flag set to false:

Stringified JWT Sample
}
    "iss": "56560a358b946e0c8452365ds",
    "iat": 1471015342,
    "exp": 1471022542,
    "jti": "55ebfa2a-665f-4d6b-81ea-37d1d4d12d9e",
    "ConsumerSessionId": "fb3a97a3-0344-4d3d-93ea-6482d866ec97",
    "Payload": "{\"Validated\":true,\"Payment\":{\"Type\":\"CCA\",\"ExtendedData\":{\"CAVV\":\"AAABAWFlmQAAAABjRWWZEEFgFz+\\u003d\",\"ECIFlag\":\"05\",\"PAResStatus\":\"Y\",\"SignatureVerification\":\"Y\",\"XID\":\"MFpjUVpwb0FXcHdwMWJBdldwNDA\\u003d\",\"Enrolled\":\"Y\"}},\"ActionCode\":\"SUCCESS\",\"ErrorNumber\":0,\"ErrorDescription\":\"Success\"}"
}

Code Samples

Below are a code samples of how you can verify a JWT in a few languages

We do not recommend using these samples unmodified in a production environment. They are intended as examples only.

Validating a Response JWT in .NET

We recommend using an existing third party library to assist you in generating and validating JWTs. Some of our recommendations are:

JSON Web Token Handler - www.nuget.org

JWT - GitHub.com

The JWT.io website contains a list of additional approved libraries, with their feature sets. Check it out here.

public string DecodeAndValidateResponseJwt(string responseJwt)
    {
        string jsonPayload = string.Empty;
        try
        {
            var apiKey = ConfigurationManager.AppSettings["APIKey"];

            jsonPayload = JWT.JsonWebToken.Decode(responseJwt, apiKey);
            Console.WriteLine(jsonPayload);
        }
        catch (JWT.SignatureVerificationException)
        {
            Console.WriteLine("Signature validation failed! JWT is not valid!");
        }

        return jsonPayload;
    }

Validating a Response JWT in Java

We recommend using an existing third party library to assist you in generating and validating JWTs. The JWT.io website contains a list of approved libraries, with their feature sets. Check it out here.

    // The jwt argument is the Cardinal response jwt handed back to the payments.validated event. 
    // This value is NOT the request jwt generated by the merchant and sent to Cardinal.
    public static boolean validateJwt(String jwt) {
        
        try{
            // The API Key used here to validate the Cardinal response is the same 
            // API Key you use to generate your request jwt.
            Claims claims = (Claims) Jwts.parser()
                .setSigningKey(apiKey.getBytes())
                .parse(jwt)
                .getBody();
                
            System.out.println("Signature Verified");
                        
            return true;
            
        } catch(SignatureException se) {
            System.out.println("Signature Validation Failed! JWT is not valid.");
        } catch(Exception ex){
        	System.out.println("General Error: " + ex.getMessage());
        }
        
        return false;
    }

Validating a Response JWT in PHP

We recommend using an existing third party library to assist you in generating and validating JWTs. The JWT.io website contains a list of approved libraries, with their feature sets. Check it out here.

<?php

    /* 
    composer.json Example:
    {
        "require": {
            "firebase/php-jwt": "^4.0"
        }
    }
    */

    require "vendor/autoload.php"; // Autoload.php generated by Composer
    
    use Firebase\JWT\JWT;

    $GLOBALS['ApiKey'] = '[INSERT_API_KEY_HERE]';
    $GLOBALS['ApiId'] = '[INSERT_API_KEY_ID_HERE]';
    $GLOBALS['OrgUnitId'] = '[INSERT_ORG_UNIT_ID_HERE]';

    function validateJwt($jwt) {
        // This will validate JWT Requests or Responses from Cardinal.
        try{
            // Validate the JWT by virtue of successful decoding
            $decoded = JWT::decode($jwt, $GLOBALS['ApiKey'], array('HS256'));
        } catch (Exception $e) {
            echo "Exception in validateJwt: ", $e->getMessage(), "\n";
        }
        return false;
    }
?>