REST API

Generating a JSON Web Token for a POST Request

Prerequisites

Generate and Base-64 encode the payload of the API request. For sample code, see the SDK for your language.

Generate the Claim Set

Use the following key:value pairs.
Claim Set Elements
Field Name
Description
Example
iat
The date and time of message origin. The date can be in any format for a time zone.
Date formatting as defined by RFC7231: 
http://tools.ietf.org/html/rfc7231#section-7.1.1.1
String gmtDateTime = DateTimeFormatter.RFC_1123_DATE_TIME.format(         ZonedDateTime.now(ZoneId.of("GMT")));
This is a required field.
iat: Thur, 15 June 2017 08:12:31 GMT
Digest
Digest of JSON payload. The digest is Base64-encoded.
The
digest
field should not be passed in the JWT Header for a GET call.
example_payload:
{   "clientReferenceInformation" : {     "code" : "TC50171_3"   },   "orderInformation" : {     "amountDetails" : {       "totalAmount" : "102.21",       "currency" : "USD"     }   } }
SHA256_hash_of_example_payload =
2b4fee10da8c5e1feaad32b014021e079fe4afcf06af223004af944011a7cb65c
# The hash has Base64 encoded Digest header in RFC3230 defined format of "Digest:
BASE64(SHA256_hash_of_example_payload)“
= tP7hDajF4f6q0ysBQCHgef5K/PBq8iMASvlEARp8tl=
Digest: tP7hDajF4f6q0ysBQCHgef5K/PBq8iMASvlEARp8tl=
Code Snippet:
MessageDigest signatureString = MessageDigest.getInstance("SHA-256");byte[] digestBytes = signatureString.digest(messageBody.getBytes());String bluePrint = Base64.getEncoder().encodeToString(digestBytes);
digestAlgorithm
The signature algorithm you are using. For asymmetric keys, use a SHA-256 hash.
The
digestAlgorithm
field should not be passed in the JWT Header for a GET call.
"digestAlgorithm":  SHA-256
Example
{ "iat": "Thur, 15 June 2017 08:12:31 GMT", "digest": "tP7hDajF4f6q0ysBQCHgef5K/PBq8iMASvlEARp8tl=", "digestAlgorithm": "SHA-256" }

Generate the Token Header

Use the following key:value pairs.
Token Header Elements
Field Name
Description
Example
x5c
The
x5c
(X.509 certificate chain) Header Parameter contains the X.509 public key certificate or certificate chain corresponding to the key(.p12) used to digitally sign the token.
This is a required field.
MIICZTCCAc6gAwIBAg…Emj0F35Ew2ek4VezUXnZ/SMLvWEA6DG2sjSFCCuIot3mLJ3lI4AQSQSBSazhQec75Rk=
alg
The signing algorithm used.
This is a required field.
alg: RS256
v-c-merchant-id
Merchant ID assigned in the Business Center.
Required for merchant transactions.
Required for partners sending transactions of behalf of merchants.
v-c-merchant-id: merchant_id
Example
{ "x5c": "MIICZTCCAc6gAwIBAg…Emj0F35Ew2ek4VezUXnZ/SMLvWEA6DG2sjSFCCuIot3mLJ3lI4AQSQSBSazhQec75Rk=", "alg": "RS256", "v-c-merchant-id": "merchant_id" }

Generate the Token Signature

Token Signature Elements
Field Name
Description
Example
JWT Signature
The JWT header and the claim set created in previous steps is Base64-encoded. Join the resulting encoded strings together with a period (.) in between them. In our pseudo code, this joined string is assigned to data.
To get the JWT signature, the data string is signed with RS256 with the private key using the signing algorithm specified in the JWT header. Signature String is then encoded with Base64-encoded before creating final token.
data = base64urlEncode( JWT header ) + “.” + base64urlEncode( Claimset )
signature = RS256Hash( data, private_key ) ;
signature = eyJ2LWMtbWVyY2hhbn…WYQNLMOApxv6-DdcJZK4L9mLRc3gFb1kTFvodNEI6M0GeyoFp-b9PNG32TLQITYfWmZEbTZExgQHXGwwqo

