JWT Creation

Cardinal Cruise utilizes a JWT to handle authentication and to assist in passing secure data between you and Cardinal. The JWT is a JWS with the signature using a SHA-256 HMAC hash algorithm. The JWT must be created server-side and sent to the front end to be injected into the JavaScript initialization code. Creating a JWT client-side is not a valid activation option. Each order should have a uniquely generated JWT associated with it.

Learn more about JWT's.

Helpful JWT external pages:


JWT Fields

A valid generic transaction JWT must contain the below values. Additional fields may be required to complete an integration with some payment brands. Please review the payment brand's documentation for more details on if a payment brand needs additional fields.

Required Claims

Please note that each claim key is case sensitive.

Claim NameDescription
jtiJWT Id - A unique identifier for this JWT. This field should change each time a JWT is generated.
iatIssued At - The epoch time in seconds of when the JWT was generated. This allows us to determine how long a JWT has been around and whether we consider it expired or not.
issIssuer - An identifier of who is issuing the JWT. We use this value to contain the Api Key identifier or name.
OrgUnitId

The merchant SSO OrgUnitId

PayloadThe JSON data object being sent to Cardinal. This object is usually an Order object

Optional Claims

The following claims are available for use but are not currently required for a valid JWT:

Claim NamesDescription
ReferenceIdThis is a merchant supplied identifier that can be used to match up data collected from Cardinal Cruise and Centinel. Centinel can then use data collected to enable rules or enhance the authentication request.
ObjectifyPayloadA boolean flag that indicates how Centinel Api should consume the Payload claim. When set to true, this tells Centinel Api the Payload claim is an object. When set to false, the Payload claim is a stringified object. Some Jwt libraries do not support passing objects as claims, this allows those who only allow strings to use their libraries without customization
expExpiration - The numeric epoch time that the JWT should be consider expired. This value is ignored if its larger than 2 hrs. By default we will not consider any JWT older than 2 hrs.

Other Claims

The following claims are conditionally required when doing some transactional flows:

Claim NameDescriptionFlow Required
ConfirmUrlThe merchant endpoint that will receive the post back from the payment brand that contains the Centinel API response JWT describing the result of redirecting to the payment brand.Redirect

JWT Payload Example

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

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


Code Samples

The below code samples are to provide you with a basic idea on how to generate JWT's within a few languages. 


Generating a Server JWT in .NET

We recommend using an existing third party library to assist you in generating a JWT. The JWT.io website contains a list of libraries with their feature sets. Check it out here. In the below sample we will focus on using this JWT (GitHub.com) library.


This is an example of a JWT object class.

Generating a Server JWT in Java

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

Generating a Server JWT in PHP

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