Digital Wallet

API Implementation Guide

Version 2.1
March 2021
Confidential and Trade Secret Materials
This document contains sensitive, confidential, and trade secret information and may not be disclosed to third parties
without the prior written consent of American Express Travel Related Services Company, Inc.

To the maximum extent permitted by law, American Express does not make and hereby disclaims any and all
representations, warranties, and liabilities, whether express or implied, or arising by law or from a course of dealing or
usage of trade, including implied warranties of merchantability or fitness for a particular purpose or any warranty of
title or non-infringement. Each Participant must comply with laws and regulations applicable to the subject matter of
this document. These laws and regulations can differ from country to country, and each Participant is solely
responsible for being aware and adhering to them in all countries where applicable.

The policies, procedures, and rules in this manual are subject to change from time to time by American Express
Global Network Services.

All Rights Reserved. © 2021 American Express Travel Related Services Co., Inc.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 2
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Table of Contents
1 Introduction.......................................................................................................................................... 10
Purpose................................................................................................................................................... 10
How to Use this Document.......................................................................................................................... 10
Ref erence Documents................................................................................................................................ 10
2 Application Programming Interface Design Philosophy........................................................................... 11
Endpoint Structure ................................................................................................................................ 11
3 Application Programming Interface (API) Definitions ............................................................................... 12
Request Common Elements........................................................................................................................ 12
Response Common Elements ..................................................................................................................... 12
HTTP Status Codes for API Responses ........................................................................................................ 13
Service Level Agreements, Connection, Timeout, and Retries .......................................................................... 13
Additional Considerations and Requirements ................................................................................................. 13
4 Network Provisioning Application Programming Interfaces ..................................................................... 14
Communication Sequence ..................................................................................................................... 15
Account Eligibility Check API....................................................................................................................... 16
Endpoint .............................................................................................................................................. 16
Request Header ................................................................................................................................... 16
Request Body ...................................................................................................................................... 17
Plain Account Data JSON Fields ............................................................................................................. 17
Risk Assessment Data........................................................................................................................... 17
Device Data ......................................................................................................................................... 18
Response Header................................................................................................................................. 18
Response Body .................................................................................................................................... 18
Ineligibility Reason Codes ...................................................................................................................... 19
Account Metadata................................................................................................................................. 19
Market................................................................................................................................................. 20
Response Status Codes ........................................................................................................................ 20
Account Eligibility Check API Request and Response Example ........................................................................ 22
Risk Assessment API................................................................................................................................. 23
Endpoint .............................................................................................................................................. 23
Request Header ................................................................................................................................... 23
Request Body ...................................................................................................................................... 23
Plain Account Data JSON Fields ............................................................................................................. 24
Risk Assessment Data........................................................................................................................... 24
Response Header................................................................................................................................. 28
Response Body .................................................................................................................................... 28
Response Codes .................................................................................................................................. 29

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 3
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Account Metadata................................................................................................................................. 29
Risk Assessment API Request and Response Examples................................................................................. 30
5 One-Time Passcode Services ................................................................................................................ 32
One-Time Passcode Management Services .................................................................................................. 34
Get Tenured Channels API ......................................................................................................................... 34
Get Tenured Channels Network Validation .................................................................................................... 34
Endpoint .............................................................................................................................................. 34
Request Header ................................................................................................................................... 34
Request Body ...................................................................................................................................... 34
Plain Account Data JSON Fields ............................................................................................................. 35
Device Data ......................................................................................................................................... 35
Response Header................................................................................................................................. 35
Response Body .................................................................................................................................... 36
Communication Channels ...................................................................................................................... 36
Response Codes .................................................................................................................................. 36
Get Tenured Channels API Request and Response Example........................................................................... 37
Deliver Security Challenge API .................................................................................................................... 38
Endpoint .............................................................................................................................................. 38
Request Header ................................................................................................................................... 38
Request Body ...................................................................................................................................... 38
Plain Account Data JSON Fields ............................................................................................................. 38
Device Data ......................................................................................................................................... 39
Response Header................................................................................................................................. 39
Response Body .................................................................................................................................... 39
Response Codes .................................................................................................................................. 40
Deliver Security Challenge API Request and Response Example ..................................................................... 40
6 Issuer Notification Application Programming Interface ............................................................................ 41
Endpoint .............................................................................................................................................. 41
Request Header ................................................................................................................................... 41
Request Body ...................................................................................................................................... 41
Plain Account Data JSON Fields ............................................................................................................. 42
Token Data.......................................................................................................................................... 42
Device Data ......................................................................................................................................... 43
Event Data........................................................................................................................................... 44
Event Status Codes............................................................................................................................... 44
Response Header................................................................................................................................. 44
Response Status Codes ........................................................................................................................ 45
Issuer Notification API Request and Response Example ................................................................................. 46
7 Account Life Cycle Management Application Programming Interfaces ..................................................... 47
Account Update API .................................................................................................................................. 48

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 4
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Endpoint .............................................................................................................................................. 48
Request Header ................................................................................................................................... 48
Plain Account Data JSON Fields ............................................................................................................. 48
Metadata ............................................................................................................................................. 49
Response Header................................................................................................................................. 49
Response Body .................................................................................................................................... 49
Status Code and Status Code Type......................................................................................................... 49
Account Update API Request and Response Example .................................................................................... 50
Account Update API at GUID Level Request and Response Example ............................................................... 51
Account Unlock API ................................................................................................................................... 52
Endpoint .............................................................................................................................................. 52
Request Header ................................................................................................................................... 52
Request Body ...................................................................................................................................... 52
Plain Account Data JSON Fields ............................................................................................................. 53
Response Header................................................................................................................................. 53
Response Body .................................................................................................................................... 53
Status Code and Status Code Type......................................................................................................... 53
Account Unlock API Request and Response Example .................................................................................... 54
Account Suspend API ................................................................................................................................ 55
Endpoint .............................................................................................................................................. 55
Request Header ................................................................................................................................... 55
Request Body ...................................................................................................................................... 55
Plain Account Data JSON Fields ............................................................................................................. 55
Response Header................................................................................................................................. 56
Response Body .................................................................................................................................... 56
Status Code and Status Code Type......................................................................................................... 56
Account Suspend API Request and Response Example.................................................................................. 57
Account Resume API ................................................................................................................................. 58
Endpoint .............................................................................................................................................. 58
Request Header ................................................................................................................................... 58
Request Body ...................................................................................................................................... 58
Request Data ....................................................................................................................................... 58
Response Header................................................................................................................................. 59
Response Body .................................................................................................................................... 59
Status Code and Status Code Type......................................................................................................... 59
Account Resume API Request and Response Example .................................................................................. 60
Account Delete API.................................................................................................................................... 61
Endpoint .............................................................................................................................................. 61
Request Header ................................................................................................................................... 61
Request Body ...................................................................................................................................... 61

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 5
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Request Data ....................................................................................................................................... 61
Response Header................................................................................................................................. 62
Response Body .................................................................................................................................... 62
Status Code and Status Code Type......................................................................................................... 62
Account Delete API Request and Response Example ..................................................................................... 63
8 Token Life Cycle Management Application Programming Interfaces......................................................... 64
Token Suspend API................................................................................................................................... 64
Endpoint .............................................................................................................................................. 64
Request Header ................................................................................................................................... 64
Request Body ...................................................................................................................................... 64
Request Data ....................................................................................................................................... 64
Response Header................................................................................................................................. 65
Response Body .................................................................................................................................... 65
Status Code and Status Code Type......................................................................................................... 65
Token Suspend API Request and Response Example .................................................................................... 66
Token Resume API.................................................................................................................................... 67
Endpoint .............................................................................................................................................. 67
Request Header ................................................................................................................................... 67
Request Body ...................................................................................................................................... 67
Request Data ....................................................................................................................................... 67
Response Header................................................................................................................................. 67
Response Body .................................................................................................................................... 68
Status Code and Status Code Type......................................................................................................... 68
Token Resume API Request and Response Example ..................................................................................... 69
Token Delete API ...................................................................................................................................... 70
Endpoint .............................................................................................................................................. 70
Request Header ................................................................................................................................... 70
Request Body ...................................................................................................................................... 70
Request Data ....................................................................................................................................... 70
Response Header................................................................................................................................. 70
Response Body .................................................................................................................................... 71
Status Code and Status Code Type......................................................................................................... 71
Token Delete API Request and Response Example........................................................................................ 72
9 Servicing Application Programming Interfaces ....................................................................................... 73
Token History API ..................................................................................................................................... 73
Endpoint .............................................................................................................................................. 73
Time Outs............................................................................................................................................ 73
Request Header ................................................................................................................................... 73
Request Body ...................................................................................................................................... 73
Plain Account Data JSON Fields ............................................................................................................. 74

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 6
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Credit Card .......................................................................................................................................... 74
Search Criteria ..................................................................................................................................... 75
Response Header................................................................................................................................. 75
Common Attributes ............................................................................................................................... 75
Status Code and Status Code Type......................................................................................................... 75
Links ................................................................................................................................................... 76
Token History Scenarios ........................................................................................................................ 76
Response Body .................................................................................................................................... 77
Response Account Information ............................................................................................................... 77
Account References .............................................................................................................................. 77
Account Metadata................................................................................................................................. 78
Token Requester Information.................................................................................................................. 78
Token Information................................................................................................................................. 79
Status ................................................................................................................................................. 79
Token Metadata.................................................................................................................................... 80
Form Factor Data.................................................................................................................................. 80
Token Inquiry API using Card Key Identif ier Example Request and Response .................................................... 82
Event History API Request and Response Example........................................................................................ 85
10 Bank App Provisioning ........................................................................................................................ 88
IssuerData Generation ............................................................................................................................... 89
IssuerData ........................................................................................................................................... 89
AccountData ........................................................................................................................................ 89
IssuerSignatureData Scheme...................................................................................................................... 90
ContentInfo .......................................................................................................................................... 90
EnvelopeData ...................................................................................................................................... 90
SymmetricDataBean ............................................................................................................................. 91
EncryptedDataContentInfo ..................................................................................................................... 92
Java Code for IssuerData Generation Example.............................................................................................. 93
Example for JWE Encryption and JWE Decryption of IssuerData Object ............................................................ 96
11 Security and Encryption ...................................................................................................................... 97
Transport Layer Security ............................................................................................................................ 97
Two-way Transport Layer Security........................................................................................................... 97
Secure Socket Layer Certificate Exchange ............................................................................................... 97
Data Security ............................................................................................................................................ 97
Data Security for Bank App Provisioning................................................................................................... 97
JSON Web Encryption Key Exchange...................................................................................................... 98
Data Encryption.................................................................................................................................... 98
JSON Web Encryption Implementation Example ............................................................................................ 99
12 Glossary of Terms..............................................................................................................................100
13 Acronyms..........................................................................................................................................103

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 7
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Table of Figures
Figure 1: Communication Sequence............................................................................................................. 15
Figure 2: One-Time Passcode Flow ............................................................................................................. 33
Figure 3: Life Cycle Management Event Flows............................................................................................... 47
Figure 4: Bank App Provisioning Flow........................................................................................................... 88

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 8
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Version History
Version Description/Changes/Notes Date Submitted
1.0 First version of the API Issuer Implementation Guide November 2019
2.0 Updated version with corrections January 2021
2.1 March 2021
• Added new Bank App Provisioning chapter

• Updated Data Security section for Bank App

Provisioning in the Security and Encryption chapter

• Removed One-way TLS from the Transport Layer

Security section in the Security and Encryption
chapter

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 9
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
1 Introduction
The Application Programming Interface (API) Implementation Guide provides Issuers with the information required to
enable payments using a mobile device over Near Field Communication (NFC) utilizing a Secure Element or Host
Card Emulation (HCE). In order to minimize the direct integration points, Wallet Providers will integrate with American
Express and American Express will act as an aggregator for Issuers.

This guide also outlines the requirements and guidelines to use the Issuer Bank App Provisioning feature in HCE
Android Pay Wallets. Issuers using this feature will be able to initiate a Tokenization request through their banking
mobile app. For more information on the components required to use this feature, see Bank App Provisioning chapter.

For inf ormation on Apple Pay In-App Provisioning feature, contact your American Express Global Network (AEGN)
representative.

Purpose
This document describes and defines the APIs used for communication between American Express and Issuers.

How to Use this Document

This document is intended to be used in conjunction with the Business and Operational Policies (BOP) and the
Network Technical Specifications manuals. In the event of any conflict between this document and the BOP, the
requirements in the BOP take precedence.

Words that are capitalized have specific meaning in the context of this document and the BOP. Refer to the
Def initions and Acronyms section in this document or the BOP for any word or term in question.

Additional information can be found in the reference documents listed in the following section.

Reference Documents
This document is intended to be used in conjunction with:

• Business and Operational Policies

• Codes Reference Guide

• Network Specifications – Authorization

• Expresspay Mobile Host Card Emulation Specification Version 2.0

• Expresspay Mobile Host Card Emulation Security Requirements Guide

• Host Card Emulation Wallet Provider API Implementation Guide

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 10
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
2 Application Programming Interface Design Philosophy
American Express has defined a set of Application Programming Interfaces to create a standard set of communication
protocols between Wallet Providers, American Express Network, Issuers, and Cardmembers.

• Services from the Issuer will be consumed as Representational State Transfer (REST) /Hyper Text Transfer
Protocol (HTTP) with 2-way Transport Layer Security (TLS).

• Web service requests will use JSON Web Encryption (JWE) for any Personally Identifiable Information (PII)
data elements. The related details are covered in the individual API specifications.

• All requests generated from the Network and sent to the Issuer will have unique tracking ID headers which
can be used for tracking errors.

• Nonf unctional requirements, including availability and response time, will be defined for each API interaction.

• Issuer services can maintain state and can retry different interactions with their downstream systems within
the agreed upon response time.

• API interactions between the Network and Issuer will be via HTTPS Communication protocol.

• Issuer Systems shall be highly available (99.9% uptime for Network interaction).

Endpoint Structure
The entire API outlined in the document can be accessed with the following URI structure.

protocol://host:port/context/version/apiname

• protocol – https

• host:port – Host name and port of American Express

• context – Name of the target system

• version – Version of the API being targeted

• apiname – Name of API being invoked

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 11
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
3 Application Programming Interface (API) Definitions
The tables shown below list the common elements across the APIs in this guide. These elements are included where
applicable for each API included in this document.

NOTE: Components defined in the Bank App Provisioning chapter do not follow this API definition.

Request Common Elements

API requests will have a common header.

Name Type Mandatory Description

Unique identifier for the conversation

• For wallet events, the value received from the
tracking_id String (64) Yes wallet will be used.
• For issuer events, the value received from the
issuer will be used.

token_requestor_id String (11) Yes Identif ier for the Token Requestor.

content-type String Yes Application/json

Response Common Elements

API responses will have a common header.

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 12
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
HTTP Status Codes for API Responses

Status Code Status Description

200 Request processed

202 Request accepted

400 Bad request

500 Internal error

401 Request not authorized

409 Conf lict

Service Level Agreements, Connection, Timeout, and Retries

• The response Service Level Agreement (SLA) for APIs is 1-2 seconds.

• The connection timeout is 3 seconds.

• Retries can be attempted 2 times before disconnect.

Additional Considerations and Requirements

• The payload data exchange format is Java Script Object Notation (JSON).

• The API version can be encoded in the URL to allow routing to the appropriate service version.

