On This Page
FILTER BY TAG

Construct Messages Using JSON Web Tokens

This figure shows the steps required for using JSON Web Tokens (JWTs) to construct messages. Each step is described in the following subsections.

JSON Web Token Message Elements

A JWT message consists of HTTP headers and an HTTP message body.
HTTP Message Elements
Your HTTP message header must include these elements:
HTTP Message Header Elements
HTTP Header Element
Description
content-type
Also known as the Multipurpose Internet Mail Extension (MIME) type, this element identifies the media or file type of the resource (application/json).
host
The transaction endpoint. (
api.cybersource.com
)
authorization
JSON Web Signature (JWS) bearer token.
HTTP Message Body
Your API request.

Step 1: Set Known HTTP Headers

Set the values for these HTTP header elements. They do not require calculation.
content-type
Set to the media or file type resource.
host
Set to the endpoint.

Step 2: Set the JWS Header Claims

You must construct a
JSON Web Signature
 (JWS) token. To construct a JWS token, you must first set its header claim values.
These header claim values do not require calculation.
HTTP Message Header Fields
Header Field
Description
alg
The symmetric algorithm you use to sign the token header. These algorithms are supported:
  • HS256
  • HS384
  • HS512
kid
The ID of the key you use to digitally sign the JWT. The key ID must be registered with the authorizing server. It is the key ID from your P12 certificate. For more information, see Create or Submit a P12 Certificate.
typ
The token type. Set to
JWT
.

Step 3: Set the JWS Body Claims

After you set the JWS header values, set these JWS body claim values:
JWS Body Claims
JWS Body Claim Field
Description
Data Type
digest
A Base64-encoded hash of the message payload.
Do not include the
digest
 field if the request message is empty, such as during a GET or DELETE request.
String
digestAlgorithm
The algorithm used to hash the message payload.
The message payload should be hashed using the SHA-256 algorithm.
Do not include the
digestAlgorithm
 field if the
digest
 field is not included.
String
exp
The time at which the JWS token expires. Field values cannot exceed two minutes after the message issue date, which is the
iat
 field value. This field is an HTTP-date value as defined in RFC7231.
For example, 01/01/2020 at 00:02:00 is
1577836920
.
String
iat
The date and time at which the message is issued. This field uses a
NumericDate
 value as defined in RFC 7519, which is the number of seconds since
1970‑01‑01T00:00:00Z
 (Unix epoch).
For example, 01/01/2020 at 00:00:00 is
1577836800
.
String
iss
The issuer identifier for the JWS token. Set to the organization ID that created the private key (P12 certificate). This value is used to validate the issuer.
String
jti
The unique token ID. This value is used for replay prevention.
Format the value using UUID version 4. For example:
6643fb9a-8093-47c6-95d3-8d69785b5e62
String
request-method
The HTTP request method. For example,
POST
,
GET
,
PUT
,
PATCH
, or
DELETE
.
It is standard practice to format this value using lowercase digits.
String
request-resource-path
The complete URL path for the HTTP request.
It is standard practice to format this value using lowercase digits.
String
v-c-jwt-version
The Visa JWT scheme version number. Set to
2
.
It is standard practice to format this value using lowercase digits.
String
v-c-merchant-id
Your
Cybersource
 transacting merchant ID (MID).
If you are a portfolio or merchant account user, set this to the transacting merchant ID you send requests on behalf of.
String
v-c-response-mle-kid
The message-level encryption response key ID, also known as the
REST–API Response MLE
 key.
String
The value of the
digest
 JWS claim is a hashed version of the HTTP message body that you must calculate.
Cybersource
 uses this hash value to validate the integrity of your message body.
Follow these steps to calculate the digest hash:
  1. Generate the SHA-256 hash of the JSON payload (message body).
  2. Encode the hashed string to Base64.
  3. Add the message body hash to the
    digest
     JWS body claims.
  4. Add the algorithm used to hash the digest in the
    digestAlgorithm
     JWS body claims.
Example: Creating a Message Hash Using the Command Line
shasum
 Tool
echo -n "{"clientReferenceInformation":{"code":"TC50171_3"},"paymentInformation":{"card":{"number":
				"4111111111111111","expirationMonth":"12","expirationYear":"2031"}},"orderInformation":{"amountDetails":
				{"totalAmount":"102.21","currency":"USD"},"billTo”:{“firstName":"John","lastName":"Doe","address1":
				"1MarketSt","locality":"sanfrancisco","administrativeArea":"CA","postalCode":"94105","country":"US",
				"email":"","phoneNumber":"4158880000"}}}" | shasum -a 256
echo -n "6ae5459bc8a7d6a4b203e8a734d6a616725134088e13261f5bbcefc1424fc956" | base64
Example: Creating a Message Hash Using the Command Line
base64
 Tool
echo -n "6ae5459bc8a7d6a4b203e8a734d6a616725134088e13261f5bbcefc1424fc956" | base64
Example: Creating a Message Hash Using C#
public static string GenerateDigest() {
				var digest = "";
				var bodyText = "{ your JSON payload }";
				using (var sha256hash = SHA256.Create()) {
				byte[] payloadBytes = sha256hash
				.ComputeHash(Encoding.UTF8.GetBytes(bodyText));
				digest = Convert.ToBase64String(payloadBytes);
				digest = "SHA-256=" + digest;
				}
				return digest;
				}
Example: Creating a Message Using Java
public static String GenerateDigest() throws NoSuchAlgorithmException {
				String bodyText = "{ your JSON payload }";
				MessageDigest md = MessageDigest.getInstance("SHA-256");
				md.update(bodyText.getBytes(StandardCharsets.UTF_8));
				byte[] digest = md.digest();
				return "SHA-256=" + Base64.getEncoder().encodeToString(digest);
				}

Step 4: Calculate the JWS Signature

You can now calculate the JSON Web Signature (JWS). The JWS consists of the JWS header and claim set hashes in the following format. They are encrypted with the private key.
[JWS Header].[Claim Set]
Follow these steps to calculate the signature:
  1. Concatenate the JWS header and claim set hash strings with a period character (
    .
    ) between the hashes:
    [JWS Header].[Claim Set]
  2. Generate an encoded version of the text file using your private key from the
    .p12
     certificate. For more information, see Create or Submit a P12 Certificate.
  3. Base64-encode the signature output.
  4. After calculating the signature, you can construct a complete JWS token by combining the JWS header claims, body claims, and signature.
Example: Token Signature Hash
YjgwNGIxOTMxMzQ2NzhlYjdiMDdhMWZmYjZiYzUzNzliMTk5NzFmNjAzNWRmMThlNzk0N2NhY2U0YTEwNzYyYQ
Code Example: Encoding the Signature File Using OpenSSL
Encode the signature file using the
openssl
 tool.
openssl rsautl -encrypt -inkey publickey.key -pubin -in [signature-text-file]
					> [signature-encoded-file]
Code Example: Base64 Encoding the Signature File Using the Command Line
Encode the signature file using the
openssl
 tool and remove any padding.
base64 -i [signature-encoded-file]

Step 5: Complete the Message with JWTs

Combine all of the HTTP headers with your HTTP message body to construct your HTTP signature message.
If you have not already, you must construct the entire JWS token by combining the JWS header claims, body claims, and signature from Steps 2 – 4.
RELATED TO THIS PAGE