Overview Guide

README

The information below is designed to help you implement American Express Flexible Rewards. We have outlined the steps to give you a sense of what to expect. As always, we are here to help so feel free to contact us at any stage of the process.

Prerequisite

  1. Merchant needs to share their domain names for all the environments with the American Express.
  2. American Express should whitelist those domains and then merchant can start the integration process.

The Integration Process

  1. The Merchant creates the JSON Object containing all required parameters.
  2. Merchant will include the JavaScript library provided below and put Flexible Rewards placeholder on same page as per given instructions.
  3. After successful implementation, American Express
    login button
    will be enabled.
  4. The login button will drive the Card Member to the American Express
    login page.
  5. The Card Member enters their americanexpress.com username and password.
  6. American Express will authenticate the respective Card Member details.
  7. After successful authentication, it will return unique identity for respective Card Member via a query string to the Merchant after taking the Card Member to the page specified in the callback parameter.
  8. In the case of a failed authentication, the Card Member will be returned to the page where the Amex button was enabled. An error message will appear as a query string.

Adding the Enrollment Window

The American Express Flexible Rewards JavaScript provides an easy-to-use and secure way of integrating client-side functionality into your existing experience. Add this code snippet before the </body> tag on the page where you want to have the American Express Flexible Rewards window.

JSON Request Object

fre.init({
 "partner_id": "M000000001",
 "context_id": "5menrq33qy7n7eprtedg1s",
 "locale": "en_US",
 "country": "US",
 "callback": "YourHomepageURL"
});

Enrollment Placeholder

<div id="amex-frenroll-placeholder"></div>

Include JavaScript Library

<script src="https://flexpartnerlogin.americanexpress.com/js/1.0/FRE.min.js" integrity="integrity="sha384-sgaRGRIVslerwgKJ432lKJg3">


American Express requests all JavaScript files provided by American Express should be used with Subresource Integrity check. Subresource Integrity (SRI) is a security feature that enables browsers to verify that third-party resources they fetch (for example, from a CDN) are delivered without unexpected manipulation. Please include the integrity hash in an inline script.

American Express Flexible Rewards has two environments. Each environment has its own javascript library to integrate.

QA(E2) Environment

Please include below JavaScript library for QA:

<script src="https://flexpartnerlogin-qa.americanexpress.com/js/1.0/FREE2.min.js" integrity="sha384-sgaRGRIVslerwgKJ432lKJg3">


Production(E3) Environment

Please include below JavaScript library for Production:

<script src="https://flexpartnerlogin.americanexpress.com/js/1.0/FRE.min.js" integrity="sha384-sd5236gdsherwgKJ4ad62lKJg3>


Parameters

The following table highlights the parameters involved.

Parameter Type Required Description
partner_id string Yes This parameter is unique Merchant ID for API use provided by American Express.
e.g. M000000001
context_id string Yes Unique tracking ID, generated by the Merchant and will be treated by American Express as a pass-through parameter. It allows the Merchant to uniquely identify requests and responses. Note: Only alphanumeric characters are allowed.
e.g. 5menrq33qy7n7eprtedg1s
locale string No Indicates the language that needs to be displayed,
e.g. en_US
country string No Indicates the country (ISO ALPHA-2 Code) where the Merchant site is shown,
e.g. US
callback string Yes The callback parameter should be the homepage Card Member will redirect to on successful log in.
e.g., "YourHomepageURL"

Once the script and JSON Request Object are implemented, your page should look similar to the code below:

<html>
<head>
   ...
</head>
<body> ... <div id="amex-frenroll-placeholder"></div>
   ...
<script>

fre.init({
 "partner_id": "M000000001",
 "context_id": "zmnutzvznqdsvuswds7gj",
 "locale": "en_US",
 "country": "US",
 "callback": "YourHomepageURL",
});

</script>

<script src="https://flexpartnerlogin.americanexpress.com/js/1.0/FRE.min.js" integrity="sha384-sgaRGRIVslerwgKJ432lKJg3> </body>
</html>

Retrieve Response Information

Once response_data is returned, the Merchant can use unique identity identifier for the respective Card Member.

The response will appear in the URL as such:

Successfull Enrollment response_data will be as below:

{
 'contextId': '5menrq33qy7n7eprtedg1s',
 'walletId': 'zmnutzvznqdsvuswds7gj'
}

Not Eligible Enrollment response_data will be as below:

{
 'contextId': '5menrq33qy7n7eprtedg1s',
 'error': {code: 'NOT_QUALIFIED' , message: 'Sorry, this American Express Card account is not eligible.'}
}

Partner Not Found response_data will be as below:

{
 'contextId': '5menrq33qy7n7eprtedg1s',
 'error': {code: 'PARTNER_NOTFOUND' , message: 'Partner is not configured for the Flexible Rewards program.'}
}

Failed response_data will be as below:

{
 'contextId': '5menrq33qy7n7eprtedg1s',
 'error': {code: 'FAILED' , message: 'Service is unavailable.'}
}

Incompatible Browser response_data will be as below:

{
 'contextId': '5menrq33qy7n7eprtedg1s',
 'error': {code: 'EMPTY_GUID' , message: 'You may be using an incompatible browser. Please try again with a different browser.'}
}

Response

The following table explains the response received:

Parameter Type Description
contextId string Unique request tracking ID, which is generated by the Merchant and will be treated by American Express as a pass-through parameter. It may allow the Merchant to uniquely identify request and responses.
walletId string An internal American Express identifier that will be used to identify Card Member.
e.g. zmnutzvznqdsvuswds7gj
error object This object will contain error code and message

Compatibility & Support

As a reminder, we offer 24/7 support during implementation. So please do not hesitate to contact us if you have any questions.

Browser Compatibility

  • Chrome 69 or higher
  • Firefox 62 or higher
  • Microsoft Edge 85 or higher
  • Safari 10 or higher

Mobile Device Compatibility

Mobile browsers for iOS and Android.