Skip to main content

How to generate a JSON Web Token (JWT) for the Signature Generation API endpoint

How to generate a JSON Web Token (JWT) for the Signature Generation API endpoint

Last updated: 29-Feb-2024
Rate this article:

Overview

In order to pass the identity of the merchant to the 2Checkout Signature Generation API endpoint, you need to generate a valid JSON Web Token (JWT). This is an Internet standard for creating JSON-based access tokens that assert some number of claims.

The https://jwt.io/ website allows you to decode, verify, and generate JSON Web Tokens.

Recommended resources

JWTs are credentials, which can grant access to resources. Be careful where you paste them! 

Generate a merchant JWT

To generate a merchant JWT, follow the steps below:

1. Before generating a JWT, you need to copy the Buy-link Secret Word from your Merchant Control Panel. Log in to your Control Panel and navigate to Integrations → Webhooks & APISecret word section.

2. Copy the string from the Buy-link Secret Word field to the clipboard.

3. Navigate to the https://jwt.io website and start generating the JWT token.

  • In the Debugger section, you need to input data into the sections highlighted in this image.

jwt_io.png

 

  • The data in the HEADER section identifies which algorithm and token type are used to generate the signature. For your JWT token, use HMAC-SHA-512 (HS512) and token type JWT:
    • alg: HS512 (string, required) - encryption algorithm;

    • typ: JWT (string, required) - token type;

{
 "alg" : "HS512",
 "typ" : "JWT"
}
  • The PAYLOAD section contains a set of claims. The JWT specification defines seven Registered Claim Names which are the standard fields commonly included in tokens. For your JWT, use the following claims:
    • sub: MERCH_CODE (string, required) - subject, the merchant code whom the token refers;

    • iat: 1580915730 (string, required) - issued at, must be current timestamp since the UNIX epoch;

    • exp: 1580915730 (string, optional) - expiration time, must be in UNIX timestamp format from future.

If the expiration time (exp) is not provided, the JWT token expiration time will be calculated from iat + 30 minutes.

All the other fields/claims will be ignored.

 {
  "sub": "MERCH_CODE",
  "iat": 1580912768,
  "exp": 1580916205
}
  • In the VERIFY SIGNATURE section, you calculate the signature. This is calculated by encoding the header and payload using Base64url encoding and concatenating the two values with a period separator. Then run the resulting string through the cryptographic algorithm specified in the header, which in this case is HMAC-SHA512.
  • For your JWT token, replace the <Buy link secret word> from the example below with your Buy-link Secret Word from step 1.
HMACSHA512(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  <Buy link secret word>
)
  •  You will get the JWT token:
eyJhbGciOiJIUzUxMiIsInR5cCI6IkpXVCJ9.eyJz...z0ZY6L6T1GvlOHiptgOQ

4. Use this JWT token in the future to pass your identity as a merchant to the 2Checkout Signature Generation API endpoint. 

Rate this article:

Need help?

Do you have a question? If you didn’t find the answer you are looking for in our documentation, you can contact our Support teams for more information. If you have a technical issue or question, please contact us. We are happy to help.

Not yet a Verifone customer?

We’ll help you choose the right payment solution for your business, wherever you want to sell, in-person or online. Our team of experts will happily discuss your needs.

Verifone logo