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.
Excerpt | ||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Required ClaimsPlease note that each claim key is case sensitive.
Optional ClaimsThe following claims are available for use but are not currently required for a valid JWT:
Other ClaimsThe following claims are conditionally required when doing some transactional flows:
JWT Payload ExampleBelow 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.
Warning |
---|
We do not recommend using these samples unmodified in a production environment. They are intended as examples only. |
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.
Info | ||
---|---|---|
| ||
When using nuget you can grab the JWT library by installing the package 'JsonWebTokens'. It has been reported that some versions of .Net will need to install an additional dependency 'System.Security.Cryptography.Primitives' for 'JsonWebTokens' to work properly. |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
// This sample code was written using the JSON Web Token Handler library. using System.Configuration; using System.Web.Mvc; using CardinalCruiseDemoSite.Helpers; using CardinalCruiseDemoSite.Models.View; namespace CardinalCruiseDemoSite.Controllers { public class HomeController : Controller { private readonly JwtHelper _jwtHelper = new JwtHelper(); public ActionResult Index() { var apiKey = ConfigurationManager.AppSettings["APIKey"]; var apiIdentifier = ConfigurationManager.AppSettings["APIIdentifier"]; var orgUnitId = ConfigurationManager.AppSettings["OrgUnitId"]; var jwt = _jwtHelper.GenerateJwt(apiKey, apiIdentifier, orgUnitId); return View(new CardinalCruiseViewModel {JWT = jwt}); } } } |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
namespace CardinalCruiseDemoSite.Models.View { public class CardinalCruiseViewModel { public string JWT { get; set; } } } |
This is an example of a JWT object class.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
using System; using System.Collections.Generic; using CardinalCruiseDemoSite.Models; using JWT; namespace CardinalCruiseDemoSite.Helpers { public class JwtHelper { public string GenerateJwt(string apiKey, string apiIdentifier, string orgUnitId) { var payload = new Dictionary<string, object> { {"exp", DateTime.UtcNow.AddDays(365).ToUnixTime()}, {"iat", DateTime.UtcNow.ToUnixTime()}, {"jti", Guid.NewGuid()}, {"iss", apiIdentifier}, {"OrgUnitId", orgUnitId}, { "Payload", new Order { OrderDetails = new OrderDetails { OrderNumber = Guid.NewGuid().ToString() } } } }; return JsonWebToken.Encode(payload, apiKey, JwtHashAlgorithm.HS256); } } } |
Info |
---|
It is important that you generate the JWT expiration using UNIX time. We recommend using a library such as NodaTime from NodaTime.org to help with this. If you are unable to use a third party library, here is a helper function you may use (this is used in the example above): |
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
using System; namespace CardinalCruiseDemoSite.Helpers { public static class DateTimeHelper { public static long ToUnixTime(this DateTime date) { var epoch = new DateTime(1970, 1, 1, 0, 0, 0, DateTimeKind.Utc); return Convert.ToInt64((date - epoch).TotalSeconds); } } } |
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.
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
// This sample code was written using the Java JWT // library (https://github.com/jwtk/jjwt) found at JWT.io import io.jsonwebtoken.JwtBuilder; import io.jsonwebtoken.Jwts; import io.jsonwebtoken.SignatureAlgorithm; import java.security.Key; import java.util.Date; import java.util.UUID; import javax.crypto.spec.SecretKeySpec; public class generateJWT { public static String apiKey = ""; public static String apiIdentifier = ""; public static String orgUnitId = ""; // Sample method to construct a JWT public static String createJWT(String jwtId, long ttlMillis, Order orderObject) { // The JWT signature algorithm we will be using to sign the token SignatureAlgorithm signatureAlgorithm = SignatureAlgorithm.HS256; long nowMillis = System.currentTimeMillis(); Date now = new Date(nowMillis); // We will sign our JWT with our API Key byte[] apiKeySecretBytes = apiKey.getBytes(); Key signingKey = new SecretKeySpec(apiKeySecretBytes, signatureAlgorithm.getJcaName()); // Let's set the JWT Claims JwtBuilder builder = Jwts.builder() .setId(jwtId) .setIssuedAt(now) .setIssuer(apiIdentifier) .claim("OrgUnitId", orgUnitId) .claim("Payload", orderObject) .signWith(signatureAlgorithm, signingKey); // Add the expiration or TTL (Time To Live) for this JWT if (ttlMillis > 0) { long expMillis = nowMillis + ttlMillis; Date exp = new Date(expMillis); builder.setExpiration(exp); } // Builds the JWT and serializes it to a compact, URL-safe string return builder.compact(); } } |
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.
Code Block | ||||
---|---|---|---|---|
| ||||
<?php /* composer.json Example: { "require": { "lcobucci/jwt": "3.1.0" // Note: Requires PHP 7 } } */ require "vendor/autoload.php"; // Autoload.php is generated by Composer use Lcobucci\JWT\Builder; use Lcobucci\JWT\Signer\Hmac\Sha256; $GLOBALS['ApiKey'] = '[INSERT_API_KEY_HERE]'; $GLOBALS['ApiId'] = '[INSERT_API_KEY_ID_HERE]'; $GLOBALS['OrgUnitId'] = '[INSERT_ORG_UNIT_ID_HERE]'; $_SESSION['TransactionId'] = uniqid(); $_SESSION['Order'] = array( "OrderDetails" => array( "OrderNumber" => 'ORDER-' . strval(mt_rand(1000, 10000)), "Amount" => '1500', "CurrencyCode" => '840' ) ); function generateJwt($orderTransactionId, $orderObj){ $currentTime = time(); $expireTime = 3600; // expiration in seconds - this equals 1hr $token = (new Builder())->setIssuer($GLOBALS['ApiId']) // API Key Identifier (iss claim) ->setId($orderTransactionId, true) // The Transaction Id (jti claim) ->setIssuedAt($currentTime) // Configures the time that the token was issued (iat claim) ->setExpiration($currentTime + $expireTime) // Configures the expiration time of the token (exp claim) ->set('OrgUnitId', $GLOBALS['OrgUnitId']) // Configures a new claim, called "OrgUnitId" ->set('Payload', $_SESSION['Order']) // Configures a new claim, called "Payload", containing the OrderDetails ->set('ObjectifyPayload', true) ->sign(new Sha256(), $GLOBALS['ApiKey']) // Sign with API Key ->getToken(); // Retrieves the generated token return $token; // The JWT String } echo generateJwt($_SESSION['TransactionId'], $_SESSION['Order']); ?> |