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.

The Integration Process

  1. The Merchant constructs the URL that containing all required parameters.
  2. Redirect the user to constructed URL, American Express
    login button
    will be displayed.
  3. The login button will drive the Card Member to the American Express
    login page.
  4. The Card Member enters their americanexpress.com username and password.
  5. American Express will authenticate the respective Card Member details.
  6. 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 page, that is already pre-configured in Amex system.
  7. In the case of a failed authentication, the Card Member will be returned to the callback page where the Amex pre-configured. An error message will appear as a query string.

Note: The callback parameter is pre-configured in Amex system and not passed in the URL.

Constructing the Login URL

The American Express Flexible Rewards provides an easy-to-use and secure way of integrating client-side functionality into your existing experience.

Constructed URL

https://blockrewardsv2-qaeusw1.americanexpress.com/flex/login?partner_id=M000000001&context_id=tene5qoz0fgghzf3lrebxi&locale=en_US&country=US


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

QA(E2) Environment

Please use below URL for QA:

BASE URL : https://blockrewardsv2-qaeusw1.americanexpress.com


Production(E3) Environment

Please use below URL for Production:

BASE URL : https://blockrewardsv2-euse1.americanexpress.com


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

Once the URL Constructed with required parameters, your page should look similar to the code below:

<html>
<head>
   ...
</head>
<body> ...

< button class="btn" onclick="navigateToLogin()"> Get Started American Express </button>


<script>

function navigateToLogin() {
var url = "https://blockrewardsv2-qaeusw1.americanexpress.com/flex/login?partner_id=M000000001&context_id="
      + randomString(22)
      + "&locale=en_US&country=US";
window.location.href = url;
}

</script>

</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.