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

# Get a token's meta-data.

GET https://api.qa.americanexpress.com/payments/digital/v2/tokens/{token_ref_id}/metadata

Returns the current meta-data of a given token reference identifier.

Reference: https://developer.americanexpress.ferndocs.com/fraud-prevention/amex-token-service/api-reference/get-a-tokens-meta-data

## 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. This is 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_metadata` (MetadataSuccessResponseTokenMetadata, optional) — This is only meant to be used to enrich the display.
- `account_metadata` (MetadataSuccessResponseAccountMetadata, optional) — This is only meant to be used to enrich the display.
- `issuer_data` (issuer_data, optional) — 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.

## 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

## Types

### MetadataSuccessResponseTokenMetadata

This is only meant to be used to enrich the display.

- `expiry_month` (integer, optional) — The token's expiration month as an integer.e.g., 3
- `expiry_year` (integer, optional) — The token's expiration year as a four-digit (YYYY) integer.e.g., 2022
- `display_token_number` (integer, optional) — The last four digits of the token number.

### MetadataSuccessResponseAccountMetadata

This is only meant to be used to enrich the display.

- `display_account_number` (integer, optional) — The last four digits of the Card Account Number.e.g., 4324
- `account_country_code` (string, optional) — Based on the ISO 3166-1 two-digit, alphanumeric country code format.e.g., US
- `product_short_name` (string, optional) — The short name for the product on the provided Card.
- `expiry_month` (integer, optional) — The Card's expiration month as an integer.e.g., 3
- `expiry_year` (integer, optional) — The Card's expiration year as a four-digit (YYYY) integer.e.g., 2022

### issuer_data

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.

- `logo_url` (string, optional) — The network logo URL of the Issuer of the Card.NOTE: Provided only for supported Issuers.
- `name` (string, optional) — The legal name of the Card's Issuer.
- `privacy_policy_url` (string, optional) — The URL for the privacy policy page of the Card's Issuer.NOTE: Provided only for supported Issuers.
- `contact_number` (string, optional) — The contact number of the Card's Issuer. This number should be displayed on a wallet.
- `website_url` (string, optional) — The URL for the website of the Card's Issuer.NOTE: Provided only for supported Issuers.
- `email` (string, optional) — The email address of the Card's Issuer. This email is to be displayed on a wallet.
- `icon` (string, optional) — For use in notifications. The size and resolution vary based on the Token Requester's needs.NOTE: Provided only if the Issuer supports this field.
- `app_schemes` (IssuerDataAppSchemes, optional) — Requirements for applications.

### IssuerDataAppSchemes

Requirements for applications.

- `os_type` (string, optional) — The operating system will be either iOS (Apple) or Android.
- `scheme` (string, optional) — The native app URL or servicing scheme of the Card's Issuer.NOTE: This should contain the package/bundle identifier of the application.

## Examples

**Response**

```json
{
  "token_metadata": {
    "expiry_month": 1,
    "expiry_year": 1,
    "display_token_number": 1
  },
  "account_metadata": {
    "display_account_number": 1,
    "account_country_code": "string",
    "product_short_name": "string",
    "expiry_month": 1,
    "expiry_year": 1
  },
  "issuer_data": {
    "logo_url": "string",
    "name": "string",
    "privacy_policy_url": "string",
    "contact_number": "string",
    "website_url": "string",
    "email": "string",
    "icon": "string",
    "app_schemes": {
      "os_type": "string",
      "scheme": "string"
    }
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/metadata"

headers = {
    "Accept-Language": "Accept-Language",
    "Authorization": "<apiKey>",
    "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/metadata';
const options = {
  method: 'GET',
  headers: {
    'Accept-Language': 'Accept-Language',
    Authorization: '<apiKey>',
    '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/metadata"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Accept-Language", "Accept-Language")
	req.Header.Add("Authorization", "<apiKey>")
	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/metadata")

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"] = '<apiKey>'
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<String> response = Unirest.get("https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/metadata")
  .header("Accept-Language", "Accept-Language")
  .header("Authorization", "<apiKey>")
  .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
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.qa.americanexpress.com/payments/digital/v2/tokens/token_ref_id/metadata', [
  'headers' => [
    'Accept-Language' => 'Accept-Language',
    'Authorization' => '<apiKey>',
    '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/metadata");
var request = new RestRequest(Method.GET);
request.AddHeader("Accept-Language", "Accept-Language");
request.AddHeader("Authorization", "<apiKey>");
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": "<apiKey>",
  "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/metadata")! 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()
```