Elements of a JSON Web Token Message

A JWT message is constructed using HTTP headers and an HTTP message body.

HTTP Message Elements: Your HTTP message header must include these headers:; HTTP Message Headers

HTTP Header
Description

content-type
Also known as the Multipurpose Internet Mail Extension (MIME) type, this identifies the media or file type of the resource. (application/json)

host
The transaction endpoint. (api.visaacceptance.com)

authorization
JWS bearer token.
HTTP Message Body: Your API request.

HTTP Message Headers
HTTP Header	Description
content-type	Also known as the Multipurpose Internet Mail Extension (MIME) type, this identifies the media or file type of the resource. (application/json)
host	The transaction endpoint. (`api.visaacceptance.com`)
authorization	JWS bearer token.

Step 1: Set Known HTTP Headers

Set these HTTP header values that do not require calculation:

content-type
host

Step 2: Set the JWS Header Claims

You must construct a JSON web signature
(JWS) token. To construct a JWS, you must first set its headers claims.

Set these JWS header claim values that do not require calculation.

HTTP Message Headers
Header Field	Description
v-c-merchant-id	Your `Visa Acceptance Solutions` transacting merchant ID (MID). If you are a portfolio or merchant account user, this is the transacting merchant ID that you are sending requests on behalf of.
alg	Algorithm used to sign the token header. These are the supported algorithms: RS256 (default) RS384 RS512 PS256 PS384 PS512
kid	The ID of the key used to digitally sign the JWT. The key ID (kid) must be registered with the authorizing server. This is the key ID from your P12 certificate. For more information, see Create a P12 Certificate.

Step 3: Set the JWS Body Claims

After setting the JWS headers, you must set these JWS body claim values:

JWS Body Claims
JWS Body Claim	Description
iat	The date and time of the message origin. Date formatting is defined by RFC 7231, Section 7.1.1.1.
digest	A Base64 encoded hash of the message payload. The digest field is not included in a GET request.
digestAlgorithm	The algorithm used to hash the message payload. The message payload should be hashed using the SHA-256 algorithm. The digestAlgorithm field is not included in a GET request.

The value of the

digest

HTTP header is a hashed version of the HTTP message body that you must calculate. This hash value is used to validate the integrity of your message by the receiver.

Follow these steps to calculate the digest hash:

Generate the SHA-256 hash of the JSON payload (message body).

Encode the hashed string to Base64.

Add the message body hash to the digest
JWS body claims.

Add the hash algorithm used to the digestAlgorithm
JWS body claims.

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":"[email protected]","phoneNumber":"4158880000"}}}" | shasum -a 256

echo -n "6ae5459bc8a7d6a4b203e8a734d6a616725134088e13261f5bbcefc1424fc956" | base64

Creating a Message Hash Using the Command Line

base64

Tool

echo -n "6ae5459bc8a7d6a4b203e8a734d6a616725134088e13261f5bbcefc1424fc956" | base64

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;
				}

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 JWS signature. The JWS signature is made up of the JWS header and claim set hashes in the following format, and encrypted with the private key.

[JWS Header].[Claim Set]

Follow these steps to calculate the signature:

Concatenate the JWS header and claim set hash strings with a period character (

.

) between the hashes:

[JWS Header].[Claim Set]

Generate an encoded version of the text file using your private key from the .p12
certificate. For more information, see Create a P12 Certificate.

Base64 encode the signature output.

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.