JWT

The JWT endpoints handle the authentication handshake between your server and the 3DS Client SDK. JWT Create produces a signed token the SDK uses to initialise the 3DS session; JWT Validate decodes the token returned by the SDK after cardholder authentication and provides the final authentication outcome.

1

Step 1 — Create a JWT

The JWT Create endpoint produces a signed JSON Web Token used as the initial authentication handshake with the 3DS Client SDK. Pass this token to the SDK on page load before initiating the Lookup flow.

The jwt value returned by this endpoint should be passed to Cardinal.setup() (or the equivalent SDK initialisation call) as the session token. The device_info_id returned here should be included in the subsequent Lookup request.

2

Step 2 — Validate a JWT

After the cardholder completes the 3DS authentication (frictionless or challenge), the 3DS Client SDK returns a signed JWT. Pass this JWT to the Validate endpoint to decode the result and retrieve the authentication outcome.

The authentication_id in the JWT Validate response must match the authentication_id from your original Lookup response. Store the Lookup authentication_id before calling Validate and verify the values match before proceeding to authorization.

JWT Validate Response Fields

JwtValidateResponse
  ├── authentication_id   ← Match against Lookup response — required for authorization
  ├── action_code         ← Resulting state of the transaction
  ├── error_no            ← 0 = no error; non-zero = error encountered
  ├── error_desc          ← Human-readable error description (comma-separated if multiple)
  └── validation_result   ← Full authentication result object

A non-zero error_no indicates an error during JWT processing. Multiple errors are returned as comma-separated values in error_no and error_desc. Do not proceed to authorization if error_no is non-zero.

Full Flow Summary

JWT Create (Step 1)

1. Call POST /v2/jwt/create from your server

2. Pass the returned jwt to the 3DS Client SDK

3. Store the device_info_id for the Lookup request

4. SDK initialises the 3DS session

JWT Validate (Step 2)

1. SDK returns a JWT after cardholder authentication

2. Call POST /v2/jwt/validate with that JWT

3. Verify authentication_id matches Lookup

4. Use action_code and validation_result to complete authorization