American Express SafeKey

American Express SafeKey is the authentication service in the American Express card network that uses the 3-D Secure protocol to validate customers at checkout. When you request an authorization using a supported card type and a supported processor, you can include payer authentication data in the request.
Before implementing payer authentication for American Express SafeKey, contact customer support to have your account configured for this feature.

Fields Specific to the American Express SafeKey Use Case

These API fields are required specifically for this use case.
consumerAuthenticationInformation.cavv
Required when payer authentication is successful.
processingInformation.commerceIndicator
Set this field to one of these values:
  • aesk
    : Successful authentication (3-D Secure value of
    05
    ).
  • aesk_attempted
    : Authentication was attempted (3-D Secure value of
    06
    ).
  • internet
    : Authentication failed or was not attempted (3-D Secure value of
    07
    ).

Processor-Specific Requirements

Visa Platform Connect
processingInformation.authorizationOptions. transaction
Required only for merchants in Saudi Arabia.

Endpoint

Production:
POST
https://api.cybersource.com
/pts/v2/payments
Test:
POST
https://apitest.cybersource.com
/pts/v2/payments

Required Fields for Processing an Authorization Using American Express SafeKey

These fields must be included in a request for an authorization with American SafeKey. The values for these fields are in the response from the payer authentication validate service. When you request the payer authentication validate and authorization services together, the data is automatically passed from one service to the other.
IMPORTANT
When relaxed requirements for address data and the expiration date are being used, not all fields in this list are required. It is your responsibility to determine whether your account is enabled to use this feature and which fields are required. For details about relaxed requirements, see Relaxed Requirements for Address Data and Expiration Date in Payment Transactions.
clientReferenceInformation.code
consumerAuthenticationInformation.cavv
consumerAuthenticationInformation.eciRaw
Required when the payer authentication validation service returns a raw unmapped ECI value.
orderInformation.amountDetails.currency
orderInformation.amountDetails.totalAmount
orderInformation.billTo.address1
orderInformation.billTo.administrativeArea
orderInformation.billTo.country
orderInformation.billTo.email
orderInformation.billTo.firstName
orderInformation.billTo.lastName
orderInformation.billTo.locality
orderInformation.billTo.postalCode
paymentInformation.card.expirationMonth
paymentInformation.card.expirationYear
paymentInformation.card.number
paymentInformation.card.type
processingInformation.commerceIndicator
Set this field to one of these values:
  • aesk
    : Successful authentication (3-D Secure value of
    05
    ).
  • aesk_attempted
    : Authentication was attempted (3-D Secure value of
    06
    ).
  • internet
    : Authentication failed or was not attempted (3-D Secure value of
    07
    ).
American Express SafeKey

Optional Field for Processing an Authorization Using American Express SafeKey

This field is optional in a request for an authorization with American Express SafeKey. The value for this field is in the response from the payer authentication validate service. When you request the payer authentication validate and authorization services together, the data is automatically passed from one service to the other.
consumerAuthenticationInformation.xid
American Express SafeKey

REST Example: Processing an Authorization Using American Express SafeKey

Request
 {
    "clientReferenceInformation": {
       "code": "TC50171_3"
    },
    "processingInformation": {
        "commerceIndicator": "aesk"
    },
    "paymentInformation": {
        "card": {
        "number": "3400000XXXXXXX8",
        "expirationMonth": "01",
        "expirationYear": "2025"
     }
   },
     "orderInformation": {
        "amountDetails": {
        "totalAmount": "100",
        "currency": "USD"
     },
     "billTo": {
        "firstName": "John",
        "lastName": "Smith",
        "address1": "201 S. Division St._1",
        "locality": "Foster City",
        "administrativeArea": "CA",
        "postalCode": "94404",
        "country": "US",
        "email": "[email protected]",
        "phoneNumber": "6504327113"
      }
    },
        "consumerAuthenticationInformation": {
        "cavv": "1234567890987654321ABCDEFabcdefABCDEF123",
        "xid": "1234567890987654321ABCDEFabcdefABCDEF123"
        }
    }
Response to a Successful Request
{
  "_links": {
    "authReversal": {
      "method": "POST",
      "href": "/pts/v2/payments/6783071542936193303955/reversals"
    },
    "self": {
      "method": "GET",
      "href": "/pts/v2/payments/6783071542936193303955"
    },
    "capture": {
      "method": "POST",
      "href": "/pts/v2/payments/6783071542936193303955/captures"
    }
  },
  "clientReferenceInformation": {
    "code": "TC50171_3"
  },
  "id": "6783071542936193303955",
  "orderInformation": {
    "amountDetails": {
      "authorizedAmount": "100.00",
      "currency": "USD"
    }
  },
  "paymentAccountInformation": {
    "card": {
      "type": "003"
    }
  },
  "paymentInformation": {
    "accountFeatures": {
      "currency": "usd",
      "balanceAmount": "70.00"
    },
    "tokenizedCard": {
      "type": "003"
    },
    "card": {
      "type": "003"
    }
  },
  "pointOfSaleInformation": {
    "terminalId": "111111"
  },
  "processorInformation": {
    "approvalCode": "888888",
    "networkTransactionId": "123456789619999",
    "transactionId": "123456789619999",
    "responseCode": "100",
    "avs": {
      "code": "X",
      "codeRaw": "I1"
    }
  },
  "reconciliationId": "62427259FEYR18Q2",
  "status": "AUTHORIZED",
  "submitTimeUtc": "2023-03-08T20:25:54Z"
}
American Express SafeKey