Generate the JSON Web Token

JSON Web Token Elements
Field Name
Description
Example
JWT Token
With All three components
JWT header
,
claim set
, and
Signature
, concatenate the components into a valid JWT authorization token.
JWT token = JWT
header.Claim set.signature
 
Combine the header and payload and signature with periods (.) separating them.
Example:
JWT Token = base64url( JWT header ) + “.” + base64url( Payload ) + “.” + base64url( Signature )
// Sample JWT header
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9
// Sample PayLoad
eyJ1c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYz OTA0NjYwYmQifQ
// Sample signature
-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM
// Sample JWT Token
eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhm ODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ.-xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM

Sample Code

Format/Example
Encoding and hashing digest:
if(requestBody != null && !requestBody.isEmpty()) {      MessageDigest jwtBody = MessageDigest.getInstance("SHA-256");      byte[] Headers = jwtBody.digest(requestBody.getBytes());      e = Base64.getEncoder().encodeToString(Headers);  }
Preparing payload:
String jwtBody = "{\n \"digest\":\"" + e + "\",\n \"digestAlgorithm\":\"SHA-256\",\n \"iat\":\"" + DateTimeFormatter.RFC_1123_DATE_TIME.format(ZonedDateTime.now(ZoneId.of("GMT"))) + "\"\n} \n\n"; HashMap customHeaders = new HashMap(); customHeaders.put(v-c-merchant-id, merchantConfig.getMerchantID()); String jwsSignatureValue = sign(jwtBody, rsaPrivateKey, x509Certificate, customHeaders);
Generating JWT Token—Header, Payload, and Signature:
private sign(String content, PrivateKey privateKey, X509Certificate x509Certificate, Map<String, ? extends Object> customHeaders) {     if(!this.isNullOrEmpty(content) && x509Certificate != null && privateKey != null) {         String serialNumber = null;         String serialNumberPrefix = "SERIALNUMBER=";         String principal = x509Certificate.getSubjectDN().getName().toUpperCase();         int beg = principal.indexOf(serialNumberPrefix);         if(beg >= 0) {                 int x5cBase64List = principal.indexOf(",", beg);                 if(x5cBase64List == -1) {                     x5cBase64List = principal.length();                 }                 serialNumber = principal.substring(beg + serialNumberPrefix.length(), x5cBase64List);         } else {                 serialNumber = x509Certificate.getSerialNumber().toString();         }         ArrayList x5cBase64List1 = new ArrayList();         try {           x5cBase64List1.add(Base64.encode(x509Certificate.getEncoded()));         } catch (CertificateEncodingException var16) {           logger.error("can\'t signAndEncrypt the payload", var16);           return null;         }         RSAPrivateKey rsaPrivateKey = (RSAPrivateKey)privateKey;         Payload payload = new Payload(content);         JWSHeader jwsHeader = (new com.nimbusds.jose.JWSHeader.Builder(JWSAlgorithm.RS256)).customParams(customHeaders).keyID(serialNumber).x509CertChain(x5cBase64List1).build();         JWSObject jwsObject = new JWSObject(jwsHeader, payload);         try {             RSASSASigner joseException = new RSASSASigner(rsaPrivateKey);             jwsObject.sign(joseException);             if(!jwsObject.getState().equals(com.nimbusds.jose.JWSObject.State.SIGNED)) {                 logger.error("Payload signing failed.");                 return null;             } else {                 return jwsObject;             }         } catch (JOSEException var15) {             logger.error("can\'t signAndEncrypt the payload", var15);             return null;         }     } else {         logger.error("empty or null content or Private key or public certificate is null");         return null;     } }

After Generating the Header

To authenticate requests, place the JSON web token in an HTTP heading in the format:
Authorization: Bearer {token string}
where the {token string} is the string without curly braces.
See also Sample Code.