Amex Express Checkout Guide

Accept payments via Amex Express Checkout without modifying your existing Stripe integration.

American Express cardholders can use their online account details to pay using the Amex Express Checkout button on your site. It’s both secure and convenient for the customer as no card details are provided.

American Express creates a card token that is linked to the customer’s card and works with your existing Stripe integration to create a charge. This token also contains the customer’s information—such as their name, billing address, email, and phone number.

Integrating the Amex Express Checkout button

To get started, first generate your Amex Express Checkout client ID in the Dashboard. After obtaining this, load the helper library from American Express on your checkout page:

<script src="https://icm.aexp-static.com/Internet/IMDC/US_en/RegisteredCard/AmexExpressCheckout/js/AmexExpressCheckout.js"></script>
<script src="https://icm.aexp-static.com/Internet/IMDC/US_en/RegisteredCard/AmexExpressCheckout/js/AmexExpressCheckout.js"></script>

Before the checkout button can be displayed, it needs to be configured using an <amex:init> tag. This tag must be placed within your checkout page before the helper library is loaded:

<amex:init client_id="{CLIENT_ID}" env="production" callback="aecCallbackHandler"/>
<amex:init client_id="{CLIENT_ID}" env="production" callback="aecCallbackHandler"/>

The <amex:init> tag requires the following parameters:

Parameter	Description
`client_id`	Your Amex Express Checkout client ID
`env`	The environment that the checkout button uses (production or qa). Default is production
`callback`	A function that handles the JSON object returned by Amex Express Checkout

An example callback function you can use when accepting payments using Amex Express Checkout:

function aecCallbackHandler(response) {
  // Get the token ID:
  var token = response.token;
  if (response.token) {
    // Insert the token ID into the form so it is submitted to the server:
    $form.append($('<input type="hidden" name="stripeToken">').val(token));
  }
  // Submit the form:
  $form.get(0).submit();
};
function aecCallbackHandler(response) {
  // Get the token ID:
  var token = response.token;
  if (response.token) {
    // Insert the token ID into the form so it is submitted to the server:
    $form.append($('<input type="hidden" name="stripeToken">').val(token));
  }
  // Submit the form:
  $form.get(0).submit();
};

The string response.token represents the ID of a token. You can refer to the Stripe.js reference for further information on using a callback function.

The amex:init tag also accepts some configuration options to change the appearance of the button:

Option	Description
`theme`	The button theme (desktop or mobile). Default is desktop.
`button_color`	The color of the checkout button (dark or light). Default is dark.

Embedding and customizing the button

When you load the American Express JavaScript library, it will insert the button into the DIV with an ID amex-express-checkout. Place this HTML where you want the button to appear.

<div id="amex-express-checkout"></div>
<div id="amex-express-checkout"></div>

The button is only shown if the customer’s browser is supported. Amex Express Checkout supports all recent desktop and mobile browsers.

The card token

The token created by Amex Express Checkout is used in the same way as other tokens. It can be charged or attached to a customer for repeated charging. An example card token is:

{
  "id": "tok_6gpp55Fir1Ca8u",
  "livemode": true,
  "created": 1438056436,
  "used": false,
  "object": "token",
  "type": "card",
  "card": {
    "id": "card_6gpqVeoHsV3beV",
    "object": "card",
    "last4": "1234",
    "brand": "American Express",
    "funding": "credit",
    "exp_month": 7,
    "exp_year": 2022,
    "fingerprint": "5q9AI2LPS47YQtLX",
    "country": "US",
    "name": "CHRISTINE ROBERTS",
    "address_line1": "1 DR. CARLTON B. GOODLETT PLACE",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94110",
    "address_country": "US",
    "cvc_check": null,
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "tokenization_method": "amex_express_checkout",
    "metadata": {
      "phone": "5555551212",
    }
  },
  "email": "foo@example.com",
  "client_ip": "192.0.2.1",
  "usage": null
}
{
  "id": "tok_6gpp55Fir1Ca8u",
  "livemode": true,
  "created": 1438056436,
  "used": false,
  "object": "token",
  "type": "card",
  "card": {
    "id": "card_6gpqVeoHsV3beV",
    "object": "card",
    "last4": "1234",
    "brand": "American Express",
    "funding": "credit",
    "exp_month": 7,
    "exp_year": 2022,
    "fingerprint": "5q9AI2LPS47YQtLX",
    "country": "US",
    "name": "CHRISTINE ROBERTS",
    "address_line1": "1 DR. CARLTON B. GOODLETT PLACE",
    "address_line2": "",
    "address_city": "SAN FRANCISCO",
    "address_state": "CA",
    "address_zip": "94110",
    "address_country": "US",
    "cvc_check": null,
    "address_line1_check": "unchecked",
    "address_zip_check": "unchecked",
    "tokenization_method": "amex_express_checkout",
    "metadata": {
      "phone": "5555551212",
    }
  },
  "email": "foo@example.com",
  "client_ip": "192.0.2.1",
  "usage": null
}

American Express provides the name and billing address of the customer. The customer’s first name will be truncated to ten characters if it is longer than that. The customer’s email address and phone number are also provided, if available.

Testing Amex Express Checkout

When testing Amex Express Checkout with a test mode client ID, you can use the following American Express QA credentials to perform a test transaction:

Username: test_user
Password: password
One-time access code: 123456