On This Page
FILTER BY TAG

Construct Messages Using JSON Web Tokens

WARNING
As of
February 2026
, there are new requirements for constructing a JWT. This section explains how to update your system to remain in compliance. You must update how your system constructs JWTs by
September 2026
 to remain compliant. You risk transaction failure if you do not update your system.
To construct a message using JWTs, you must set the required HTTP headers, define the JWS header and body claims, calculate the token signature, and combine these elements into a request. This section describes how to create each element and construct the completed JWT message in the following subsections.

Figure:

JWT Construction Steps
Step 3A: Set the known HTTP header values. Step 3B: Set the JWS header claims. Step 3C: Set the JWS body claims. Step 3D: Calculate the token signature. Step 3E: Combine the HTTP headers and HTTP message body.

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 3A: Set Known HTTP Headers

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

Step 3B: 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 asymmetric algorithm you use to sign the token header. These algorithms are supported:
  • RS256 (default)
  • RS384
  • RS512
  • PS256
  • PS384
  • PS512
kid
The key ID you use to digitally sign the JWT. It 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 3C: 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
Format
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
Lowercase
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
Lowercase
exp
The time at which the JWS token expires.
IMPORTANT
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
Numeric
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
Numeric
iss
The issuer identifier for the JWS token. Set to the merchant ID that created the P12 certificate. This value is used to validate the issuer.
String
Lowercase
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
Lowercase alphanumeric
request-method
The HTTP request method. For example,
post
,
get
,
put
,
patch
, or
delete
.
String
Lowercase
request-resource-path
The endpoint path for the HTTP request, excluding the hostname.
For example, to send a message to the
https://api.cybersource.com
/pts/v2/payments
 endpoint, set this field to
/pts/v2/payments
.
String
Lowercase alphanumeric
v-c-jwt-version
The Visa JWT scheme version number. Set to
2
.
String
Numeric
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
Lowercase alphanumeric
v-c-response-mle-kid
The message-level encryption response key ID, also known as the
REST–API Response MLE
 key.
String
Lowercase alphanumeric
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
cat <<'EOF' | tr -d '\n' | shasum -a 256
{
  "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": "
test@cybs.com
",
      "phoneNumber": "4158880000"
    }
  }
}
EOF
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);
    }

    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 Base64.getEncoder().encodeToString(digest);
}

Step 3D: 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 3E: 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