> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developer.americanexpress.ferndocs.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.americanexpress.ferndocs.com/_mcp/server. # Update a token's state. POST https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications Content-Type: application/json Allows the Token Requester to update the state of a token. Reference: https://developer.americanexpress.ferndocs.com/fraud-prevention/amex-token-service/api-reference/update-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 ### 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 displayed on the American Express Token Service dashboard.e.g., OLQkWT14WtLR0aE63AqtkW2DJppMviSk - `x-amex-token-requester-id` (string, required) — The unique identifier as a 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.It is set by the API caller, and it should never be re-used across different transactions.e.g., AA3434342323 ### Body (application/json) This endpoint expects a notifications_request. - `token_ref_id` (string, optional) — 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. - `notification_type` (string, optional) — The desired end state of the token specified by the token_ref_id field in the request.The allowed values are:resume: If the token should be in an active state. An active token can be used for transactions and /metadata endpoint calls.suspend: If the token should be in a suspended state. A suspended token cannot be used for transactions or /metadata endpoint calls.delete: If the token should be permanently deleted. Similar to a suspended token, a deleted token cannot be used for transactions or /metadata endpoint calls. Unlike a suspended token, a deleted token cannot have its state changed. ## Response ### 200 The request has been processed successfully.Upon a 200 response, the state of the token was successfully changed. No response body is provided when the token state is changed. ## 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 the Authorization header value or the notification_type field in the request.e.g., 104010 - `error_type` (string, optional) — An error type specifying the source of the authorization rejection.e.g., invalid_hmac - `error_description` (string, optional) — An error description specifying the reason behind the rejected authorization.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 **Request** ```json {} ``` **Response** ```json {} ``` **SDK Code** ```python import requests url = "https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications" payload = {} 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", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications'; const options = { method: 'POST', 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', 'Content-Type': 'application/json' }, body: '{}' }; 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" "strings" "net/http" "io" ) func main() { url := "https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications" payload := strings.NewReader("{}") req, _ := http.NewRequest("POST", url, payload) 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") req.Header.Add("Content-Type", "application/json") 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/notifications") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.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' request["Content-Type"] = 'application/json' request.body = "{}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications") .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") .header("Content-Type", "application/json") .body("{}") .asString(); ``` ```php request('POST', 'https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications', [ 'body' => '{}', 'headers' => [ 'Accept-Language' => 'Accept-Language', 'Authorization' => '', 'Content-Language' => 'Content-Language', 'Content-Type' => 'application/json', '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/notifications"); var request = new RestRequest(Method.POST); 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"); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{}", ParameterType.RequestBody); 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", "Content-Type": "application/json" ] let parameters = [] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data 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() ```