availability

Amex Express Checkout has been replaced with the latest unified checkout experience offered through Visa known as Secure Remote Commerce (SRC). If you were previously using Amex Express Checkout, you will need to integrate with SRC.

SRC is currently in a limited release to eligible merchants, and the API is subject to change. It is only available for our Android v3, Android v2, iOS v4, and JavaScript v3 SDKs.

Contact us to request access to the release.

Include Braintree.js

The Amex Express Checkout integration relies on Braintree's JavaScript SDK. If you haven't already integrated, please refer to our Client SDK documentation to include Braintree.js in your webpage. Specifically for this integration, you will need to use the american-express component.

Include the American Express script

To insert the Amex Express Checkout button in your checkout page, include the American Express script in your HTML and initialize it.

HTML
<html>
  <body>
    <amex:init client_id="merchant_client_id" env="qa" callback="handleAmexResponse"></amex:init>
    <amex:buy key_name="client_key" key_value="merchant_client_key"></amex:buy>
    <div id="amex-express-checkout"></div>

    <!-- Place this script tag at the bottom of your document before the closing </body> tag -->
    <script src="https://icm.aexp-static.com/Internet/IMDC/US_en/RegisteredCard/AmexExpressCheckout/js/AmexExpressCheckout.js"></script>
  </body>
</html>

You can find your merchant_client_id and merchant_client_key in the Braintree Control Panel:

  1. Log into the Control Panel
  2. Click on the gear icon in the top right corner
  3. Click Processing from the drop-down menu
  4. Scroll to the Payment Methods section
  5. Next to Amex Express Checkout, click the Options link

To use Amex Express Checkout in the sandbox environment, change the env parameter of the amex:init tag from production to qa, indicating to Amex that you will be using their QA environment.

You can change the appearance of the Amex button by adding parameters to the amex:init tag:

Parameter Description
theme Theme may be "desktop" (default) or "mobile"
button_color Button color may be "dark" (default) or "light"
note

American Express provides a list of Brand Requirements for all merchants implementing Amex Express Checkout on their websites. Please review these requirements prior to going live.

Create the global callback handler

JavaScript
function handleAmexResponse (object) {
  // Send object.nonce to your server
}

The callback function must be on the window scope and defined in a <script> that is executed before the Amex JS. The nonce returned from American Express is a standard payment method nonce. You can use this nonce to create a transaction on your server.

Retrieve cardmember details

American Express provides you with information about the cardmember when they use Amex Express Checkout. You can retrieve this information from Amex by passing the nonce to Braintree's SDK as follows:

braintree.client.create({
  authorization: 'CLIENT_TOKEN_FROM_SERVER'
}, function (clientErr, clientInstance) {
  if (clientErr) {
    // Handle error in client creation
    return;
  }

  braintree.americanExpress.create({
    client: clientInstance
  }, function (amexErr, americanExpressInstance) {
    if (amexErr) {
      // Handle error in American Express component creation
      return;
    }

    americanExpress.getExpressCheckoutProfile({nonce: "NONCE_FROM_AMEX"}, function (ecErr, payload) {
      if (ecErr) {
        // Handle error communicating with Braintree
        return;
      }

      // Handle payload
    });
  });
});

If no profile data is found for the specified nonce, you’ll receive a payload object that matches the following:

JavaScript
{
  error: {
    message: 'Profile not found'
  },
  fieldErrors: [],
  status: 404
}
note

This will be an error in the payload argument, not the err argument; this is because it is an error from American Express, not directly from Braintree.

Profile payload

The profile object contains a single field, amexExpressCheckoutCards, which is an array containing the customer’s Amex Express Checkout card. There will only be one item in this array. The card will contain the following fields:

Field Name Description Example
expirationDate ^ Expiration date of the Amex Express Checkout card (may differ from physical card) "06/20"
cardMemberNumber Last 4 digits of the card member’s physical card "1008"
firstName First name "Jane"
lastName Last name "Smith"
cardMemberExpiryDate Expiration date of the card member’s physical card "02/16"
emailAddress ^ Email "name@domain.com"
smsPhoneNumber ^ SMS number "5551234567"
homePhoneNumber ^ Home number "5551234567"
mobileNumber ^ Mobile number "5551234567"
dateOfBirth *^ Date of birth "1900-10-20"
gender *^ Gender "M"
expressCheckoutCardId Unique ID of the Amex Express Checkout card "159a60dd-3fd3-4043-92b6-1397dbb8c0f2"
memberSince *^ How long has this member been an American Express customer? "2008-12-20"
mrIndicator *^ Does this member participate in American Express Membership Reward Points? "Y"
cardMemberBillingAddress Billing address (see below)

* These fields are only available to merchants who have been approved by American Express for their specific implementation.

^ These fields may not be available for every customer.

Billing address fields

Field Name Example
addressLine1 "123 Main St"
addressLine2 ^ "Suite 123"
addressLine3 ^ "Unit A"
zipCode "123456789"
city "Chicago"
state "IL"
countryCode "US"

^ These fields may not be available for every customer.

For more information on the american-express component, see the JavaScript reference.

Next Page: Server-Side Implementation →