> 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/the-outbound-token-state-change-notification/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.americanexpress.ferndocs.com/_mcp/server.

# The outbound token state change notification.

POST https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications(outbound)
Content-Type: application/json

This endpoint is an extension of the /notifications endpoint that alerts the Token Requester when the state of the Token is changed by American Express. The request schema provided here is meant to indicate the format of an outbound request sent by American Express. These outbound requests are sent by American Express to the Token Requester who provisioned the token.

Reference: https://developer.americanexpress.ferndocs.com/fraud-prevention/amex-token-service/api-reference/the-outbound-token-state-change-notification

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

### Body (application/json)

This endpoint expects an outbound_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 value for outbound notifications are resume, suspend, delete, and metadataupdate.
- `metadataupdate` (OutboundNotificationsRequestMetadataupdate, optional) — Applicable only when American Express calls the Token Requester. The object is present if the notification_type field is set to metadataupdate.

## Response

### 200

The outbound notification was successfully received and processed by the Token Requester. The contents of the response headers and body are at the discretion of the Token Requester that receives the outbound request.

## Types

### OutboundNotificationsRequestMetadataupdate

Applicable only when American Express calls the Token Requester. The object is present if the notification_type field is set to metadataupdate.

- `metadata_type` (string, optional) — The type of meta-data being sent in the outbound request. The allowed value is account_metadata.e.g., account_metadata
- `account_metadata` (OutboundNotificationsRequestMetadataupdateAccountMetadata, optional) — This is only meant to be used to enrich the display.

### OutboundNotificationsRequestMetadataupdateAccountMetadata

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
- `card_art` (OutboundNotificationsRequestMetadataupdateAccountMetadataCardArt, optional) — The Card's asset information.
- `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

### OutboundNotificationsRequestMetadataupdateAccountMetadataCardArt

The Card's asset information.

- `card_art_url` (string, optional) — The URL pointing to the Card's art image. The image format will be either SVG or PNG.
- `foreground_color` (string, optional) — The text color to be displayed on the Card's artwork.e.g., rgb(0,0,0)

## Examples

**Request**

```json
{}
```

**Response**

```json
{}
```

**SDK Code**

```python
import requests

url = "https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications(outbound)"

payload = {}
headers = {
    "Authorization": "<apiKey>",
    "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(outbound)';
const options = {
  method: 'POST',
  headers: {Authorization: '<apiKey>', '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(outbound)"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<apiKey>")
	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(outbound)")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<apiKey>'
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<String> response = Unirest.post("https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications(outbound)")
  .header("Authorization", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications(outbound)', [
  'body' => '{}',
  'headers' => [
    'Authorization' => '<apiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.qa.americanexpress.com/payments/digital/v2/tokens/notifications(outbound)");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "<apiKey>",
  "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(outbound)")! 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()
```