Skip to navigation
API Reference

Provision a four-digit security code for a transaction.

Returns a payment credential for a transaction context.

Authentication

Authorizationstring

HMAC (one-way TLS). A MAC authorization header signed with your client secret. See https://developer.americanexpress.com/documentation/api-security/hmac

Headers

Accept-LanguagestringRequired<=36 characters

This is en-US.

Content-LanguagestringRequired<=36 characters

This is en-US.

AuthorizationstringRequired<=256 characters

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=".

x-amex-api-keystringRequired<=64 characters

The Client ID displayed on the American Express Token Service dashboard.

e.g., OLQkWT14WtLR0aE63AqtkW2DJppMviSk

x-amex-token-requester-idstringRequired<=64 characters

The unique identifier as a Token Requester. This is available on the American Express Token Service dashboard.

e.g., devportalTest

x-amex-request-idstringRequired<=64 characters

The unique identifier for the API request to be returned in the response headers.

It is set by the API caller, and it should never be re-used across different transactions.

e.g., AA3434342323

Request

This endpoint expects an object.
token_ref_idstringOptional<=64 characters

The unique reference identifier for a token.

risk_assessment_dataobjectOptional
The User's risk profile on the Token Requester's domain.
encrypted_payloadobjectOptional

The base64-encoded JWE(Json Web Encryption) string containing the PAN information. The JWE string should adhere to RFC 7516.

Steps for encryption:

  1. The JWE encryption utility will generate an AES 128-bit dynamic data encryption key.
  2. The dynamic data encryption key should be wrapped with the static AES 256-bit key provided by American Express using the A256KW algorithm.
  3. Set the key identifier of the static AES key in the header.
  4. Use the JSON compact serialization.
  5. Set the resulting JWE blob in the encrypted_payload element.

Key wrap algorithm: A256KW

Data encryption algorithm: AES/GCM/NoPadding

Response headers

x-amex-request-idstringOptional
The unique identifier sent with the request.
session_idstringOptional
The unique identifier of the session generated by the TSP.

Response

The request has been processed successfully.

Upon a 200 response, the transaction was successfully processed and the token data and transaction data are returned in a response payload.

encrypted_payloadobjectOptional

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:

  1. 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.
  2. Unwraps the dynamic data encryption key, using the static AES 256-bit key, by means of the A256KW algorithm.
  3. Decrypts the data using the 128-bit dynamic encryption key, by means of the A128GCM algorithm.
  4. Validates the authorization tag.
  5. The resulting JSON object conforms to the secure_token_data.

Key wrap algorithm: A256KW

Data encryption algorithm: AES/GCM/NoPadding

Errors

400
Bad Request Error
401
Unauthorized Error
429
Too Many Requests Error
500
Internal Server Error
504
Gateway Timeout Error