• If cache control headers are sent, provider support is at their discretion.

• UTF-8 encoding should be used for every string within the API.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 13
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
4 Network Provisioning Application Programming
Interfaces
As part of the provisioning process, the Wallet Provider will initiate a check eligibility call to the Network. This call will
contain a list of Primary Account Numbers (PAN) linked to a user. The Network will complete a status check for each
Issuer card in the Check Eligibility request. All cards with a negative status will be marked as ineligible. The Network
will send the list of ineligible/negative PANs along with the corresponding reason codes to the Wallet Provider.

Once eligibility is confirmed, Cardmembers enter requested card details including the 4-digit Card Security Code for
the card and accept the Issuer Terms and Conditions (T&Cs) to initiate provisioning.
NOTE: For Card-on-File Token provisioning, the wallet initiates the eligibility check behind the scenes with the details
of the card on file.

The Wallet Provider sends the Provisioning request along with the PAN and Card Security Code that the Cardmember
has added to the wallet. As part of the Provisioning request, the Network sends a Pseudo Auth to the Issuer with the
Card details (PAN, Name on Card, CSC, Expiry, Wallet Provider Score, etc.). The Issuer is expected to do a f raud/risk
assessment and provide a risk score for the Card as well as a decision. If the Issuer decision is positive, the Network
will allocate a Token for the PAN and generate the associated Personalization Script (Perso Script). The Network will
link/activate the Token and once the Perso Script is delivered to the Wallet Provider and the Token has been
provisioned onto the device, the Issuer will be sent a notification from the Network. The provisioning status notification
can be sent over ISO or API.

NOTE: The Issuer Notification API call is relevant only when the Issuer prefers Post Provisioning Notification (PPN)
over API.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 14
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Communication Sequence
The f ollowing diagram depicts the communication sequence for provisioning between the Wallet Provider, Network,
and Issuer.

Wallet Provider Network (AXP) Issuer

Check Eligibility (PAN, Expiry)

Check Eligibility

*Issuer Notification API

(Provision, OBO Card Eligibility Red)

Generate Auth Token

Check Eligibility (T&Cs, PAN, Expiry)

