Provision a token.
Returns the token and displays the account information if valid details are provided for a given Card.
Authentication
HMAC (one-way TLS). A MAC authorization header signed with your client secret. See https://developer.americanexpress.com/documentation/api-security/hmac
Headers
This is en-US.
This is en-US.
The HMAC authorization header generated as prescribed by American Express API security.
e.g., MAC id="OLQkWT14WtLR0aE63AqtkW2DJppMviSk", ts="1548353658039", nonce="18036bb8-a100-4e02-ab93-328abd67acf2", bodyhash="uRphuQfK6igW44z4Ns/Bo9XdiXlsCdEzTsxdeUBu9j8=", mac="yJ70ObsprC2ygCjzq88Lq0QTKPqlLMIPYpR4O1DBg+Y="
The Client ID displayed on the American Express Token Service dashboard.
e.g., OLQkWT14WtLR0aE63AqtkW2DJppMviSk
The unique identifier as a Token Requester. Available on the American Express Token Service dashboard.
e.g., devportalTest
The unique identifier for the API request to be returned in the response headers.
It is set by the API caller, and should never be re-used across different transactions.
e.g., AA3434342323
Request
The base64-encoded JWE string containing the Primary Account Number (PAN) information. The JWE string should adhere to RFC 7516.
Steps for encryption:
- The JWE encryption utility will generate an AES 128-bit dynamic data encryption key. Encrypt the account_data object using this key and the A128GCM algorithm.
- The dynamic data encryption key should be wrapped with the static AES 256-bit key provided by American Express using the A256KW algorithm.
- Set the key identifier of the static AES key in the header.
- Use the JSON compact serialization.
- Set the resulting JWE blob in the account_data element.
Key wrap algorithm: A256KW
Data encryption algorithm: AES/GCM/NoPadding
Response headers
The unique identifier of the session generated by the Token Service Provider (TSP).
Response
The request has been processed successfully.
Upon a 200 response, the token is successfully provisioned and the token data is returned in a response payload.
The unique reference identifier for a token.
NOTE: This data needs to be stored by the Token Requester for the life cycle API calls, such as /notifications, /status, and /metadata.
The JSON Web-encrypted token and payment data for authorization. You will receive this as a base64-encoded string as per RFC 7516. The secure_token_data is encrypted using a dynamically-generated, 128-bit data encryption key using the A128GCM algorithm. The dynamic data encryption key is wrapped with the static AES 256-bit key provided by American Express, using the A256KW algorithm.
Steps to decrypt:
- Base64 decodes the header and reads the key identifier. Looks up the static AES 256-bit key provided by American Express that has been mapped to the key identifier.
- Unwraps the dynamic data encryption key, using the static AES 256-bit key, by means of the A256KW algorithm.
- Decrypts the data using the 128-bit dynamic encryption key, by means of the A128GCM algorithm.
- Validates the authorization tag.
- The resulting JSON object conforms to the secure_token_data.
Key wrap algorithm: A256KW
Data encryption algorithm: AES/GCM/NoPadding
This is only meant to be used to enrich the display.
The meta-data for the Card's account as provided by the Card's Issuer. This data is only meant to be used for enriching the display of Card's account.