The JWT claim set is a JSON object whose fields are the claims asserted by the JWT issuer. For example:
{
"sub":"user_name",
"aud":["default"],
"nbf":1503385203,
"iss":"https://example.com:8443",
"exp":1503388803,
"iat":1503385203
}The claim set for a transaction confirmation token that is generated by the Transaction plugin is slightly different from the claim set that is generated by other plugins. These are described below.
API Server JWT Claim Set
The API Server's plugins and configuration object generate/validate a JWT that uses the standard claim set specified in RFC 7519. These are described in the table below.
Claim Name | Description |
|---|---|
sub | Mandatory. String. Subject, in other words, the user. |
aud | Mandatory. String. Audience or the intended recipient. This is a tenant name. |
nbf | Optional. Integer. Not before time. The time before which the JWT must not be accepted for processing. Present only if the jwt_config's generate.nbf_delta field is used. |
iss | Mandatory. String. Issuer of the JWT. The URL of the API Server. |
exp | Mandatory. Integer. Expiration time. Time after which the JWT expires. |
iat | Mandatory. Integer. Issued at time. The issuing date/time (number of seconds from epoch). |
auth_time | Mandatory. Integer. The date/time of authentication (number of seconds from epoch). This is added to the session token when a session is created after user authentication. This is copied from the old JWT to the new JWT when the session is renewed. Only used by the Session plugin's JWT Processor. |
Transaction Confirmation Token
The Transaction plugin creates a transaction confirmation token which includes the transaction text object confirmed by the buyer. Your client app sends this token to your backend system, so that your backend system can verify that transaction confirmation token prior to processing the user's transaction.
When your client app initiates transaction confirmation, the App SDK interacts with the user to get their consent to that transaction and sends that information to the Auth Server. The Auth Server authenticates that consent and sends back its response. The API Server acts as a gateway between the Auth Server and App SDK. Before the API Server sends the response to the App SDK, it generates a transaction confirmation token that it includes in the Auth Server's response.
The Transaction Confirmation Token (tcToken) body has the following claims in JWT:
Name | Description |
|---|---|
iss | Mandatory. Issuer of the JWT. The URL of the API Server. |
iat | Mandatory. Issued at time. The issuing date/time in number of seconds from epoch. |
aud | Mandatory. A tenant name. |
sub | Mandatory. The userName on Auth Server who confirmed the transaction. |
jti | Optional. The unique identifier for the token (JWT ID). See RFC 7519 for when you can use this claim. |
exp | Optional. The expiration date/time of the token in the number of seconds from epoch. If the jti claim is present in the token, this claim must be included. |
txn | Mandatory. The transaction ID. |
txt | Mandatory if the transaction was completed without SPC. The transaction text in a JSON. |
If the transaction is completed using Secure Payment Confirmation, the claims in the rows below are included.
Name | Description |
|---|---|
spc | Mandatory. A boolean indicating whether the transaction is fulfilled using Secure Payment Confirmation. |
inst_dispname | Mandatory. The name of the payment instrument displayed to the user. |
inst_icon | Mandatory. The URL of the icon of the payment instrument. |
orig | Mandatory. The origin where the Secure Payment Confirmation takes place. |
pmt_amt | Mandatory. The amount of the transaction. |
pmt_cur | Mandatory. The currency of the transaction. |
payee_orig | Mandatory. The origin that triggers the transaction. |
payee_name | Mandatory. The merchant name that triggers the transaction. |
rpid | Mandatory. The Relying Party Identifier. |
top_orig | Mandatory. The top origin that triggers the transaction. This is different from orig only if the transaction is completed through a cross-origin iframe. |
Example header of a tcToken for a transaction that may or may not use SPC:
{
"kid": "rsa_sig_2048",
"alg": "RS256"
}Example payload of a tcToken for a transaction that does not use SPC:
{
"sub": "userName",
"aud": "default",
"txt": "Authorize $100 payment from Tutorial App?",
"iss": "https://example.com:8443",
"exp": 1560948382,
"iat": 1560944782,
"jti": "d458b353-7f7e-45c9-ab62-950a33926c19"
}Example payload of a tcToken for a transaction that uses SPC:
{
"sub": "userName",
"rpid": "example.com",
"top_orig": "https://example.com",
"orig": "https://example.com",
"spc": true,
"iss": "https://example.com",
"pmt_amt": "100.0",
"pmt_cur": "USD",
"inst_icon": "https://example.com/img/instrument-icon.png",
"inst_dispname": "U.S. Bank...1234",
"payee_orig": "https://merchant.example.com",
"payee_name": "Tutorial App",
"aud": "default",
"nbf": 1663931831,
"auth_time": 1663931831,
"exp": 1663935431,
"iat": 1663931831,
"jti": "c53b5210-c291-40c4-87b9-3ac385671d3b"
}