Provisioning Request
(PAN, Auth Token, CID, Wallet Provider Score

AXP Verification (Wallet Provider Score)

ISO 1100 Message

(PAN, Auth Token, CID, Wallet Provider Score)

Issuer
Verification
ISO 1100 Message (PAN, Issuer Score)

Risk Assessment API

Risk Assessment API

Allocate Token

Provisioning Response (token, token_ref, fpan

last five digits, fpan_Id, card art)

Generate Perso Script

Link and Activate Token

Perso Script

Issuer Notification API (pendingauth, success)

Provisioning Status Notification

Validate Provisioning

API Message Calls

ISO Messages

* Issuer notification for Check Card Eligibility failures is optional.

Figure 1: Communication Sequence

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 15
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Eligibility Check API
The Account Eligibility Check API takes a single JWE encrypted Funding Primary Account Number (FPAN) in the
request. The purpose of the API is to determine FPAN eligibility and perform a fraud check to establish the eligibility of
all cards sent in the request. All parameters provided by the Wallet Provider as part of the check card Call will be
passed as part of this Call to the Issuer.

The Network validates the following business rules before sending the request to the Issuer.

• The Wallet status for the given device is active.

• The Card has not been provisioned for the given device.

NOTE: The account eligibility check call to Issuer is optional. Based upon the Issuer preference, if opted, the Network
may complete account eligibility check as an On-Behalf-Of (OBO) service using exception data provided by the
Issuer.

Endpoint
Issuer to provide endpoint for Network to consume.

NOTE: Card-on-File does not utilize the Account Eligibility Check API. All information in this API is part of Risk
Assessment.

Request Header

Name Type Mandatory Description

Unique identifier for the conversation

• For wallet events, the value received from the
tracking_id String (64) Yes wallet will be used.
• For Issuer events, the value received from the
Issuer will be used.

token_requestor_id String (11) Yes Identif ier for the Token Requestor.

content-type String Yes Application/JSON

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 16
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Request Body

Name Type Mandatory Description

JWE encrypted string of the “plain account data

String JSON” object. The “plain account data” JSON
encrypted_account_data Yes
(2048) object will hold the details of the account for which
eligibility needs to be checked.
The device for which Card Eligibility Check is
device_data{} Object Optional
requested.
Field containing information that the Issuer can
use f or eligibility check.
NOTE: Must include fpan_source as one of the
risk parameters.
Possible values include:
risk_assessment_data{} Object Optional • onf ile – Card on Wallet Provider’s file.
• issuerapp – Provisioning via Issuer App.
• userinput – Provisioning via manual input
f rom card member.
• other – For f uture use cases
• blank

Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

The 15-digit account number for which eligibility

account_number String (15) Yes
check needs to be performed.

Risk Assessment Data

risk_assessment_data{}

Name Type Mandatory Description

The Connecting Inf ormation (CI) value passed

connecting_information String (64) Optional f rom the wallet.
NOTE: This f ield is reserved for specific use case.
The source of FPAN being provisioning
Possible values include:
• onf ile – Card on Wallet Provider’s file.
f pan_source String (64) Yes • issuerapp – Provisioning via Issuer App.
• Userinput – Provisioning via manual input
f rom card member.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 17
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 • other – For f uture use cases
• blank

Device Data

device_data{}

Name Type Mandatory Description

device_id String (64) Yes Identif ier of the device.

The identifier of the wallet within the device.

wallet_id String (64) Conditional
NOTE: This is only applicable for HCE Wallets.
This is the type of device attempting Tokenization.
Possible values include:
• phone
• tablet
• watch
• card - Currently not supported, this value is
device_type String (64) Yes reserved f or future use cases.
• wearable
• console
• desktop
• laptop
• other

Response Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

Response Body

Name Type Mandatory Description

Indicates whether the account is eligible for

isEligible Boolean Yes
Tokenization.
The 3-digit reason code indicating ineligibility
reason f or the account. This is applicable only if
ineligibility_reason String (3) Conditional the account is not eligible.
NOTE: The ineligibility reason field is always
associated with Status code – 5216.
Contains metadata information about account in
account_metadata{} Object Yes
question.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 18
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Indicates the market/region where the Card was
market{} Object Yes
issued.

status_code String (4) Yes Status Code

status_message String (128) Yes Description of the status.

Ineligibility Reason Codes

ineligibility_reason()

Status Code Status Description

106 Card has not been activated, replaced, or renewed card has not been activated.

107 Non-whitelisted accounts when a market is at beta test phase.

Ineligible instant account/instant membership account provisioning.

205
NOTE: Optional if the Issuer wants to decline based on tenure of the Card.

Account Metadata

account_metadata{}

Name Type Mandatory Description

display_account_number String (5) Yes Last 5-digits of the account number.

expiry_date String (10) Yes Card expiry date in yyyy-mm-dd format.

Possible options:
• Credit
• Prepaid
product_type String (64) Yes
• Loyalty
• Corporate
• Small Business

product_name String (12) Yes Card product code.

product_short_description String (64) Yes Short description of product.

product_long_description String (128) Yes Long description of product.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 19
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Funding account PAN sequence.
pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.

Market

market{}

Name Type Mandatory Description

Two letter country code. EXAMPLES: US, GB, AU,

country_code String (2) Yes
etc.
Region name is the country name.
region_name String (64) Yes NOTE: For list of possible values, refer to Codes
Reference Guide.
Locale in xx_XX format. The f ormat is based on
xx_XX, where xx refers to Language code and XX
ref ers to Country code. EXAMPLES: en_US, ru_KZ,
locale String (12) Yes en_SA, etc.
NOTE: ISO standard values for the country of the
Issuer. For list of possible values, refer to Codes
Reference Guide.

Response Status Codes

status_code()

Status Code Status Message HTTP Status Code

0000 Success 200

4210 Missing_{fieldname} 200

4211 f ield_length_invalid_{fieldname} 400

4212 account_invalid 404

8999 Internal_server_error 500

5223 Card_locked_out 200

5216 Card_not_eligible 200

5210 Card_market_not_supported 200

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 20
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
5211 Card_product_not_supported 200

5212 Card_data_not_found 200

5213 Card_status_not_supported 200

5201 tokenRequestor_not_supported 200

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 21
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Eligibility Check API Request and Response Example
Request

Header
tracking_id : "uniqueconversationId1654"

Content-Type : application/json
Body
{"encrypted_account_data":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1
c2VySWQiOiJiMDhmODZhZi0zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYm QifQ. -
xN_h82PHVTCMA9vdoHrcZxH-x5mb11y1537t3rGzcM"}

Response

Header
tracking_id : "uniqueconversationId1654"

Body
{
"status_code" : 0000,

"status_message" : "Success",

"isEligible" : true,

"ineligibility_reason" : "",

"market" : {

"country_code" : "US",

"region_name" : "XYZ",

"locale" : "en_US" } ,

"account_metadata" : {

"expiry_date" : "2018-12-30",

"product_type" : "XYZ",

"product_name" : "XYZ",

"product_short_description" : "XYZ Card",

"product_long_description" : "XYZ Card"

“pan_sequence” : “01”
}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 22
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Risk Assessment API
The Risk Assessment API validates an eligible FPAN requesting to be Tokenized for transaction or wallet use. This
call will contain the 4CID entered by the Cardmember and will require Issuer verification and fraud/risk scoring.

The network will validate the following business rules before sending the request to the Issuer.

1. The Wallet status for the given device is active. The device has not been reported as stolen or fraudulent.
NOTE: Network verification of device fraud only occurs if Issuer opts for partial ISO provisioning chec k.

2. The Card has not been provisioned for the given device.

3. The Account Eligibility Check has been performed within six hours.

Endpoint
Issuer provides endpoint for Network to consume.

Request Header

Name Type Mandatory Description

Unique identifier for the conversation

• For wallet events, the value received from the
tracking_id String (64) Yes wallet will be used.
• For issuer events, the value received from the
issuer will be used.

token_requestor_id String (11) Yes Identif ier for the Token Requestor.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account data

JSON" object. The "plain account data" JSON
encrypted_account_data String (2048) Yes
object will hold the details of the account for which
eligibility needs to be checked.
Field containing information that the Issuer can
risk_assessment_data{} Object Yes use f or risk assessment and provisioning
decisions.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 23
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

The 15-digit account number for which eligibility

account_number String (15) Yes
check needs to be performed.

security_code String (4) Yes The 4-digit CSC for the account.

expiry_date String (4) Yes Expiry date of the Card in MMYY format.

Risk Assessment Data

risk_assessment_data{}

Name Type Mandatory Description

The device ID or the Stable Hardware ID to

device_id String (64) Yes
identify the device.
This is the type of device attempting
Tokenization. Possible values include:
• phone
• tablet
• watch
• card – Currently not supported, this value is
device_type String (12) Yes
reserved f or future use cases.
• wearable
• console
• desktop
• laptop
• other
This is the Funding Primary Account Number
f rom the Wallet Provider.
Possible values include:
• ONFILE – Card on Wallet Provider’s file.
• ISSUERAPP – Provisioning via Issuer App.
provider_fpan_source String (64) Optional • USERINPUT – Provisioning via manual input
f rom Cardmember.
• OTHER – For f uture use cases
• STREAMLINE – This value is reserved for
specific use case.
• BLANK

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 24
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Risk Score from Wallet Provider.
Possible values per the provisioning decision
include:
• G (green) – Approval
provider_riskscore String (64) Optional • Y (yellow)– Additional authentication
required f rom the Cardmember. EXAMPLE:
One-Time Password (OTP)
• R (red) – Decline

provider_riskscore_version String (64) Optional Risk Score version from the Wallet Provider.

Risk Reason Codes from the Wallet Provider.

provider_risk_rsncds String (64) Optional NOTE: For list of possible values, refer to Codes
Reference Guide.
Device ID score indicates the trust of the device.
Possible values include a score between 1 to 5
device_id_score String (5) Optional
that indicates trust of the device, with 5 being the
most trusted.
ISO Language Code.
device_language_code String (2) Optional NOTE: For list of possible values, refer to Codes
Reference Guide.
The time zone of the device. EXAMPLE: UTC-
device_time_zone String (32) Optional
07:00
Indicates if the device time zone is set by user
device_timezone_setting Boolean Optional
pref erence.
The Account Score indicates trust of the
account.
account_score String (5) Optional Possible values include a score from 1 to 5 that
indicates trust of the Account, with 5 being the
most trusted.
The Phone Number score indicates trust of the
phone number.
phone_number_score String (5) Optional Possible values include a score from 1 to 5 that
indicates trust of the phone number, with 5 being
the most trusted.

dpan_counts String (2) Optional The number of cards present on the device.

The time when the Cardmember accepted the

terms_cond_acceptance_ts String (64) Optional
Terms & Conditions on the device.

latitude_coordinates String (64) Optional Device latitude coordinates.

longitude_coordinates String (64) Optional Device longitude coordinates.

wallet_userid String (64) Optional The identity of the Wallet user.

device_name String (64) Optional A recognizable device name.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 25
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 Version of the Terms and Conditions accepted by
terms_and_cond_version String (64) Optional
the Cardmember.

source_ip String (64) Optional IP of the source device.

f irst_name String (64) Optional The f irst name of the wallet user.

middle_name String (64) Optional The middle name of the wallet user.

last_name String (64) Optional The last name of the wallet user.

Indicates if the Cardholder name entered by the

cardholder_name_matched Boolean Optional user matched the one on file – applicable for
ONFILE use cases.

street_address String (64) Optional The street address of the Cardmember.

address_city String (64) Optional The city of the Cardmember.

address_region_cd String (64) Optional The region, state, or territory of the Cardmember.

address_iso_ctry_cd String (3) Optional The ISO country code of the Cardmember.

postal_cd String (64) Optional The postal code or zip code of the Cardmember.

phone_iso_dial_ctry_cd String (64) Optional The ISO dial country code.

registered_devices_for_user Integer Optional Number of registered devices for the Cardmember.

devices_with_tokens_ Number of devices with tokens for the

Integer Optional
f or_user Cardmember.
Recommended algorithm version for the account
algorithm_version Integer Optional
score.

email_tenure String (4) Optional The age of the user email address.

wallet_account_tenure String (4) Optional The age of the wallet account.

account_tenure_on_file String (4) Optional The tenure of FPAN of customer file.

The number of weeks since the account ID was

account_id_tenure Integer Optional
created.
The number of weeks since the account
account_age_on_device Integer Optional
registration date on the device.

phone_number String (64) Optional The phone number of the device.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 26
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 This is the identifier of the Wallet initiating the
wallet_identifier String (64) Optional request. NOTE: This is only applicable for HCE
wallets.

device_brand String (64) Optional The brand of the device.

device_manufacturer String (64) Optional The manuf acturer of the device.

mobile_carrier String (64) Optional The mobile network operator type.

os_platform String (64) Optional The Operating System (OS) platform / version.

network_type String (64) Optional The type of network.

The country code of the device at the time of

country_on_device String (64) Optional
provisioning.

country_on_accountId String (64) Optional The country code of the wallet account.

The score based on the number of tokens on the

tokens_on_device_score String (4) Optional
physical device.
The method of account entry.

Possible values for HCE wallets:

• 01 – Manual Entry
• 02 – OCR
• 03 – Unknown
• 04 – OCR edited
• 05 – NFC Reader
• 06 – Issuer Mobile Web (currently not
account_input_method String (64) Optional supported, this value is reserved for future use
cases)
• 07 – Issuer Web (currently not supported, this
value is reserved for future use cases)
• 08 – Issuer Bank App (currently not supported,
this value is reserved for future use cases)

Possible values for Secure Element wallets:

• 1 – Camera
• 2 – Manual
days_since_last_wallet_
Integer Optional The number of days since the last activity.
activity
The number of transactions in the last twelve
wallet_transaction_count Integer Optional
months for the given wallet/device.
The number of provisioning attempts across
provisioning_attempt_count Integer Optional
Issuers in the last 24 hours on the device.
weeks_since_wallet_
Integer Optional The number of weeks since wallet activation.
activation
NOTE: Risk assessment data will change every time a new wallet request is sent.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 27
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

Response Body

Name Type Mandatory Description

This contains metadata information about the

account for which risk assessment was
account_metadata{} Object Optional
requested. The issuer can send this information if
Card Eligibility Check was done by the network.
Indicates the risk score.
• G – green – Approved
• Y – yellow – Additional authentication
required. EXAMPLE: One-Time Password
risk_score String (1) Yes
(OTP)
• R – red– Declined
NOTE: For Card-on-File Tokenization, Issuer
response is R (red) or G (green).
This indicates the reason for the score. This field
will carry the actual reason if the score is R. If the
Issuer is able to process the risk assessment for
the Card, they should return "0000" with the
proper color recommendation. If the color is "R",
they should provide the reason code as
mentioned in the risk_reason field.
Possible values include:
• 001 – Incorrect CID and expiry value.
risk_reason String (3) Conditional • 203 – Card cannot be provisioned due to
invalid status or other reasons.
• 204 – Suspected fraud on card.
• 206 – Cardmember exceeded the maximum
allowed number of cards.
• 207 – Too many tokens on the device.
• 209 – Cardmember exceeded allowed
number of devices.
• Blanks are Red scored due to other f raud
reasons.

status_code String (4) Yes Indicator of the response status.

status_message String (128) Yes Description of the response status.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 28
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Codes

Status Code Status Message HTTP Status Code

4211 Invalid Field Length 400

4212 Account Number Invalid 404

8999 Internal Server Error 500

0000 Success 200

Account Metadata

account_metadata{}

Name Type Mandatory Description

display_account_number String (5) Yes The last 5 digits of the account number.

expiry_date String (10) Yes The Card expiry date in yyyy-mm-dd format.

String
product_long_description Yes The product long description.
(128)
The Card product code used to identify card
product_name String (12) Yes
assets.

product_short_description String (64) Yes The product short description.

The possible product type options include:

• CREDIT
product_type String (64) Yes • PREPAID
• LOYALTY
• SMALL_BUSINESS
Funding account PAN sequence.
pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 29
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Risk Assessment API Request and Response Examples
Request

Header
tracking_id : "uniqueconversationId1654"

token_requestor_id : "30010030273"

Content-Type : application/json

Body
{"encrypted_account_data":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJiMDhmODZhZi0
zNWRhLTQ4ZjItOGZhYi1jZWYzOTA0NjYwYmQifQ. -xN_h82PHVTCMA9vdoHrcZxH-
x5mb11y1537t3rGzcM",

"risk_assessment_data" : {

"provider_fpan_source" : "USERINPUT",

"expiry_date" : "1224",

"provider_riskscore" : "G",

"device_type" : "1",

"device_id_score" : "3",

"f irst_name" : "Test",

"last_name" : "Test",

"device_name" : "iPhone",

"provider_riskscore_version" : "0001.0",

"source_ip" : "126.133.4.97",

"device_language_code" : "en",

"provider_risk_rsncds" : "03,04",

"phone_number" : "09043173104",

"device_latitude" : "+35.25",

"device_longitude" : "+140.27" }
}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 30
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response – Green

Header

tracking_id : "uniqueconversationId1654"

Body

{ "status_code" : 0000,

"status_message" : "Success",

"risk_score " : "G",

"risk_reason " : "" }

Response – Yellow

Header

tracking_id : "uniqueconversationId1654"

Body

{ "status_code" : 0000,

"status_message" : "Success",

"risk_score " : "Y",

"risk_reason " : ""}

Response – Red – Incorrect CID

Header

tracking_id : "uniqueconversationId1654"

Body
{ "status_code" : 0000,

"status_message" : "Success",

"risk_score " : "R",

"risk_reason " : "001"}

"risk_reason " : "207"

}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 31
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
5 One-Time Passcode Services
As part of the Risk Assessment API request, the Issuer can set the Risk Score of a PAN to Pending Authentication.
The Network allocates a Token, but the Token will not be linked or activated. When the Cardmember selects to
activate the Token, the Wallet Provider sends a request to the Network to display the list of Tenured Channels for the
Cardmember.

The Network relays the request to the Issuer and the Issuer provides the list of registered communication channels
which will be displayed to the Cardmember. The Cardmember selects the preferred communication option. Upon
receiving the preferred Communication Channel, the Network generates the One-Time Passcode (OTP) and sends
the generated OTP and the preferred Communication Channel to the Issuer. The Issuer delivers the OTP to the
Cardmember, and the Cardmember enters the OTP into the Wallet. If the Cardmember enters the wrong OTP three
times, the account will be locked and the Cardmember cannot enter the password for the fourth time and will be
directed to contact Issuer’s customer support. The Wallet Provider sends the OTP to the Network for verification.
NOTE: There is no OTP f or Card-on-File Tokenization.

If an OTP is generated to the Cardmember more than ten times within the 24-hour period, they will be directed to
contact Issuer’s customer support upon the eleventh time and the Issuer should not send the SMS tenure channel.

Once the OTP is verified by the Network, the Network activates the Token and sends a notification to the Issuer upon
successful activation.

The Issuer also has the ability to request an OTP override to the Network after having completed the user verification.
In this scenario, the Token will be activated and linked without OTP verification.

NOTE: If more than six hours passes between the initial Issuer Risk Scoring (Provisioning) and the OTP flow, the
Network re-runs the Card Eligibility check. If the Card has been included in the Exception File, then OTP verification
will not proceed. The OTP validity is 10 mins and number of OTP retries is 3.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 32
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Figure 2: One-Time Passcode Flow

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 33
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
One-Time Passcode Management Services
The One-Time Passcode service is consumed by the American Express Network. It is used to fetch various registered
communication channels for a PAN from an Issuer and return a One-Time Passcode security challenge to the Issuer.

Get Tenured Channels API

This API is a service consumed by an American Express Network to obtain a list of official communication channels
(EXAMPLES: phone number for Short Message Service (SMS) or email address) trusted by the Issuer for identification
and verif ication. This list is sent to Wallet Provider to display the choices available on the device to the Cardmember.
This service assists the Cardmember in selecting a preferred channel.

Get Tenured Channels Network Validation

The network validates that the Token is in “PendingActivate” state before the API call is made to the Issuer.

Endpoint
Issuer to provide endpoint for Network to consume.

This API retrieves the list of all Tenured Channels linked to an account.

Request Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

token_requestor_id String (11) Yes Identif ier for the Token Requestor.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account data

JSON" object. The "plain account data" JSON
encrypted_account_data String (2048) Yes
object will hold the details of the account for which
eligibility needs to be checked.

device_data{} Object Optional The device requesting the channels.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 34
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

account_number String (15) Yes The 15-digit account number.

Device Data

device_data{}

Name Type Mandatory Description

device_id String (64) Yes Identif ier of the device.

The identifier of the wallet within the device.

wallet_id String (64) Conditional
NOTE: This is only applicable for HCE Wallets.
This is the type of device attempting Tokenization.
Possible values include:
• phone
• tablet
• watch
• card - Currently not supported, this value is
device_type String (64) Yes
reserved f or future use cases
• wearable
• console
• desktop
• laptop
• other

Response Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 35
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Body

Name Type Mandatory Description

List of communication channels registered with

communication_channels{}[] Object Yes
the account.

status_code String (4) Yes API status code.

status_message String (128) Yes Description of the API status.

Communication Channels

communication_channels{}

Name Type Mandatory Description

A unique identifier for the channel sent in the

Deliver Security Challenge API f or delivering the
identifier String (64) Yes OTP.
NOTE: If Cardmember has no registered
channels, the API sends “CS999” as the identifier.
The type of Communication Channel.
Possible values include:
• EMAIL
• SMS
type String (64) Yes
• CUSTOMERSERVICE
NOTE: If Cardmember has not registered
channels, the API returns
“CUSTOMERSERVICE” as the channel type.

display_value String (64) Yes The channel value displayed to the Cardmember.

Response Codes

Status Code Status Message HTTP Status Code

4510 Missing_{fieldname} 400

4511 f ield_length_invalid_{fieldname} 400

4512 account_number_invalid 404

8999 Internal_server_error 500

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 36
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
7511 no_tenured_channels_available 200

7512 Card_not_eligible 200

Get Tenured Channels API Request and Response Example

Request

Header
tracking_id : "uniqueconversationId1654"

token_requestor_id : "12324343"

Content-Type : application/json

Body
{
"encrypted_account_data" : "eyJraWQiOiIwMSIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJBMjU2S1cifQ.YITq
nQ9aXnunzriU89vAS882uqJx-
VnRDT0Gjrx3dKSHN9z9s2CNw.dArkM2uU7ZMAnwcL.zd9Xo6HgExW9fjFhDKtSqWS6 975U-
XZKcw.27Fn16MnF8LSEECAdCsj4A"
}

Response

HTTP Status: 200

Header
tracking_id : "uniqueconversationId1654"

Body
{
"status_code" : "0000",

"status_message" : "Success",

"communication_channels" : [

{ "identifier" : "+GFBydpLsU+hC7Hr389Uuw==",

"type" : "SMS",

"display_value" : "xxx-xx9-5103" },

{ "identifier" : "YGFBydpLsU+hC7Hr389Uuw==",

"type" : "EMAIL",

"display_value" : "d***********[email protected]"
}
] }

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 37
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Deliver Security Challenge API
This API delivers the One-Time Passcode generated by the Network to the Communication Channel selected by the
Cardmember.

Endpoint
Issuer to provide endpoint for Network to consume.

Request Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

token_requestor_id String (11) Yes Identif ier for the Token Requestor.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account data

JSON" object. The "plain account data" JSON
encrypted_account_data String (2048) Yes
object will hold the details of the account for which
eligibility needs to be checked.

device_data{} Object Yes The device for which OTP is requested.

The One-Time Passcode generated by the

verif ication_code String (15) Yes
Network.

Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

account_number String (15) Yes The 15-digit account number.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 38
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Device Data

device_data{}

Name Type Mandatory Description

device_id String (64) Yes Identif ier of the device.

The identifier of the wallet within the device.

wallet_id String (64) Conditional
NOTE: This is only applicable for HCE Wallets.
This is the type of device attempting Tokenization.
Possible values include:
• phone
• tablet
• watch
• card - Currently not supported, this value is
device_type String (64) Yes reserved f or future use cases.
• wearable
• console
• desktop
• laptop
• other

Response Header

Name Type Mandatory Description

Unique Identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

Response Body

Name Type Mandatory Description

status_code String (4) Yes API status code.

status_message String (128) Yes Description of the API status.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 39
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Codes

Status Code Status Message HTTP Status Code

4530 Missing_{fieldname} 400

4531 f ield_length_invalid_{fieldName} 400

4532 account_number_invalid 404

8999 Internal_server_error 500

5531 invalid_channel_error 404

5533 otp_send_error 503

Deliver Security Challenge API Request and Response Example

Request

Header
tracking_id : "uniqueconversationId1654"
token_requestor_id : "12324343"
Content-Type : application/json

Body
{
"encrypted_account_data" : "eyJraWQiOiIwMSIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJBMjU2S1cifQ.YITq
nQ9aXnunzriU89vAS882uqJx-
VnRDT0Gjrx3dKSHN9z9s2CNw.dArkM2uU7ZMAnwcL.zd9Xo6HgExW9fjFhDKtSqWS6 975U-
XZKcw.27Fn16MnF8LSEECAdCsj4A" "verification_code" : "123456""
}

Response

HTTP Status: 200

Header
tracking_id : "uniqueconversationId1654"

Body
{
"status_code" : 0000,

"status_message" : "Success"
}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 40
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
6 Issuer Notification Application Programming Interface
During the Check Eligibility Call and after the Network performs the Exception File check, the Network will send a
notif ication with the list of negative PANs along with the reason code, provided.

NOTE: This is applicable only if the Issuer opts for On-Behalf-Of (OBO) account eligibility check service.

Once the Card is added in the Wallet for provisioning, a change of status notification is sent to the Issuer through the
notif ication service.

NOTE: The Network will notify the Issuer of all Token status changes. These changes can include Wallet Provider
initiated Life Cycle Management (LCM) events (e.g., Token suspend, resume, unlink).

The Issuer Notification API notifies the Issuer of Token provisioning and LCM events.

Endpoint
POST /tokens/notification

Request Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

token_requestor_id String (11) Yes Identif ier for the Token Requestor.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account data

JSON" object. The "plain account data" JSON
encrypted_account_data String (2048) Yes
object will hold the details of the account for which
eligibility needs to be checked.
JWE encrypted token_data will be present only
f or Life Cycle Management (LCM) and Post
encrypted_token_data String (2048) Optional
Provisioning (PPN) Notifications.
NOTE: This is not present for Red Notifications.
Token metadata information is available only if
token_metadata{} Object Conditional
encrypted_token_data is present.
Details of the device on which Tokenization is
done.
device_data{} Object Yes
NOTE: Not applicable for cloud-based
Tokenization.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 41
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 The possible values include:
• provision – Provisioning Event (Not applicable
f or provisioning over ISO)
• pendingauth – Yellow Flow notification
NOTE: Not an available notification for Card-
notif ication_type String (128) Yes
on-File Tokenization.
• suspend – Suspend Event
• resume – Resume Event
• delete – Cancel / Delete Event
• accountupdate - Account Update Event
Field containing details of the event for which
event_data{} String (1024) Yes
notif ication is initiated.

Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

account_number String (15) Yes The 15-digit account number.

PAN sequence number associated with the

pan_sequence String (2) Yes account. EXAMPLES: 00 (Default Value), 01, 02,
03.

Token Data

token_data{}

Name Type Mandatory Description

token_number String (15) Yes The 15-digit account number.

token_reference String (42) Optional Unique ref erence identifier f or a Token.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 42
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Metadata

token_metadata{}

Name Type Mandatory Description

expiry_date String (10) Yes The Token expiry date in yyyy-mm-dd format.

ef f ective_date String (19) Yes The Token ef fective date.

The status of the Token when notification is

initiated.
The valid values include:
• Active
status String (32) Yes • PendingAuth (Cardmember needs to
complete OTP)
• PendingOverride (Pending Issuer Override)
• Suspended
• Cancelled

Device Data

device_data{}

Name Type Mandatory Description

Unique identifier for the device on which Account

device_id String (64) Yes
is Tokenized.
Unique identifier for the wallet on which account is
wallet_id String (64) Yes Tokenized.
NOTE: This is applicable only for HCE Wallets.

visible_device_id String (64) Optional Visible identifier of the device.

device_model String (64) Optional The model of the device.

This is the type of device attempting Tokenization.

Possible values include:
• phone
• tablet
• watch
device_type String (32) Yes • card - Currently not supported, this value is
reserved f or future use cases.
• wearable
• console
• desktop
• other

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 43
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 device_manufacturer String (128) Optional The name of the device manufacturer.

Event Data

event_data{}

Name Type Mandatory Description

reason String (128) Optional The reason f or the event.

The 4-digit code indicating the status of the event.

status String (4) Yes The status code along with the notification_type
will identify the event.

event_time dateTime Yes Time of Event in ISO 8601 date format.

Initiator of the Event:

event_originator String (128) Yes • Wallet
• Issuer

Event Status Codes

Status Code Description

0000 Event success.

3555 OBO CardEligibility Red

4555 Provision failed due to Fraud.

5001 Provision Failed due to unexpected error.

5002 Provision Failed – CID Lockout.

Response Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 44
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Body

Name Type Mandatory Description

status_code String (4) Yes API status code.

status_message String (128) Yes Description of the API status.

Response Status Codes

Status Code Status Message HTTP Status Code

0000 Success 200

4610 f ield_length_invalid_{fieldname} 400

4620 account_number_invalid 404

8999 Internal_server_error 503

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 45
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Issuer Notification API Request and Response Example
Request

Header
tracking_id : "uniqueconversationId1654"

Content-Type : application/json

Body
{"encrypted_account_data" : "eyJraWQiOiIwMSIsImVuYyI6IkEyNTZHQ00iLCJhbGciOiJBMjU2S1cifQ.YITq
nQ9aXnunzriU89vAS882uqJx-
VnRDT0Gjrx3dKSHN9z9s2CNw.dArkM2uU7ZMAnwcL.zd9Xo6HgExW9fjFhDKtSqWS6 975U-
XZKcw.27Fn16MnF8LSEECAdCsj4A",

"token_metadata" : {

"expiry_date" : "2025-10-01",

"ef fective_date" : "2018-06-30",

"status" : "Active" },

"notification_type" : "delete",

"device_data" : {

"device_id" : "04B1D0FD61C25F02B74628A89C78BE7DCB7AFFFFFFFFFFFC",

"device_type" : "phone"

},

"event_data" : {

"event_time" : "2018-06-29T09:43:58",

"event_originator" : "Wallet",

"status" : "0000"

}}

Response

{
"status_code" : 0000,

"status_message" : "Success"

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 46
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
7 Account Life Cycle Management Application
Programming Interfaces
The American Express Network exposes operations that can be consumed by the Issuer to communicate account
related lif e cycle events of virtual or plastic cards. The life cycle events can be initiated by an Issuer or the
Cardmember and include events that affects the virtual card state. The account life cycle events include update,
cancel, resume, and suspend.

The lif e cycle events for an account or token can be triggered by an Issuer in two different ways:

• Direct access of the “endpoint URL” of the API included in the individual APIs.

• Issuer triggers the Token History API and then uses the HATOES link. Examples can be found in the Token
History Scenarios section.

NOTE: When a HATOES link is used to trigger any LCM event API, the body in the API message could be left blank.

The lif e cycle events are depicted in the figure below.

Figure 3: Life Cycle Management Event Flows

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 47
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Update API
The Account Update API updates account details in the event the plastic card is replaced or there is a product
transf er.

Endpoint
PUT /payments/digital/{version}/provisionings/accounts/

Request Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account data

JSON" object. The "plain account data" JSON
encrypted_account_data String (2048) Yes
object will hold the details of the account for which
eligibility needs to be checked.
JWE encrypted account_data details should be
encrypted_account_data
String (2048) Conditional changed (required if account details in the
_update
account_data object have changed).
Required if metadata details corresponding to
metadata_update String (1024) Conditional f unding account number in account_data has
changed.

Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

account_number String (15) Yes The 15-digit account number.

Funding account PAN sequence.

pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.
Funding account expiry date in yyyy-mm-dd
expiry_date String (10) Yes
f ormat.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 48
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Metadata

metadata_update{}

Name Type Mandatory Description

Required if product has changed, this value is

card_product String (64) Conditional
used to identify asset details for device update.

Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique identifier provided by the requestor.

The time, in milliseconds, taken to process the

processing_time_in_ms Integer Optional
request.
The time the request was received formatted with
received_ts String (128) Optional
ISO 8601 compliant date/time.

Response Body

Name Type Mandatory Description

status_code String (64) Yes API status code.

status_code_type String (128) Yes API status code type.

Status Code and Status Code Type

Status Code Message HTTP Status Code

invalid_{attribute name} invalid_request_error 400

request_not_authorized auth_error 401

internal_api_error system_error 500

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 49
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Update API Request and Response Example
Request

URL: https://dplcmupdatedev.aexp.com/payments/digital/v1/provisionings/accounts

Method: PUT

Header:

Content_Type: application / json

trackingId: 214214

developer_app_name XXXXX5750GlobalAmexMYCA

SSL_CN: WSP.E1.Signing.aexp.com

org_id: "001"

body
{
"encrypted_account_data": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0._3SMrdNyAa1AjGtGqfOWTMxQG73vrAZSqUMk
ob6aAfkhOI1VCGkg1g.6XYwKePwMFGg3w6m.sAYe349_HDsrduOXRBNqRRnTSZGqpu1Wy0c4x_V709bvqTG_1
7uU CBsOE7JxC89rTRL5H6_2DPDg9LnhG81V_Jm8JfirgKnWOoBiwIO0iz ROGw.VzClxIlXztzWdGDPF62FxA",

"encrypted_account_data_update":"eyJraWQiOiJ0ZXN0X2Flc19rZ
XkiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiQTI1NktXIn0.LFNGmVWy
PIr0y_7Kh67BIIpAF6cGfDnBl9scUT3VcjQkOYLOyEHaUg.t8PixGX5D QmJOpVA.BzR3c-qgebd8LH0_gheLzsOc8-
4mV8p73TlFAXwsycqclgahFTLZbJBrCdG0AuxOtbrfwywQ5zmo1KjGwZS1YojKYoisBZwg6GEIp12Zosk4I.UeNZ9B
bvcBr---PMi-vLgA",

"metadata_update": null

Response:

{
“status_code_type”:“UpdateSoftcard in progress”,“

status_code”:“success”
}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 50
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Update API at GUID Level Request and Response Example
GUID is returned in the response to Token History API as HATEOAS links for account level operations. For details,
ref er to the Token History Scenarios in the Token History API section of this guide.

Request

URL: https://dplcmupdatedev.aexp.com/payments/digital/v1/provisionings/accounts/0c758d26- 8a0a-437f-a2fc-

46550ca8e351

Method: PUT

Header:

tracking_id Test0001

Content-Type application/json

body:

{
"encrypted_account_data_update": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0._3SMrdNyAa1AjGtGqfOWTMxQG73vrAZSqUMkob6aAfkhOI1VCGkg1g.6XYwKePwMFGg3w6m.
sAYe349_HDsrduOXRBNqRRnTSZGqpu1Wy0c4x_V709bvqTG_17uU
CBsOE7JxC89rTRL5H6_2DPDg9LnhG81V_Jm8JfirgKnWOoBiwIO0iz ROGw.VzClxIlXztzWdGDPF62FxA"

Response:

“status_code_type”:“UpdateSoftcard in progress”,

“status_code”:“success”

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 51
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Unlock API
The Account Unlock API is used to remove an account level lock established as a result of a provisioning activity.

Endpoint
DELETE /payments/digital/{version}/provisionings/accounts/{GUID}/freeze?unlock=true

Request Header

Name Type Mandatory Description

Content-Type String (64) Yes Application/json

Unique identifier for the request provided by the

tracking_id String (64) Yes
requestor.
Unique identifier for the session provided by the
session_id String (64) Optional requestor.
NOTE: This is not applicable for GNS issuers.
This can be either SSL or the
developer_app_name extracted by American
Express gateway from SSL handshake for WSP
SSL_CN String (64) Optional
and GSP.
NOTE: This is automatically inserted by AXP
request gateway.
This can be either this or the SSL_CN used by
MYCA.
developer_app_name String (64) Optional
NOTE: This is automatically inserted by AXP
request gateway.

org_ID String (64) Conditional This is not required for GNS issuers.

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account data

JSON" object. The "plain account data" JSON
encrypted_account_data String (2048) Yes
object will hold the details of the account for which
eligibility needs to be checked.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 52
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

Funding account number. If the account number

account_number String (64) Yes
does not change for an LCM, this can be ignored.
Funding account PAN sequence.
pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.

Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique identifier provided by the requestor.

The time, in milliseconds, taken to process the

processing_time_in_ms Integer Optional
request.
The time the request was received. ISO 8601
received_ts String (128) Optional
compliant date and time.

Response Body

Name Type Mandatory Description

Details can be found in status code table shown

status_code String (64) Yes
below.
Details can be found in the status code table
status_code_type String (128) Yes
shown below.

Status Code and Status Code Type

Status Code Status Code Type HTTP Status Code

invalid_{attribute name} invalid_request_error 400

no_provisioning_data invalid_request_error 400

account_already_exists Invalid_request_error 400

request_not_authorized auth_error 401

internal_api_error system_error 500

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 53
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Unlock API Request and Response Example
Request

URL: /payments/digital/{version}/provisionings/accounts/freeze?unlock=true

Method: DELETE

Header:

Content_Type: application / json

trackingId: 214214

SSL_CN: XXXXX5750GlobalAmexMYCA SSL_CN: WSP.E1.Signing.aexp.com

org_id: "XXX"

body:

"encrypted_account_data": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0._3SMrdNyAa1AjGtGqfOWTMxQG73vrAZSqUMk
ob6aAfkhOI1VCGkg1g.6XYwKePwMFGg3w6m.sAYe349_HDsrduOXRBNqRRnTSZGqpu1Wy0c4x_V709bvqTG_1
7uU CBsOE7JxC89rTRL5H6_2DPDg9LnhG81V_Jm8JfirgKnWOoBiwIO0iz ROGw.VzClxIlXztzWdGDPF62FxA"

Response:
{

"status_code_type":"",

"status_code":""

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 54
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Suspend API
The Account Suspend API is used by an Issuer when all Tokens linked to an account are required to be suspended.
This might happen if fraud is suspected on the account and the Issuer wants to suspend all the Tokens linked to that
account.

Endpoint
POST /payments/digital/{version]/provisionings/accounts/freeze

Request Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account data

JSON" object. The "plain account data" JSON
encrypted_account_data String (2048) Yes
object will hold the details of the account for which
eligibility needs to be checked.

Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

account_number String (15) Yes The 15-digit account number.

Funding account PAN sequence.

pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 55
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique Identifier provided by the requestor.

The time, in milliseconds, taken to process the

processing_time_in_ms Integer Optional
request.
The time the request was received formatted with
received_ts String (128) Optional
ISO 8601 compliant date/time.

Response Body

Name Type Mandatory Description

status_code String (64) Conditional Only displays in the event of a f ailure.

status_code_type String (128) Conditional Displays if status code is available.

Status Code and Status Code Type

Status_code_type Status_code HTTP Status

invalid_request_error invalid_{attribute_name} 400

auth_error request_not_authorized 401

system_error internal_api_error 500

token_error token_already_deleted 409

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 56
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Suspend API Request and Response Example

Request

URL: https://dplcmupdatedev.aexp.com/payments/digital/v1/provisionings/accounts/0c758d26- 8a0a-437f-a2fc-

46550ca8e351

Method: PUT

Header:

tracking_id Test0001

Content-Type application/json

body:

"encrypted_account_data_update": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0._3SMrdNyAa1AjGtGqfOWTMxQG73vrAZSqUMkob6aAfkhOI1VCGkg1g.6XYwKePwMFGg3w6m.
sAYe349_HDsrduOXRBNqRRnTSZGqpu1Wy0c4x_V709bvqTG_17uU
CBsOE7JxC89rTRL5H6_2DPDg9LnhG81V_Jm8JfirgKnWOoBiwIO0iz ROGw.VzClxIlXztzWdGDPF62FxA"

Response:

“status_code_type”:“UpdateSoftcard in progress”,

“status_code”:“success”

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 57
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Resume API
The Account Resume API reactivates a suspended Token at the account level. This API is used by Issuers to
reactivate previously suspended Tokens as needed.

Endpoint
DELETE /payments/digital/{version}/provisionings/accounts/freeze

Request Header

Name Type Mandatory Description

Unique identifier for the conversation

tracking_id String (64) Yes
between the consumer and the provider.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account

data JSON" object. The "plain account
encrypted_account_data String (2048) Yes data" JSON object will hold the details of
the account for which eligibility needs to be
checked.

Request Data
Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

account_number String (15) Yes The 15-digit account number.

Funding account PAN sequence.

pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 58
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique identifier provided by the requestor.

The time, in milliseconds, taken to process the

processing_time_in_ms Integer Optional
request.
The time the request was received formatted with
received_ts String (128) Optional
ISO 8601 compliant date/time.

Response Body

Name Type Mandatory Description

status_code String (64) Conditional Only displays in the event of a f ailure.

status_code_type String (128) Conditional Displays if status code is available.

Status Code and Status Code Type

Status_code_type Status_code HTTP Status

invalid_request_error invalid_{attribute_name} 400

auth_error request_not_authorized 401

system_error internal_api_error 500

token_error token_already_deleted 409

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 59
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Resume API Request and Response Example
Request

URL: https://dplcmupdatedev.aexp.com/payments/digital/v1/provisionings/accounts/0c758d26- 8a0a-437f-a2fc-

46550ca8e351

Method: PUT

Header:

tracking_id Test0001

Content-Type application/json

body:
{
"encrypted_account_data_update": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0._3SMrdNyAa1AjGtGqfOWTMxQG73vrAZSqUMkob6aAfkhOI1VCGkg1g.6XYwKePwMFGg3w6m.
sAYe349_HDsrduOXRBNqRRnTSZGqpu1Wy0c4x_V709bvqTG_17uU
CBsOE7JxC89rTRL5H6_2DPDg9LnhG81V_Jm8JfirgKnWOoBiwIO0iz ROGw.VzClxIlXztzWdGDPF62FxA"
}

Response:

“status_code_type”:“UpdateSoftcard in progress”,

“status_code”:“success”

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 60
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Delete API
The Account Delete API deletes all linked Tokens at an account level.

Endpoint
DELETE /payments/digital/{version}/provisionings/accounts/

Request Header

Name Type Mandatory Description

Unique identifier for the conversation between the

tracking_id String (64) Yes
consumer and the provider.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted string of the "plain account

data JSON" object. The "plain account data"
encrypted_account_data String (2048) Yes
JSON object will hold the details of the account
f or which eligibility needs to be checked.

Request Data
Plain Account Data JSON Fields

account_data{}

Name Type Mandatory Description

account_number String (15) Yes The 15-digit account number.

Funding account PAN sequence.

pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 61
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique identifier provided by the requestor.

The time, in milliseconds, taken to process the

processing_time_in_ms Integer Optional
request.
The time the request was received formatted with
received_ts String (128) Optional
ISO 8601 compliant date/time.

Response Body

Name Type Mandatory Description

status_code String (64) Conditional Only displays in the event of a f ailure.

status_code_type String (128) Conditional Displays if status code is available.

Status Code and Status Code Type

Status_code_type Status_code HTTP Status

invalid_request_error invalid_{attribute_name} 400

auth_error request_not_authorized 401

system_error internal_api_error 500

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 62
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Delete API Request and Response Example
Request

URL: https://dplcmupdatedev.aexp.com/payments/digital/v1/provisionings/accounts/0c758d26- 8a0a-437f-a2fc-

46550ca8e351

Method: PUT

Header:

tracking_id Test0001

Content-Type application/json

body:

{
"encrypted_account_data_update": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0._3SMrdNyAa1AjGtGqfOWTMxQG73vrAZSqUMkob6aAfkhOI1VCGkg1g.6XYwKePwMFGg3w6m.
sAYe349_HDsrduOXRBNqRRnTSZGqpu1Wy0c4x_V709bvqTG_17uU
CBsOE7JxC89rTRL5H6_2DPDg9LnhG81V_Jm8JfirgKnWOoBiwIO0iz ROGw.VzClxIlXztzWdGDPF62FxA"
}

Response:

“status_code_type”:“UpdateSoftcard in progress”,

“status_code”:“success”

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 63
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
8 Token Life Cycle Management Application Programming
Interfaces
The American Express Network exposes operations that can be consumed by the Issuer to communicate Token
related lif e cycle events. The lif e cycle events can be initiated by an Issuer and include events that affects the status of
a Token. The Token lif e cycle events include suspend, resume, and delete.

Token Suspend API

The Token Suspend API suspends a single Token for an account. If , for example, a device is lost and the
Cardmember needs to suspend the Token linked to the specific device, this API is used.

Endpoint
POST /payments/digital/{version]/provisionings/tokens/freeze

Request Header
Name
Type Mandatory Description

Unique identifier for the conversation

tracking_id String (64) Yes
between the consumer and the provider.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted field containing

encrypted_token_data String (2048) Yes
token_data elements.

Request Data

token_data{}

Name Type Mandatory Description

token_number String (15) Yes The 15-digit Token number.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 64
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique identifier provided by the requestor.

The time, in milliseconds, taken to process the

processing_time_in_ms Integer Optional
request.
The time the request was received formatted with
received_ts String (128) Optional
ISO 8601 compliant date/time.

Response Body

Name Type Mandatory Description

status_code String (64) Conditional Only displays in the event of a f ailure.

status_code_type String (128) Conditional Displays if status code is available.

Status Code and Status Code Type

Status_code_type Status_code HTTP Status

invalid_request_error invalid_{attribute_name} 400

auth_error request_not_authorized 401

system_error internal_api_error 500

token_error token_already_deleted 409

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 65
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Suspend API Request and Response Example
Sample Request Token:

POST

/payments/digital/v1/provisionings/tokens/freeze?sandbox=true HTTP/1.1
Host: dpsandboxupdate-dev.aexp.com

Header:
tracking_id: ConversationID12344

Content-Type: application/json

Body:

{ "encrypted_token_data" : "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0.SNcxYHiv1uOGr77- yXXqcZ7AN697r0N2f2SpIsGedXwX05pu1S_hw.qhX_xvFXgmCMX_
V8.NFmxQ5m7xjXpyG9Y35pYUgnXvniqSsTabgp4_13CQatM_A.a63 Kp0-icnRmGgpjVVXwRA" }

Response:

{“status_code_type”:“suspension in progress”,
“status_code”:“success”
}

Sample Request of TokenRef_Id level:

POST
/payments/digital/v1/provisionings/tokens/DAPLAB0013e004669ee8547 6a876df4a29f9cfa34/freeze?sandbox=true
HTTP/1.1
Host: dpsandboxupdate-dev.aexp.com
tracking_id: conversarionID
Content-Type: application/json

Response:

{“status_code_type”:“suspension in progress”,“
status_code”:“success”}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 66
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Resume API
The Token Resume API reactivates the Token by a CCP/Issuer.

Endpoint
DELETE /payments/digital/{version}/provisionings/tokens/freeze

Request Header

Name Type Mandatory Description

Unique identifier for the conversation

tracking_id String (64) Yes
between the consumer and the provider.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted field containing token_data

encrypted_token_data String (2048) Yes
elements.

Request Data

token_data{}

Name Type Mandatory Description

token_number String (15) Yes The 15-digit Token number.

Response Header

Name Type Mandatory Description

Unique identifier provided by the

tracking_id String (64) Yes
requestor.
The time, in milliseconds, taken to process
processing_time_in_ms Integer Optional
the request.
The time the request was received
received_ts String (128) Optional f ormatted with ISO 8601 compliant
date/time.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 67
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Body

Name Type Mandatory Description

status_code String (64) Conditional Only displays in the event of a f ailure.

status_code_type String (128) Conditional Displays if status code is available.

Status Code and Status Code Type

Status_code_type Status_code HTTP Status

invalid_request_error invalid_{attribute_name} 400

auth_error request_not_authorized 401

system_error internal_api_error 500

token_error token_already_deleted 409

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 68
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Resume API Request and Response Example
Sample Request Token:

DELETE /payments/digital/v1/provisionings/tokens/freeze?sandbox=true
HTTP/1.1
Host: dpsandboxupdate-dev.aexp.com

Header:

tracking_id: ConversationID12344
Content-Type: application/json

Body:

{"encrypted_token_data" : "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWx
nIjoiQTI1NktXIn0.SNcxYHiv1uOGr77-
yXXqcZ7AN697r0N2f2SpIsGedXwX05pu1S_hw.qhX_xvFXgmCMX_V8.NFmxQ5m7xjXpyG9Y35pYUgnXvniqSsTa
bgp4_13CQatM_A.a63 Kp0-icnRmGgpjVVXwRA" } }

Response:

{“status_code_type”:“Resumption in progress”,

“status_code”:“success”

Sample Request of TokenRef_Id level:

DELETE
/payments/digital/v1/provisionings/tokens/DAPLAB0013e004669ee8547
6a876df 4a29f9cfa34/freeze?sandbox=true
HTTP/1.1

Host: dpsandboxupdate-dev.aexp.com

Header:

tracking_id: conversarionID
Content-Type: application/json

Response:

{“status_code_type”:“Resumption in progress”,“
status_code”:“success”}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 69
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Delete API
The Token Delete API cancels a Token.

Endpoint
DELETE /payments/digital/{version}/provisionings/tokens/freeze

Request Header

Name Type Mandatory Description

Unique identifier for the conversation

tracking_id String (64) Yes between the consumer and the
provider.

Content-Type String Yes Application/json

Request Body

Name Type Mandatory Description

JWE encrypted field containing

encrypted_token_data String (2048) Yes
token_data elements.

Request Data

token_data{}

Name Type Mandatory Description

token_number String (15) Yes The 15-digit Token number.

Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique identifier provided by the requestor.

The time, in milliseconds, taken to process the

processing_time_in_ms Integer Optional
request.
The time the request was received formatted
received_ts String (128) Optional
with ISO 8601 compliant date/time.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 70
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Response Body

Name Type Mandatory Description

The account information is included in the

account_information Object Conditional response if the account number has been
Tokenized.
Displays Token information for each provided
tr_inf ormation Object/array Conditional TRID, if the account number has been
Tokenized.

Status Code and Status Code Type

Status_code_type Status_code HTTP Status

invalid_request_error invalid_{attribute_name} 400

auth_error request_not_authorized 401

system_error internal_api_error 500

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 71
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Delete API Request and Response Example
Sample Request Token:

Method:
DELETE /payments/digital/v1/provisionings/tokens?sandbox=true
HTTP/1.1

Host: dpsandboxupdate-dev.aexp.com

Header:

tracking_id: ConversationID12344

Content-Type: application/json

Body:

{"encrypted_token_data" : "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjo
iQTI1NktXIn0.SNcxYHiv1uOGr77- yXXqcZ7AN697r0N2f2SpIsGedXwX05pu1S_hw.qhX_xvFXgmCMX_V8.
NFmxQ5m7xjXpyG9Y35pYUgnXvniqSsTabgp4_13CQatM_A.a63Kp0- icnRmGgpjVVXwRA"} }

Response:

{“status_code_type”:“Cancellation in progress”,
“status_code”:“success”

Sample Request of TokenRef_Id level:

Method: DELETE
/payments/digital/v1/provisionings/tokens/DAPLAB0013e004669ee85476a8 76df4a29f9cfa34?sandbox=true
HTTP/1.1
Host: dpsandboxupdate-dev.aexp.com

Header:
tracking_id: conversarionID

Content-Type: application/json

Response:

{“status_code_type”:“Cancellation in progress”,“
status_code”:“success”}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 72
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
9 Servicing Application Programming Interfaces
Network Servicing APIs provide Issuers with information on Card provisioning status. These APIs will be consumed by
Issuers to derive information regarding Cardmember’s Card provisioning state, Token history, and event history status
inf ormation.

Token History API

The Token History API provides Token details for card accounts and available actions. Request and response
payloads are sent in the JSON data-interchange format and are UTF-8 encoded.

Endpoint
POST / payments/digital/{version}/provisionings/tokens/history/inquiry_result

Time Outs
9 seconds

Request Header

Name Type Mandatory Description

Content_Type String (64) Yes Application/json

tracking_id String (64) Yes Unique identifier for the conversation.

This f ield is only passed by internal American

session_id String (64) Conditional Express consumers.
NOTE: Not applicable for GNS issuers.

Request Body

Name Type Mandatory Description

Token Requestor identifier f or use by a Token

Requestor Client.
trid String (11) Optional
NOTE: Clients such as MYCS, WSP, and
Issuers do not use this field.
JWE encrypted string of the "plain account
data JSON" object. The "plain account data"
JSON object will hold the details of the account
encrypted_account_data Object, array Conditional
f or which token history is been requested.
NOTE: Conditional when card_key is in the
context.
Reserved for clients using an Enterprise Data
card_key String (64) Conditional
Encryption Platform (EDPP) for Card account

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 73
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 numbers. This field is only applicable for
internal American Express client.
NOTE: Not applicable for GNS issuers.
Issuer identifier which is optional for MYCA
org_id String (3) Conditional and required for all others.
NOTE: Not applicable for GNS issuers.
This f ield carries the token_requester_name
search_criteria Object Optional
f ilter. It is the only filter currently supported.

Plain Account Data JSON Fields

account_data{}[]

Name Type Mandatory Description

The accepted values are account_reference and

account_type String (128) Yes
credit_card.
This is required if the Issuer uses an alternate
identifier for the Card account number. If
client_account_ref_id String (64) Conditional
provided, the value will be sent back in the
response.
This is required when the account_type is
credit_card Object Conditional
credit_card.
This is the provider's proxy for Card account
number. Required when account_type is
account_ref_id String (64) Conditional
account_reference. If provided, the value will be
included in the response.

Credit Card

credit_card{}

Name Type Mandatory Description

account_number String (19) Yes Funding account number.

PAN Sequence Number, if provided by the Issuer.

pan_sequence String (2) Yes
EXAMPLES: 00 (Default Value), 01, 02, 03.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 74
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Search Criteria

search_criteria{}

Name Type Mandatory Description

token_requester_name String (128) Yes Token requestor name to identify wallet.

Response Header

Name Type Mandatory Description

tracking_id String (64) Yes Unique identifier provided by the requestor.

Provided to indicate a failure, applicable if there is

status_code String (64) Conditional
a f ailure.

session_id String (64) Conditional The provided identifier from the request.

Content-Type String Yes Application/json

Common Attributes

Name Type Mandatory Description

Provided to indicate a failure, applicable if there is

status_code String (64) Conditional
a f ailure.
Provided to indicate a failure, applicable if there is
status_code_type String (128) Conditional
a f ailure.

Status Code and Status Code Type

Status_code_type Status_code HTTP Status

400
invalid_request_error invalid_{attribute_name}
Bad request
500
system_error Internal_api_error Something went wrong on Provider’s
end.

auth_error request_not_authorized 401

404
No data Found No data f ound
No data f ound

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 75
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Links

Name Type Mandatory Description

Method String (8) Yes HTTP method required for this link.

href String (255) Yes Link f or subsequent interaction.

rel String (128) Yes Relation type for this link.

Name value pair attributes associated with the

target_attributes Object Optional
link.

Token History Scenarios

Scenario Link

Suspend a Token rel: suspend_token

For details refer to: method: POST
Token Suspend href : /payments/digital/{version}/provisionings/tokens/{ token_ref_id}/freeze
Resume a Token rel: resume_token
For details refer to: method: DELETE
Token Resume href : /payments/digital/{version}/provisionings/tokens/{ token_ref_id}/freeze
Delete a Token rel: delete_token
For details refer to: method: DELETE
Token Delete href : /payments/digital/{version}/provisionings/tokens/{ token_ref_id}
Suspend Tokens rel: suspend_all
For details refer to: method: POST
Account Suspend href : /payments/digital/{version}/provisionings/accounts /{GUID}/freeze
Resume Tokens rel: resume_all
For details refer to: method: DELETE
Account Resume href : /payments/digital/{version}/provisionings/accounts /{GUID}/freeze
Delete Tokens rel: delete_all
For details refer to: method: DELETE
Account Delete href : /payments/digital/{version}/provisionings/accounts /{GUID}
Unlock Account rel: unlock_account
For Details refer to: method: DELETE
Account Unlock href : /payments/digital/{version}/provisionings/accounts/{GUID}/lock
rel: update_account
method: PUT
Update Account
href : /payments/digital/{version}/provisionings/accounts /{GUID}
For details refer to:
Account Update
target_attributes : {"account_number": "string", "pan_sequence": "integer",
"card_product": "string"}

NOTE: To use the above HATOES links for each scenario, the requestor must trigger the “Token History API” first and
then use the HATOES links mentioned above for each LCM API events.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 76
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
EXAMPLE: To Unlock Account triggered from the response of the “Token History API”, use the HATOES link: href:
/payments/digital/{version}/provisionings/accounts/{GUID}/lock.

Response Body

Name Type Mandatory Description

The account information is included in the

account_information Object Conditional response if the account number has been
Tokenized.
Displays Token information for each provided
tr_inf ormation Object/array Conditional TRID, if the account number has been
Tokenized.

Response Account Information

account_information{}

Name Type Mandatory Description

client_account_ref_id String (64) Conditional This is the identifier, if provided in the request.

List of account references, if the account is

account_references Object, array Conditional
Tokenized.
This object contains metadata information about
account_metadata Object Optional
the account.
HATEOAS links for subsequent interactions.
links Object, array Yes There are no links provided if the account has no
valid Token and if all Tokens are cancelled.

Account References

account_references{}[]

Name Type Mandatory Description

token_requester_id String (11) Optional Identif ier for the Token Requestor.

token_requester_name String (128) Optional Name of the Token Requestor.

account_ref_id String (64) Optional Proxy for the Card account number.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 77
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Account Metadata

account_metadata{}

Name Type Mandatory Description

display_account_number String (5) Optional Last f our digits of the Card account number.

The Card expiration month in two-digit (MM)

expiry_month Integer Optional
f ormat.
The Card expiration year in f our-digit (YYYY)
expiry_year Integer Optional
f ormat.
Primary account number sequence of the network
pan_sequence String (2) Yes issuer provided account. EXAMPLES: 00 (Default
Value), 01, 02, 03.
Number of failed verification attempts which is
verif ication_failed_attempts Integer Conditional
only applicable if there are f ailed attempts.
This f ield is provided if the account is locked. The
locked_on_ts Timestamp Conditional f ormat is based on ISO 8601 (e.g., 2017-2-
19T14:56:54. 961-07:00).
If the account is enrolled in SRC, the enrollment
src_enrollment_ts String Conditional timestamp is in ISO 8601 (e.g., 2017-02-
19T14:56:54.961-07:00)
SRC enrollment consumer IDs. The ID can be
src_enrollment_id String/array Conditional email or phone number. This is applicable if the
account is enrolled in SRC.

Token Requester Information

tr_inf ormation{}[]

Name Type Mandatory Description

trid String Yes Token Requestor identifier.

token_requester_name String Yes Name of the Token Requestor.

token_requester_display_name String Optional Name of the Token Requestor.

Object, This object contains the Token information

token_information Yes
array f ields.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 78
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Information

token_information{}[]

Name Type Mandatory Description

token_ref_id String (64) Yes Unique identifier used to lookup Token.

Populated for Issuers asking for downstream

token_number String (19) Optional
investigations.
Fields that will be sent here are detailed in the
token_metadata Object Optional
Token Metadata section below.
Fields that will be sent here are detailed in the
status Object Yes
Status section below.
Fields that will be sent here are detailed in the
Form Factor Data section below.
f orm_factor_data Object Conditional
NOTE: Not applicable for Card-on-File
Tokenization.
HATEOAS links for subsequent interactions.
links Object, array Yes There are no links provided if the token is
cancelled.

Status

Name Type Mandatory Description

Possible values include:

• Active
• Cancelled
state String Yes
• Suspended
• Pending Activate
• Pending Provision
Reason code for suspend, resume, and yellow
reason_code String Yes
f low. This is only populated for pending state.
Latest updated timestamp. Format is ISO 8601,
last_updated_ts String Yes
e.g., 2017-02-19T14:56:54.961-07:00.
Possible Values:
• Issuer
last_updated_by String Yes • Token
• Requestor

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 79
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Metadata

token_metadata{}

Name Type Mandatory Description

If true, the Cardmember was involved in

Tokenization of the account.
visible String Optional
If f alse, the Cardmember was not involved in the
Tokenization of the account.

display_token_number String Yes Last f our digits of the Token.

Format is ISO 8601, e.g., 2017-2-

activation_ts Timestamp Yes
19T14:56:54.961-07:00.

account_source String Optional FPAN source during Tokenization.

Form Factor Data

f orm_factor_data{}

Name Type Mandatory Description

device_id String Yes Hardware identifier

wallet_id String Optional Sof tware identifier

visible_id String Optional Visible identifier of the device.

device_model String Optional Model of the device.

Possible Values:
• Phone
• Tablet
• Watch
device_type String Optional • Card - Currently not supported, this value is
reserved f or future use cases.
• Wearable
• Laptop
• Other
Possible Values:
• 01 - Phone
device_type_code String Optional
• 02 - Tablet
• 03 - Watch

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 80
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 • 04 - Card - Currently not supported, this value
is reserved for future use cases.
• 05 - Wearable
• 06 - Laptop
• 99 - Other
Provided by the Token requestor to identify the
device_nickname String Optional Cardmember’s personalized name for the form
f actor.

device_manufacturer String Optional Device Manufacturer name.

device_brand String Optional The brand of the device.

mobile_number String Optional Complete phone number of the device.

os_version String Optional The operating system version number.

os_type String Optional The type of the operating system.

build_number String Optional The operating system build number.

serial_number String Optional The device serial number.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 81
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Token Inquiry API using Card Key Identifier Example Request and
Response
Header:
Content - Type: application / json
Accept – Language: sv
trackingId: 214214
developer_app_name XXXXX5750GlobalAmexMYCA
body
{
"card_key": ["LUX6LSTMBI6DFE3"," P1Y27LAV1KNRCX6"],
"search_criteria":
{
"token_requester_name": "ApplePay"
}
}
Using credit_card with search criteria
Header: Content - Type: application / json
Accept - Language: sv
trackingId: 214214
developer_app_name XXXXX2814NAP
Body
{
"encrypted_account_data": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmM
iOiJBMjU2R0NNIiwiYWxnIjoiQTI1NktXIn0.bVAOBPna0zMGcrWHSYa4 NbJQELSC6xTbz0WJE_JU-
1qk32jWEEPSw.HxirlWR7Sx3TWN6y.oQCMyJVLG2LUHljWDFE1KAUvyx3Rxy4cw
A13sCMU0gQZpUX9beiS0uyaBUa0q_rfCUocbZQ2wAHlmwGQOqDb_p
nmSdkLIHSHNzh33sjjwOdy4QPVFFv6EuQFMs6aZccYLGnotrH0T6tUqz
g6dyr-lovbxe2u171HdcecuCA_- 9QZgvslq7eubXJaX2cf2zswy6VqwSLXCtyeBUY15DLq5Snn8ao6e3CRDC
oiVl61QEGyz_4r6uatTzTjyGO1Pn7p7Y9gfal0M9G_Gr7DJWaJZYYivX0aoK9UKMfaqSWP_1ygRb8QQ.cf8GfLQEzt
pCr0RMZ6wqVg",
"org_id":"001",
"search_criteria":
{
"token_requester_name": "ApplePay"
}
}
Token Inquiry Sample response: [
{
"tr_inf ormation":
[{ "token_information":
[{ "token_ref_id": "TSGPAB0013b410d72d0ad4cbf8737187d4201d191",
"token_number": "3XXXXXXXXXXXXX ",
"token_metadata":
{
"display_token_number": "2606",
"activation_ts": "2018-01-29T06:04:07.548-07:00",
"account_source": "USERINPUT" },
"f orm_factor_data":
{
"device_type": "Phone",
"device_nickname": "Galaxy Note9",
"device_id": "D798A22506ED996A130027A4678D93F4",

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 82
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
"wallet_id": "4b314267753641555147534553543235755643496951 ",
"visible_id": "4282",
"device_model": "SM-N960U",
"device_manufacturer": "samsung" },
},
"status":
{ "state": "Active"
}, "links":
[{ "method": "DELETE",
"href ": "/payments/digital/v1/provisionings/tokens/TSGPAB0013b4 10d72d0ad4cbf8737187d4201d191", "rel":
"cancel_token"
}, { "method": "POST",
"href ": "/payments/digital/v1/provisionings/tokens/TSGPAB0013b4 10d72d0ad4cbf8737187d4201d191/freeze",
"rel": "suspend_token"
}
]
}
],
"trid": "30000000025",
"token_requester_name": "SamsungPay"
},
{ "token_information":
[{ "token_ref_id": "DAPLAB00109e84371ea254f569dc3657f05617281",
"token_number": "3XXXXXXXXXXXXXX",
"token_metadata":
{
"display_token_number": "3605",
"activation_ts": null,
"account_source": "USERINPUT"
},

{
"display_token_number": "3605",
"activation_ts": null,
"account_source":
"USERINPUT"
},
"f orm_factor_data":
{
"device_type": "Phone",
"device_id": "794d9b769990b1b79403",
"visible_id": "6026026026"
},
"status":
{
"state": "Pending Activate",
"reason_code": ""
},
"links"
: [{
"method": "DELETE",
"href ": "/payments/digital/v1/provisionings/tokens/DAPLAB00109e 84371ea254f569dc3657f05617281", "rel":
"cancel_token" }, { "method": "DELETE", "href": "/payments/digital/v1/provisionings/tokens/DAPLAB00109e
84371ea254f 569dc3657f05617281/freeze",
"rel": "resume_token"

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 83
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
}] },
{ "token_ref_id": "DAPLAB0010ed1ac31ad884b41b62100d63bb94821", "token_number": " 3XXXXXXXXXXXXXX ",
"token_metadata": { "display_token_number": "3308", "activation_ts": null,

"account_source": "USERINPUT"
},
"f orm_factor_data":
{ "device_type": "Phone",
"device_id": "46612358dae510aa726b",
"wallet_id": "4b314267753641555147534553543235755643496951",
"visible_id": "6026026026"
},
"status":
{
"state": "Pending Activate",
"reason_code": ""
},
"links":
[{ "method": "DELETE",
"href ": "/payments/digital/v1/provisionings/tokens/DAPLAB0010ed 1ac31ad884b41b62100d63bb94821",
"rel": "cancel_token"
}, { "method": "DELETE",
"href ": "/payments/digital/v1/provisionings/tokens/DAPLAB0010ed 1ac31ad884b41b62100d63bb94821/freeze",
"rel": "resume_token"
}] }],
"trid": "30010030273",
"token_requester_name": "ApplePay" }],
"account_information":
{ "client_account_ref_id": "6009", "account_references": [{ "token_requester_id": "30010030273",
"token_requester_name": "ApplePay", "account_reference_id": "FAPLAB0015c50c2479ae042fd829fd9866c97
3668" }, { "token_requester_id": "30000000025", "token_requester_name": "SamsungPay", "account_reference_id":
"ASGPAB0012554ec3635dc4efeb894c25cb20 1722c" }], "account_metadata": { "display_account_number":
"6009", "expiry_month": "04",
"expiry_year": "2020",
"pan_sequence": "00",
"verif ication_failed_attempts": "0",
"locked_on_ts" : "2018-12-25T10:00:29.481-07:00"
},
"links":
[{ "method": "PUT",
"href ": "/payments/digital/v1/provisionings/accounts/bd4194f5-5089- 463b-b0ad-8ba156b0c412",
"rel": "update_account"
},
{
"method": "POST",
"href ": "/payments/digital/v1/provisionings/accounts/bd4194f5-5089- 463b-b0ad-8ba156b0c412/freeze", "rel":
"suspend_all_tokens"
},
{ "method": "DELETE", "
href ": "/payments/digital/v1/provisionings/accounts/bd4194f5-5089- 463b-b0ad-8ba156b0c412",
"rel": "cancel_all_tokens" }
,{ "method" : "DELETE",
"href " : "/payments/digital/v1/provisionings/accounts/ecd8d401- 386d-4cbf-8e03-d9f0e03d834/freeze?unlock=true",
"rel" : "unlock_account"
}] } }]

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 84
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Event History API Request and Response Example
Sample Request:
URL : https://dplcminquirydev.aexp.com/payments/digital/v1/provisionings/tokens/events/inquiry_ results
Method: POST
Header
Content-Type application/json
tracking_id AMEXTESTConv11110012
developer_app_name XXXXX2814NAP
SSL_CN
Body
{
"encrypted_account_data": "eyJraWQiOiJ0ZXN0X2Flc19rZXkiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiQTI
1NktXIn0.8iju2jq- qs0mzf0MK9vF4h31Qu79e4ppVE3Cz_ZTcbCLvV4CmQlU Sg.0gGkQM8-0-
4FOP2G.ZUPEIRDC4xptdBh8Gyt7YOKfTHVdQQsNPoYBW k5LBOJkLGgSQ7T3cFMZpSRYccxm-PTUz8J6p-
7IPcAJO5-7CU23J0- UiMOzgd54Is2pZitLmIE.CEVF_Nn7e3pn_GhSqO4o_A", "org_id": "744"
}
Sample Response:
{ "events":
[{ "client_account_ref_id":"00001", "event_id": "00128763973891543217407267", "event_name":
"ELIGIBILITY_CHECK", "event_conversation_id": "convbb341629a6696128e2c0", "event_bts": "2018-11-
330T12:30:06.854-07:00", "event_ets": "2018-11-330T12:30:07.272-07:00", "event_origin": "YK",
"event_origin_type": "WALLET", "event_status": "SCS", "event_process": "PROVISIONING", "device_id":
"c144bc6d484a122e534a", "wallet_provider": "YK" }, { "client_account_ref_id":"00001", "event_id":
"00118989260641543217409147", "event_name": "CARD_UPDATION", "event_conversation_id":
"convbb341629a6696128e2c0", "event_bts": "2018-11-330T12:30:09.145-07:00", "event_ets": "2018-11-
330T12:30:09.200-07:00", "event_origin": "YK", "event_origin_type": "WALLET", "event_status": "SCS",
"event_process": "PROVISIONING", "device_id": "c144bc6d484a122e534a", "device_type": "Phone",
"wallet_provider": "YK" }, { "client_account_ref_id":"00001"
"event_id": "00185282590471543217409370",
"event_name": "CARD_VERIFICATION",
"event_conversation_id": "convbb341629a6696128e2c0",
"event_bts": "2018-11-330T12:30:09.432-07:00",
"event_ets": "2018-11-330T12:30:10.329-07:00",
"event_origin": "YK",
"event_origin_type": "WALLET",
"event_reason": "",
"event_status": "SCS",
"event_process": "PROVISIONING",
"device_id": "c144bc6d484a122e534a",
"device_type": "Phone",
"wallet_provider": "YK" },
{ "client_account_ref_id":"00001",
"event_id": "00186656794991543217410429",
"event_name": "DPAN_ALLOCATION",
"event_conversation_id": "convbb341629a6696128e2c0",
"event_bts": "2018-11-330T12:30:10.429-07:00",
"event_ets": "2018-11-330T12:30:10.709-07:00",
"event_origin": "YK",
"event_origin_type": "WALLET",
"event_reason": "", "event_status": "SCS", "event_process": "PROVISIONING", "device_id":
"c144bc6d484a122e534a", "device_type": "Phone", "wallet_provider": "YK" },
{
"client_account_ref_id":"00001", "event_id": "00154271620001543217411064",

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 85
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 "event_name": "SCRIPTING_INITIATION",
"event_conversation_id":
"convbb341629a6696128e2c0", "event_bts": "2018-11-330T12:30:11.066-07:00", "event_ets": "2018-11-
330T12:30:11.085-07:00", "event_origin": "YK", "event_origin_type": "WALLET", "event_reason": "", "event_status":
"SCS", "event_process": "PROVISIONING", "device_id": "c144bc6d484a122e534a", "device_type": "Phone",
"token_number": "3XXXXXXXXXXXXXX ",
"token_ref_id": "DAPLAB001c49e0a149d414e7a89654d68b459a41b ", "token_feature": "YK-US-001-EN-1.2.6.03-
01-CREDIT:WIP", "wallet_provider": "YK" }, { "client_account_ref_id":"00001", "event_id":
"00166734785961543217412358", "event_name": "SCRIPTING_COMPLETION", "event_conversation_id":
"convbb341629a6696128e2c0", "event_bts": "2018-11-330T12:30:11.066-07:00", "event_ets": "2018-11-
330T12:30:12.361-07:00", "event_origin": "YK", "event_origin_type": "WALLET", "event_reason": "", "event_status":
"SCS", "event_process": "PROVISIONING", "device_id": "c144bc6d484a122e534a", "device_type": "Phone",
"token_number": "3XXXXXXXXXXXXXX ", "token_ref_id": "DAPLAB001c49e0a149d414e7a89654d68b459a41b ",
"token_feature": "YK-US-001-EN-1.2.6.03-01-CREDIT:WIP", "token_status":"Pending Provision", "wallet_provider":
"YK" }, { "client_account_ref_id":"00001", "event_id": "00169673427191543217412406", "event_name":
"ACTIVATION", "event_conversation_id": "convbb341629a6696128e2c0", "event_bts": "2018-11-
330T12:30:12.408-07:00", "event_ets": "2018-11-330T12:30:17.783-07:00", "event_origin": "YK",
"event_origin_type": "WALLET", "event_reason": "", "event_status": "SCS", "event_prSampocess":
"PROVISIONING", "device_id": "c144bc6d484a122e534a", "device_type": "Phone", "token_number":
"3XXXXXXXXXXXXXX ", "token_ref_id": "DAPLAB001c49e0a149d414e7a89654d68b459a41b ", "token_feature":
"YK-US-001-EN-1.2.6.03-01-CREDIT:WIP", "token_status":"Active",

"wallet_provider": "YK" },{ "client_account_ref_id":"00002", "event_id": "00169673427191543217412406",

"event_name": "ACTIVATION", "event_conversation_id": "convbb341629a6696128e2c1", "event_bts": " 2018-11-
330T12:30:12.408-07:00", "event_ets": "2018-11-330T12:30:17.783-07:00", "event_origin": "YK",
"event_origin_type": "WALLET", "event_reason": "", "event_status": "SCS", "event_process": "PROVISIONING",
"device_id": "c144bc6d484a122e534b", "device_type": "Phone", "token_number": "3XXXXXXXXXXXXXX ",
"token_ref_id": "DAPLAB001c49e0a149d414e7a89654d68b459a41c" , "token_feature": "YK -US-001-EN-1.2.6.03-
01-CREDIT:WIP", "token_status":"Active", "wallet_provider": "YK" }] }
"event_id": "00185282590471543217409370",
"event_name": "CARD_VERIFICATION",
"event_conversation_id": "convbb341629a6696128e2c0",
"event_bts": "2018-11-330T12:30:09.432-07:00",
"event_ets": "2018-11-330T12:30:10.329-07:00",
"event_origin": "YK",
"event_origin_type": "WALLET",
"event_reason": "",
"event_status": "SCS",
"event_process": "PROVISIONING",
"device_id": "c144bc6d484a122e534a",
"device_type": "Phone",
"wallet_provider": "YK" },
{ "client_account_ref_id":"00001",
"event_id": "00186656794991543217410429",
"event_name": "DPAN_ALLOCATION",
"event_conversation_id": "convbb341629a6696128e2c0",
"event_bts": "2018-11-330T12:30:10.429-07:00",
"event_ets": "2018-11-330T12:30:10.709-07:00",
"event_origin": "YK",
"event_origin_type": "WALLET",
"event_reason": "", "event_status": "SCS", "event_process": "PROVISIONING", "device_id":
"c144bc6d484a122e534a", "device_type": "Phone", "wallet_provider": "YK" }, { "client_account_ref_id":"00001",
"event_id": "00154271620001543217411064", "event_name": "SCRIPTING_INITIATION", "event_conversation_id":
"convbb341629a6696128e2c0", "event_bts": "2018-11-330T12:30:11.066-07:00", "event_ets": "2018-11-
330T12:30:11.085-07:00", "event_origin": "YK", "event_origin_type": "WALLET", "event_reason": "", "event_status":

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 86
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
"SCS", "event_process": "PROVISIONING", "device_id": "c144bc6d484a122e534a", "device_type": "Phone",
"token_number": "3XXXXXXXXXXXXXX ", Issuer Onboarding: Servicing APIs (Sam

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 87
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
10 Bank App Provisioning
Bank App Provisioning allows Cardmembers to add their Card from the banking mobile app to the Digital Wallet
application available on the device, such as HCE Android Pay Wallets.

NOTE: To utilize this provisioning feature, Issuers must work with the HCE Android Pay Wallet Provider to request the
documentation for Bank App provisioning client-side integration. Once the client-side integration is successfully
completed at the Issuer’s end, Issuer banking mobile app will be able to interact with the HCE Android Pay Wallet app
and can initiate the Tokenization request through the Token Requestor Server for Card provisioning.

Cardmember logs into the Issuer mobile banking app and selects the Card to provision. The Issuer will generate the
IssuerData object and pass it to the HCE Android Pay Wallet app available on the device for provisioning of the Card.
The IssuerData object contains the account details (PAN, Expiry, Account Input Method, Source of initiating the
provisioning journey, etc.) of the Card and the IssuerSignatureData which is used by Network/Token Service Provider
(TSP) to verif y if the Tokenization request is initiated by the authorized Issuer bank via the HCE Android Pay wallets.

NOTE: Issuers must follow the IssuerSignatureData Scheme defined in this chapter to generate the cryptogram
signature and sign it. Network validates this cryptogram once provisioning is initiated by HCE Android Pay Wallet app.

Once the HCE Android Pay Wallet app receives the IssuerData object from the Issuer banking mobile app, it sends
the Bank App Provisioning notification to the Token Requestor (TR) server to initiate the Tokenization request for the
eligible PAN/Card. TR server will start the Provisioning API request with Network/Token Service Provider (TSP) and
TSP will verif y the cryptogram signature received in the Bank App Provisioning notification before generating and
allocating a Token for the PAN/Card. TSP/Network will follow the provisioning process to generate and allocate a
Token. Once the Token is generated and allocated to the Card, TSP/Network will send the Token to the TR server
and the TR server will push the Token to the HCE Android Pay Wallet.

HCE Android Pay Token Requestor Token Service Provider/

Issuer Bank App
Wallet Server Network (AXP)
HCE Android Pay Wallet App sends
Sends IssuerData object to HCE Bank App Provisioning notification
Android Pay Wallet App to TR Server TR sends Tokenization request to TSP

Verifies IssuerSignatureData
and allocates Token

TR Server will push the Token to TSP sends the allocated Token to TR
HCE Android Pay Wallet Server

Figure 4: Bank App Provisioning Flow

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 88
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
IssuerData Generation
This object is generated by the Issuer and passed to the HCE Android Pay Wallet app to initiate the Tokenization
request.

IssuerData

issuerData{}

Name Type Mandatory Description

Identif ies the account details of the Card which

AccountData Array Yes
needs to be provisioned.
Identif ies the Issuer Signature generated by the
Issuer which needs to be verified by American
IssuerSignatureData Array Yes Express. Refer to the IssuerSignatureData
Scheme section to generate the cryptogram
signature.

AccountData

AccountData{}

Name Type Mandatory Description

The 15-digit FPAN which will be used for

accountNumber String (32) Yes
provisioning.

expiryDate String (10) Yes Expiry date of the Card account.

Identif ies the Issuer Signature generated by the

Issuer which needs to be verified by American
accountInputMethod String (2) Yes Express.
NOTE: The accountInputMethod field must have
‘03’ f or Bank App Provisioning.
Identif ies whether the account is on file or not.
Possible values include:
onFileIndicator String Optional • Yes
• No
Source of initiating the provisioning journey.
originatorChannel String (32) Yes NOTE: The originatorChannel field must have
‘BANKING APP’ as the value.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 89
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
IssuerSignatureData Scheme
Issuers will generate their own Issuer Signature (Non-OBO) for the Bank App Provisioning use cases of Issuer Cards.

Name Type Mandatory Description

contentInfo Array Yes The JSON body container.

ContentInfo

contentInfo{}

Name Type Mandatory Description

Identif ies the cryptographic mode for the

signatureScheme String (10) Yes
signature. EXAMPLE: Symmetric (Default Value)

contentType String (4) Yes Identif ies the content format. EXAMPLE : JSON

Identif ies the cryptographic parameters, the

EnvelopeData Array Yes
encrypted payload, and the signature.

EnvelopeData

EnvelopeData{}

Name Type Mandatory Description

symmetricDataBean Array Yes Applicable when signatureScheme is Symmetric.

Encrypted version of ASCII Hex Encoded JSON

encryptedDataContentInfo String Yes structure of the cryptogram. (Cryptogram
generation is explained in the Symmetric
DataBean section below.).
Contains the Message Authentication Code
signatureData String Yes
(MAC) calculated over the encryptedContentInfo.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 90
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
SymmetricDataBean

SymmetricDataBean{}

Name Type Mandatory Description

Identif ier for 128-bit Encryption Master Key.

NOTE: Keys for QA and Production
encryptionMasterKeyIndentifier String (32) Yes
environments will be shared offline with the
Issuer.
Identif ier for 128-bit MAC Master Key.
NOTE: Keys for QA and Production
macMasterKeyIndentifier String (32) Yes
environments will be shared offline with the
Issuer.
String (24)
Base64
encryptionDerivationData Yes Random 16-bytes Derivation Data.
encoded, 16
bytes of Hex
String (24)
Base64
macDerivationData Yes MAC Random 16-bytes Derivation Data.
encoded, 16
bytes of Hex
Algorithm for deriving a session key from
the encryptionDerivationData and 128-bit
Encryption Master key.
sessionKeyDerivationAlgorithm String (2) Yes Possible values include:
• 01 – AES128/ECB
• 02 – DES3/ECB
• 03 – DES3/CBC
Algorithm for encrypting data content.
Possible values include:
encryptionContentAlgorithm String (2) Yes • 01 – AES128/CBC/NoPadding
• 02 – AES256/CBC/NoPadding
• 03 – DES3/CBC/NoPadding
MAC algorithm.
Possible values include:
macContentAlgorithm String (2) Yes • 01 – HMAC SHA256
• 02 – ISO 9797-1 Algorithm 3 (4 most
significant bytes)

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 91
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
EncryptedDataContentInfo

encryptedDataContentInfo{}

The data should be a multiple of 128-bits, appended using Hex encoded 00’s.

Name Type Mandatory Description

String (24) A random value to ensure that the

Base64 encoded, encrypted payload value changes even
random Yes
16-bytes of Binary though data being encrypted remains the
Hex. same.
Version number of this content. EXAMPLE:
Version String (3) Yes
1.0 (Def ault Value)
The 15-digit FPAN (Card Account Number),
if the issuersignature generation is Non-
accountNumber String (15) Conditional OBO.
NOTE: Mandatory if acctRefId is not
provided.
Identif ier for the funding Card to generate
the issuersignature, if the issuersignature
acctRefId String (32) Conditional generation is OBO.
NOTE: Mandatory if account_number is not
provided.
Identif ier for the virtual card on the device.
The Network will provide this value.
tokenRefId String (32) Conditional
NOTE: Mandatory if acctRefId is not
provided.
The name of the HCE Android Pay Wallet
app.
tokenRequestorName String (16) Yes Possible values include:
• SamsungPay
• GooglePay

deviceId String (64) Yes Identif ier of the device.

timestamp String (29) Yes Current timestamp.

Format: 2015-02-19T14:56:54.961-07:00

Identif ies that a successful login to the bank

app was completed by the Cardmember.
appLogin String (5) Conditional Possible values include:
• True
• False
Identif ies whether the CSC validation was
cscCheck String (5) Conditional perf ormed.
Possible values include:
• True

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 92
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 • False

Identif ies whether the OTP validation was

perf ormed.
otpCheck String (5) Conditional Possible values include:
• True
• False

Java Code for IssuerData Generation Example

The example is based on the following configuration:

• sessionKeyDerivationAlgorithm: 01

• encryptionContentAlgorithm: 01

• macContentAlgorithm: 01

package issuer.sample;

import org.apache.commons.codec.binary.Base64;
import org.bouncycastle.util.encoders.Hex;

import javax.crypto.Cipher;
import javax.crypto.Mac;
import javax.crypto.spec.IvParameterSpec;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.Key;
import java.security.NoSuchAlgorithmException;

public class IssuerSignatureAESUtils {

private static final byte[] PADDINGBYTES = { -128, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 };

private static final String sessionKeyDerivationAlgorithm = "AES/ECB/NoPadding";
private static final String encContentAlgorithm = "AES/CBC/NoPadding";
private static final String macContentAlgorithm = "HmacSHA256";

private static final String encMasterKey = "202A709BABCD9B2FEAEF7516929713A8";

private static final String macMasterKey = "C25B79432F85C4152A49672394027657";

private static final String encDerivationDataHex =

Hex.toHexString(org.bouncycastle.util.encoders.Base64.decode("9Djw4LTw1en0OA/gtPDV6Q=="));
private static final String macDerivationDataHex =
Hex.toHexString(org.bouncycastle.util.encoders.Base64.decode("9Djw4LTw1en0OA/gtPDV6Q=="));

public static void main(String[] args) throws Exception {

String dataContent = "{\"random\":\"W5zfd8IQ\",\"version\":\"1.0\",\"accountNumber

\":\"3XXXXXXXXXXXXXX\",\"timeStamp\":\"2017-09-
26T18:41:57.977+09:00\",\"appLogin\":\"true\",\"cscCheck\":\"false\",\"otpCheck\":\"false\"}";

byte[] dataContentHex = Hex.decode(asciiToHex(dataContent));

byte[] sessionEncAESKey = deriveSessionKey(sessionKeyDerivationAlgorithm, encDerivationDataHex,
encMasterKey);
byte[] sessionMacAESKey = deriveSessionKey(sessionKeyDerivationAlgorithm, macDerivationDataHex,
macMasterKey);

System.out.println("sessionEncAESKey: "+Hex.toHexString(sessionEncAESKey));

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 93
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 System.out.println("sessionMacAESKey: "+Hex.toHexString(sessionMacAESKey));

byte[] paddedDataContent = pad(dataContentHex, 16);

byte[] encContent = encryptDataContent(sessionEncAESKey, paddedDataContent);

byte[] signature = generateSymmetricSignature(sessionMacAESKey, encContent);

String base64EncContent = Base64.encodeBase64String(encContent);

String base64Signature = Base64.encodeBase64String(signature);

System.out.println("Encrypted data: "+base64EncContent);

System.out.println("Signature: "+base64Signature);

private static byte[] deriveSessionKey(String sessionKeyDerivationAlgorithm, String derivationData,

String masterKey) throws Exception {
return encrypt(sessionKeyDerivationAlgorithm, createAESKey(masterKey), null,
Hex.decode(derivationData));
}

private static byte[] generateSymmetricSignature(byte[] sessionMacKey, byte[]

encContent) throws Exception {

return calculateHMAC(sessionMacKey, encContent);

}

private static byte[] encryptDataContent(byte[] sessionEncKey, byte[] dataContent) throws Exception {

return encrypt(encContentAlgorithm, createAESKey(Hex.toHexString(sessionEncKey)), new byte[16],

dataContent);
}

private static byte[] decryptDataContent(byte[] sessionEncKey, byte[] dataContent) throws Exception {

return decrypt(encContentAlgorithm, createAESKey(Hex.toHexString(sessionEncKey)), new byte[16],

dataContent);
}

private static byte[] calculateHMAC(byte[] macKey, byte[] bData) throws NoSuchAlgorithmException,

InvalidKeyException {
Mac sha256HMACAlg = Mac.getInstance(macContentAlgorithm);
SecretKeySpec secretKey = new SecretKeySpec(macKey, macContentAlgorithm);
sha256HMACAlg.init(secretKey);
return sha256HMACAlg.doFinal(bData);
}

private static byte[] encrypt(String algorithm, Key key, byte[] initializationVector, byte[]
data) throws Exception {
Cipher cipher = Cipher.getInstance(algorithm, "BC");

if(initializationVector ==null){
cipher.init(Cipher.ENCRYPT_MODE, key);
}else{
cipher.init(Cipher.ENCRYPT_MODE, key, new IvParameterSpec( initializationVector));
}
return cipher.doFinal(data);

private static byte[] decrypt(String algorithm, Key key, byte[] initializationVector, byte[]
data) throws Exception {
Cipher cipher = Cipher.getInstance(algorithm, "BC");

if(initializationVector ==null){
cipher.init(Cipher.DECRYPT_MODE, key);
}else{
cipher.init(Cipher.DECRYPT_MODE, key, new IvParameterSpec( initializationVector));

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 94
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 }

return cipher.doFinal(data);

private static byte[] pad(byte[] data, int blockSize){

byte[] paddedData = new byte[(data.length + blockSize) / blockSize * blockSize];

System.arraycopy(data, 0, paddedData, 0, data.length);
System.arraycopy(PADDINGBYTES, 0, paddedData, data.length, paddedData.length - data.length);

return paddedData;
}

private static Key createAESKey(String hexKey) {

return new SecretKeySpec(Hex.decode(hexKey), "AES");
}

private static String asciiToHex(String asciiValue)

{
char[] chars = asciiValue.toCharArray();
StringBuffer hex = new StringBuffer();
for (int i = 0; i < chars.length; i++)
{
hex.append(Integer.toHexString((int) chars[i]));
}
return hex.toString();
}

private static String hexToAscii(String hex){

StringBuilder output = new StringBuilder();
for (int i = 0; i < hex.length(); i+=2) {
String str = hex.substring(i, i+2);
output.append((char)Integer.parseInt(str, 16));
}

return output.toString();
}

private static String getAESKCV(String hexKey) throws Exception{

byte[] kcvInput = new byte[]{0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0};
byte[] kcv = new byte[3];

SecretKeySpec secretKey = new SecretKeySpec(Hex.decode(hexKey), "AES");

byte[] encOutput = encrypt(sessionKeyDerivationAlgorithm, secretKey, null, kcvInput);

System.arraycopy(encOutput, 0, kcv, 0, 3);

return Hex.toHexString(kcv);
}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 95
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Example for JWE Encryption and JWE Decryption of IssuerData Object
//keyId OR kid value, for identifying the payload via JWEHeader values will be shared Amex.
String keyId = "BankApp_prov_issuer_kid_from_amex";

//encryptionKeyInPlainText will be shared by Amex and this need to be converted into AES key
for encrypting the //payload while creating the IssuerData source.

String encryptionKeyInPlainText =
"plaintext_key_value_for_generating_the_AES_provided_by_amex";
final byte[] actualKey = Hex.decode(encryptionKeyInPlainText);
String jsonInput =
"{\"account_data\":{\"account_type\":\"credit_card\",\"client_account_keyref\":\"1599280283\",
\"credit_card\":{\"account_holder_name\":\"JOHN-
DOE\",\"account_number\":\"xxxx73044562001\",\"country_cd\":\"US\",\"expiry\":\"2024-04-
14\",\"language_cd\":\"en\",\"pan_sequence\":\"00\",\"product_cd\":\"NLT\",\"product_type_cd\"
:\"CREDIT\"}}}";

JWEHeader jweHeader = new JWEHeader.Builder(JWEAlgorithm.A256KW,

EncryptionMethod.A128CBC_HS256).keyID(keyId).build();
Payload payload = new Payload(jsonInput);
JWEObject jweObject = new JWEObject( jweHeader, payload);

//Encrypting the JWEObject using 'A256KW' algorithm

jweObject.encrypt(new AESEncrypter(actualKey));
String encryptedPayload = jweObject.serialize();

//Verification of data created

System.out.println("JWEHeader in the JWE Payload is : " + jweObject.getHeader());
System.out.println("Kid in the JWEHeader is : " + jweHeader.getKeyID());
System.out.println("Payload in the JWEObject is : " + jweObject.getPayload());

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 96
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
11 Security and Encryption
The security section outlines the Transport Layer and Data Layer security specifications that the Issuer and American
Express Network must adhere to for a secure data exchange and communications over APIs.

Transport Layer Security

All Issuer initiated inbound and Network initiated outbound APIs use TLS 1.2 as the Transport Layer Security protocol.
Within the Network, two-way TLS is implemented at the American Express gateway.

Two-way Transport Layer Security

For two-way TLS, the Issuer SSL certificates need to be installed on American Express gateway and American
Express gateway certificates need to be installed on Issuer servers for secure communication.

Secure Socket Layer Certificate Exchange

For two-way TLS, test and production certificates will be exchanged offline over American Express secure email
bef ore conducting API connectivity testing.

Data Security
All Personally Identifiable Information (PII) elements in the request and response will be encrypted with direct JSON
Web Encryption (JWE) with a shared symmetric key.

• A256KW is the JWE algorithm used

• A256GCM is the Encryption Method used

Data Security for Bank App Provisioning

IssuerData consisting of AccountData and IssuerSignatureData need to be encrypted with direct JSON Web
Encryption (JWE) with a shared symmetric key.

• A256KW is the JWE algorithm.

• A128CBC_HS256 is the Encryption Method.

• Use JSON compact serialization for the JWE object.

• JSON compact serialize the JWE object to generate the encrypted PII data in the request.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 97
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
JSON Web Encryption Key Exchange
American Express generates an AES 256 bit Key and KID and shares with the Issuer off -line. This is used for key
wrap. The KID can be used for identifying the AES Key.

NOTE: For Issuer Bank App Provisioning feature, Issuer Bank App should pass the encrypted IssuerData object to the
HCE Android Pay Wallet SDK.

Data Encryption
The originating entity (Issuer or American Express) will perform the following steps for all PII elements (example:
account_data) before and request or response is sent.

• Create the plain PII data object populated with required data.

• Generate the JWE header with the required JWE algorithm and EncryptionMethod.

• Set the KID of the AES key in the JWE header.

• JSON Web Encrypt the payload using the pre-shared AES 256 bit key to generate the JWE object.

• JSON compact serialize the JWE object to generate the encrypted PII data in the request / response.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 98
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
JSON Web Encryption Implementation Example
Nimbus Jose is a popular and robust java library that can be used to implement JWE.

import com.nimbusds.jose.*;
import com.nimbusds.jose.crypto.AESDecrypter;
import com.nimbusds.jose.crypto.AESEncrypter;
import org.apache.commons.codec.binary.Hex;

import javax.crypto.SecretKey;
import javax.crypto.spec.SecretKeySpec;

public class TestJWE {

private static final String SHARED_KEY =

"82D85D5625CDB8DED24E635E995196B72745A02D7CA5D99175EE1D96C0E3E496";
private static final String AES_KEY_ID = "test_aes_key";

public static void main(String[] args) throws Exception {

final byte[] actualKey = Hex.decodeHex(SHARED_KEY.toCharArray());

String payload = "{\"some_payload\":\"payload\"}";

//
// Encrypt JWE Token
//
Payload = new Payload(accountData);
JWEHeader = new JWEHeader.Builder(JWEAlgorithm.A256KW,
EncryptionMethod.A256GCM).keyID(AES_KEY_ID).build();
JWEObject = new JWEObject(jweHeader, payload);
jweObject.encrypt(new AESEncrypter(actualKey));
String encryptedPayload = jweObject.serialize();

//
// Decrypt JWE Token
//
JWEObject jweDecryptObj = JWEObject.parse(encryptedPayload);
String kid = jweDecryptObj.getHeader().getKeyID();
SecretKey secretKey = getSecretKeyWithKID(kid);
jweDecryptObj.decrypt(new AESDecrypter(secretKey));
String decryptedPayload =
jweDecryptObj.getPayload().toBase64URL().decodeToString();

System.out.println("jweToken = " + encryptedPayload);

System.out.println("decrypted = " + decryptedPayload);

}
}

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 99
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
12 Glossary of Terms
Term Explanation

A symmetric block cipher selected by the U.S. government to protect classified

Advanced Encryption
inf ormation that is implemented in software and hardware through the world to encrypt
Standard (AES)
sensitive data.
Application Programming A set of functions and procedures allowing access to features or data of an operating
Interf ace (API) system, application, or service.
An (API) Call is a piece of code that requests data from another piece of software on
Call
the internet.
A payment Card bearing an American Express trademark or logo and issued by an
Issuer or an Account number issued by an Issuer, which can be used to purchase
Card
Goods and Services from S/Es on the AEGN and/or to obtain financial services at
ATMs.

Card-on-File The process of collecting and storing payment credentials for future use.

The process of replacing a primary account number (PAN) with a unique payment
Card-on-File Tokenization
token that is restricted in its usage.
(COFT)
EXAMPLES: Restricted to a specific device, merchant, transaction type or channel.

Card Security Code (CSC) Any of several values printed or encoded on the Card and used for fraud prevention.

A Person who has entered into an agreement and established a Card Account with
Cardmember
any Issuer, or whose name appears on a Card.

Cardholder A person whose name appears on a Card.

Cardmember preferred communication method with the issuer. EXAMPLES: SMS,

Communication Channel
email, etc.
Connecting Inf ormation User authentication value, passed during Token Provisioning Request as
(CI) required f or specific markets where there is a local mandate. EXAMPLE : Korea
Customer Care
A service representative helping Cardmembers or issuers with a servicing task.
Prof essional (CCP)

4CID Four-digit Card Security Code.

Dynamic Card Security

A per transaction code with a limited time period.
Code (DCSC)
Dynamic Primary Account A payment element that serves as the logic between an enabled device and a physical
Number (DPAN) card.
When an API interacts with another system, the touchpoints of the communication
Endpoint
channel between an API and a server are known as endpoints.
A f ile of Account numbers to be used by the Network during Stand-In Authorization, for
Exception File which the Issuer has predetermined either an Authorization decision of denial (i.e.,
negative status) or requires special handling (i.e., VIP).

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 100
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
 The physical characteristics of a device, including its size and shape. The most typical
Form f actor f orm factor is the plastic card; however, a mobile phone is an example of a non-
traditional Form Factor.
Funding Primary Account
A representation of the plastic card issued by the issuer.
Number (FPAN)
Globally Unique Identifier A GUID is a 128-bit (16 byte) number used by software programs to uniquely identify
(GUID) the location of a data object.
A term used to describe the capability of a Mobile Device to provide NFC Card
Host Card Emulation
emulation by routing NFC messages to the operating system of the Mobile Device.
The underlying protocol used by the World Wide Web. This protocol defines how
Hyper Text Transf er
messages are formatted and transmitted and what actions Web servers and browsers
Protocol (HTTP)
take in response to various commands.
The primary communications protocol in the internet protocol suite for relaying
Internet Protocol (IP)
inf ormation across network boundaries.
International Organization An international standard-setting body composed of representatives from various
f or Standardization (ISO) national standards organizations.
Any entity (including, without limitation, American Express and American Express
Issuer Entities) authorized by American Express or an American Express Entity to issue a
Card and to engage in the Card Issuing Business.
Java Script Object A method of formatting data so that it can be transmitted from one place to another.
Notation (JSON) The most common use is between a server and a Web application.
JSON Web Encryption
A standardized syntax for the exchange of encrypted data.
(JWE)

Key Identifier (KID) Identif ier for the cryptographic key.

Lif e Cycle Management

The process of managing the entire lifecycle of data from inception through disposal.
(LCM)

Master Key A Cryptographic Key used to derive all other Encryption keys or a group of keys.

A short-range wireless connectivity standard that uses magnetic field induction to

Near Field Communication
enable communication between devices when they are touched together or brought
(NFC)
within a f ew centimeters of each other.
The aggregate of S/Es that accept Cards and the operational, service delivery,
Network systems, and marketing infrastructure that supports them and the American Express
brand.

On-Behalf -Of (OBO) Services offered by Network on behalf of and for the purpose of Issuers.

A One-Time Password (OTP) is a dynamic code provided by the Issuer to the

One-Time Passcode Cardmember. Issuers may utilize OTPs at their discretion as an added source of
(OTP) protection against fraud, typically in the place of a PCSC for Card Not Present
Transactions.
A series of digits used to identify a customer account or relationship. The assigned
number identifies the Card Issuer and the Cardmember Account. The Primary
Primary Account Number
Account Number, which may be embossed onto the Card plastic, is encoded into the
(PAN)
magnetic stripe, stored on the chip of a Chip Card, and printed on the back of the
Card.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 101
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
Post Provisioning
An event triggered by Network to Issuer after provisioning is complete.
Notif ication (PPN)
The process of preparing and equipping a Network to allow it to provide new service to
Provisioning
users.
Representational State An architecture style for designing networked applications. It relies on a stateless,
Transf er (REST) client-server, cacheable communications protocol.
It is a process where an eligible Card that requests to be tokenized for Digital wallet
Risk Assessment
transaction is verified by the Issuer for fraud/risk scoring.

Risk Scoring The outcome of a fraud/risk assessment performed on a Card by the Issuer.

An E-commerce checkout capability that creates a secure and consistent Cardmember

Secure Remote
checkout experience across digital channels, including mobile devices, websites, and
Commerce (SRC)
other connected devices.
Secure Sockets Layer
A computing protocol that ensures the security of data by using encryption.
(SSL)

Service Level Agreement An agreed upon commitment between a service provider and a client.

Short Message Service The most widely used type of text messaging.

Transport Layer Security (TLS) is a security protocol that allows client/server

applications to communicate in a way designed to prevent eavesdropping, tampering,
and message forgery. TLS provides endpoint authentication and communications
Transport Layer Security
privacy over the Internet using cryptography. TLS can be used to create a secure
(TLS)
communication channel between mail servers. When devices such as mail servers
communicate, TLS ensures that no third party may eavesdrop or tamper with the
message.

Tenured Channels A list of communication channels trusted for identification and verification.

A payment element which serves as the logical link between a device and a physical
Token
card PAN.

Tokenization The process by which the PAN is replaced by a surrogate value called Token.

An entity that initiates requests that PANs be Tokenized, by submitting Token

Token Requestor
Requests to a Token Service Provider.
Token Requestor Identifier
An 11-byte code pairing Token Requestor with Token Domain.
(TRID)
A payment system that protects Cardmember banking information and passwords and
Wallet
allows consumers to make safe transactions without using cash.

Wallet Provider A third-party or a Bank who owns a Digital wallet product.

An American Express account that is selected to conduct controlled testing before

Whitelisted Account
launch.

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 102
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
13 Acronyms
Acronym Term

AEGN American Express Global Network

AES Advanced Encryption Standard

API Application Programming Interface

AXP American Express

CCP Customer Care Professional

CI Connecting Inf ormation

4CID 4 Digit Card Security Code

COFT Card-on-File Tokenization

CSC Card Security Code

DPAN Dynamic Primary Account Number

EDPP Enterprise Data Provisioning Platform

FPAN Funding Primary Account Number

GNS Global Network Services

HATEOAS Hypermedia as the Engine of Application State

HCE Host Card Emulation

HEX Hexadecimal Format

HTTP Hyper Text Transf er Protocol

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 103
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
IP Internet Protocol

ISO International Organization for Standardization

JSON Java Script Object Notation

JWE JSON Web Encryption

KID Key Identifier

LCM Lif e Cycle Management

MAC Message Authentication Code

MYCA Manage Your Card Account

NFC Near Field Communication

OBO On-Behalf -Of

OCR Optical Character Reader

OS Operating System

OTP One-Time Passcode

PAN Primary Account Number

PPN Post Provisioning Notification

SLA Service Level Agreement

SMS Short Message Service

SRC Secure Remote Commerce

SSL Secure Sockets Layer

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 104
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.
REST Representational State Transfer

T&C Terms and Conditions

TLS Transport Layer Security

TRID Token Requestor Identifier

MARCH 2021 This document contains sensitive, confidential, and trade secret information, and may 105
not be disclosed to third parties without written consent of American Express Travel
Related Services Company, Inc.