> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.americanexpress.ferndocs.com/fraud-prevention/v2/amex-token-service/api-reference/check-a-tokens-state/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.americanexpress.ferndocs.com/_mcp/server. # Check a token's state. GET https://api.qa.americanexpress.com/payments/digital/v2/tokens/{token_ref_id}/status Returns the current status of an existing token. The endpoint may be particularly helpful in diagnosing issues, such as a failure within a payment flow. Reference: https://developer.americanexpress.ferndocs.com/fraud-prevention/amex-token-service/api-reference/check-a-tokens-state ## Authentication - `Authorization` header (required) — HMAC (one-way TLS). A `MAC` authorization header signed with your client secret. See https://developer.americanexpress.com/documentation/api-security/hmac ## Servers - `https://api.qa.americanexpress.com/payments/digital/v2/tokens` (Sandbox, default) - `https://api.americanexpress.com/payments/digital/v2/tokens` (Production) ## Request ### Path parameters - `token_ref_id` (string, required) — The unique reference identifier for a token. ### Headers - `Accept-Language` (string, required) — This is en-US. - `Content-Language` (string, required) — This is en-US. - `Authorization` (string, required) — 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-key` (string, required) — The Client ID as shown on the American Express Token Service dashboard.e.g., OLQkWT14WtLR0aE63AqtkW2DJppMviSk - `x-amex-token-requester-id` (string, required) — The unique identifier as the Token Requester. Available on the American Express Token Service dashboard.e.g., devportalTest - `x-amex-request-id` (string, required) — The unique identifier for the API request to be returned in the response headers.This is set by the API caller, and it should never be re-used across different transactions.e.g., AA3434342323 ## Response ### 200 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. - `token_status` (string, optional) — The token's status will be one of the following values:Active: The token is active.Suspended: The token has been temporarily suspended.Cancelled: The token is no longer available. ## Errors ### 400 Bad Request Error The submitted request body is not valid. - `error_code` (string, optional) — An error code indicating the contents of the request body that triggered an error.e.g., 104000 - `error_type` (string, optional) — An error type specifying the type of error triggered for the given request body.e.g., invalid_json_error - `error_description` (string, optional) — An error description specifying the problem with the provided request body.e.g., request_body_not_parseable_json ### 401 Unauthorized Error The Authorization header sent with the given request failed internal validation checks. - `error_code` (string, optional) — An error code indicating the request was rejected due to an incorrect Authorization header value.e.g., 104010 - `error_type` (string, optional) — An error type specifying that the type of error triggered was related to the request's Authorization field using HMAC.e.g., invalid_hmac - `error_description` (string, optional) — An error description specifying that the received request's Authorization header does not align with the provided request body or has been generated incorrectly.e.g., invalid_hmac ### 429 Too Many Requests Error The rate at which the caller is allowed to call the service has been exceeded. The caller request rate should be reduced. - `error_code` (string, optional) — An error code indicating the request was rejected due to the frequency of requests to the API.e.g., 104290 - `error_type` (string, optional) — An error type indicating the request was rejected due to the rate of requests being sent by the Token Requester.e.g., rate_limit_violation - `error_description` (string, optional) — An error description indicating the request was rejected due to the rate at which requests are sent to the API exceeding the established request rate limit.e.g., rate_limit_exceeded ### 500 Internal Server Error Internal error. An error that has occurred within the American Express system. The request may be retried based on the aligned retry policy. - `error_code` (string, optional) — An error code indicating the request was rejected due to an error within the API.e.g., 105000 - `error_type` (string, optional) — An error type indicating the request was rejected due to a transient failure within the API.e.g., system_error - `error_description` (string, optional) — An error description indicating the request failed due to an internal issue with the API.e.g., internal_api_error ### 504 Gateway Timeout Error The API gateway has experienced a connection timeout. The request may be retried based on the aligned retry policy. - `error_code` (string, optional) — An error code indicating the request did not receive a response due to a timeout from the API.e.g., 105040 - `error_type` (string, optional) — An error type indicating the request failed to receive its response due to a timeout from the API.e.g., connection_timeout - `error_description` (string, optional) — An error description indicating the request failed to receive a response from the API due to a connection timeout.e.g., connection_timeout ## Examples **Response** ```json { "token_status": "string" } ``` **SDK Code** ```python import requests url = "https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status" headers = { "Accept-Language": "Accept-Language", "Authorization": "", "Content-Language": "Content-Language", "x-amex-api-key": "x-amex-api-key", "x-amex-request-id": "x-amex-request-id", "x-amex-token-requester-id": "x-amex-token-requester-id" } response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status'; const options = { method: 'GET', headers: { 'Accept-Language': 'Accept-Language', Authorization: '', 'Content-Language': 'Content-Language', 'x-amex-api-key': 'x-amex-api-key', 'x-amex-request-id': 'x-amex-request-id', 'x-amex-token-requester-id': 'x-amex-token-requester-id' } }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Accept-Language", "Accept-Language") req.Header.Add("Authorization", "") req.Header.Add("Content-Language", "Content-Language") req.Header.Add("x-amex-api-key", "x-amex-api-key") req.Header.Add("x-amex-request-id", "x-amex-request-id") req.Header.Add("x-amex-token-requester-id", "x-amex-token-requester-id") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Accept-Language"] = 'Accept-Language' request["Authorization"] = '' request["Content-Language"] = 'Content-Language' request["x-amex-api-key"] = 'x-amex-api-key' request["x-amex-request-id"] = 'x-amex-request-id' request["x-amex-token-requester-id"] = 'x-amex-token-requester-id' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status") .header("Accept-Language", "Accept-Language") .header("Authorization", "") .header("Content-Language", "Content-Language") .header("x-amex-api-key", "x-amex-api-key") .header("x-amex-request-id", "x-amex-request-id") .header("x-amex-token-requester-id", "x-amex-token-requester-id") .asString(); ``` ```php request('GET', 'https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status', [ 'headers' => [ 'Accept-Language' => 'Accept-Language', 'Authorization' => '', 'Content-Language' => 'Content-Language', 'x-amex-api-key' => 'x-amex-api-key', 'x-amex-request-id' => 'x-amex-request-id', 'x-amex-token-requester-id' => 'x-amex-token-requester-id', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status"); var request = new RestRequest(Method.GET); request.AddHeader("Accept-Language", "Accept-Language"); request.AddHeader("Authorization", ""); request.AddHeader("Content-Language", "Content-Language"); request.AddHeader("x-amex-api-key", "x-amex-api-key"); request.AddHeader("x-amex-request-id", "x-amex-request-id"); request.AddHeader("x-amex-token-requester-id", "x-amex-token-requester-id"); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Accept-Language": "Accept-Language", "Authorization": "", "Content-Language": "Content-Language", "x-amex-api-key": "x-amex-api-key", "x-amex-request-id": "x-amex-request-id", "x-amex-token-requester-id": "x-amex-token-requester-id" ] let request = NSMutableURLRequest(url: NSURL(string: "https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/status")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```