Construct Messages Using JSON Web Tokens {#restgs-jwt-const-intro} ================================================================== ![](/content/dam/documentation/cybs/en-us/topics/platform/rest/getting-started/images/flow-keys-json-3-750x175.svg/jcr:content/renditions/original) 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.](/content/dam/documentation/cybs/en-us/topics/platform/rest/getting-started/images/restgs-jwt-mess-sec-800x500.svg/jcr:content/renditions/original) JSON Web Token Message Elements {#restgs-jwt-const-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 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.merchant-services.bankofamerica.com`) | | **authorization** | JSON Web Signature (JWS) bearer token. | [HTTP Message Header Elements] **HTTP Message Body** : Your API request. Step 3A: Set Known HTTP Headers {#restgs-jwt-message-set-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 {#restgs-jwt-message-set-jws-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. | 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](/docs/bofa/en-us/platform/developer/all/rest/rest-getting-started/restgs-jwt-message-intro/restgs-security-p12-intro.md ""). | | **typ** | The token type. Set to `JWT`. | [HTTP Message Header Fields] Step 3C: Set the JWS Body Claims {#restgs-jwt-message-set-jws-body} =================================================================== After you set the JWS header values, set these JWS body claim values: | 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.merchant-services.bankofamerica.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 `Bank of America` 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 | [JWS Body Claims] The value of the digest JWS claim is a hashed version of the HTTP message body that you must calculate. `Bank of America` 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 ```keyword 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@bankofamerica.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 {#restgs-jwt-message-conf-token-sig} ========================================================================= 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]` {#restgs-jwt-message-conf-token-sig_step1} {#restgs-jwt-message-conf-token-sig_step1} 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](/docs/bofa/en-us/platform/developer/all/rest/rest-getting-started/restgs-jwt-message-intro/restgs-security-p12-intro.md ""). {#restgs-jwt-message-conf-token-sig_step2} {#restgs-jwt-message-conf-token-sig_step2} 3. Base64-encode the signature output. {#restgs-jwt-message-conf-token-sig_step3} {#restgs-jwt-message-conf-token-sig_step3} 4. After calculating the signature, you can construct a complete JWS token by combining the JWS header claims, body claims, and signature.{#restgs-jwt-message-conf-token-sig_step4} {#restgs-jwt-message-conf-token-sig_step4} **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 {#restgs-jwt-message-construct} ======================================================================= 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.