Implementing the Hosted Payment Page
You have two options for implementing the Hosted Payment Page:
- Embedded Page is a component that is activated within your website's existing checkout page.
- Payment Page is a separate page to which the payer is redirected from your existing checkout page.
Once a checkout session has been established, the process of implementing the Hosted Payment Page for Hosted Checkout consists of the following steps:
- Create a Checkout object.
- Configure the Checkout object.
- Use the appropriate method of the Checkout object to start the payment process.
In addition, you can define callbacks that are triggered when the payer takes certain actions during the payment process.
The Hosted Payment Page implementation is done in your app or web site, using the Checkout JavaScript (JS) library.
Step 1: Create the checkout object
After the session has been initialized, you need to refer to the checkout.min.js file from the gateway server on your checkout page. This places a Checkout object into the global scope.
<script src="https://gateway-na.americanexpress.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
Step 2: Configure the checkout object
Call the Checkout.configure() function and pass it a JSON object that includes the session.id returned from the Initiate Checkout operation earlier.
Checkout.configure({
session: {
id: '<your_initiate_checkout_ID>'
}
});
- In API v67 or later, the session object is the only field allowed through configure() - all other fields must be included through INITIATE CHECKOUT.
- Data passed in Checkout.configure() never overwrites the data you already provided in the INITIATE CHECKOUT operation.
Step 3: Start the payment process
Start the payment process by calling one of the following methods of the Checkout object, depending on what kind of Hosted Payment Page you are implementing.
- To display the checkout interaction on an Embedded Page:
Example
Checkout.showEmbeddedPage('#embed-target') - To display the checkout interaction on a Payment Page:
Example
Checkout.showPaymentPage()
HTML Code Example for Requesting an Embedded or Payment Page
<html>
<head>
<script src="https://gateway-na.americanexpress.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
<script type="text/javascript">
function errorCallback(error) {
console.log(JSON.stringify(error));
}
function cancelCallback() {
console.log('Payment cancelled');
}
Checkout.configure({
session: {
id: '<your_initiate_checkout_session_ID>'
}
});
</script>
</head>
<body>
...
<div id="embed-target"> </div>
<input type="button" value="Pay with Embedded Page" onclick="Checkout.showEmbeddedPage('#embed-target');" />
<input type="button" value="Pay with Payment Page" onclick="Checkout.showPaymentPage();" />
...
</body>
</html>
HTML Code Example for Using the Modal Mode
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/bootstrap/4.5.2/css/bootstrap.min.css" integrity="sha384-JcKb8q3iqJ61gNV9KGb8thSsNjpSL0n8PARn9HuZOnIxN0hoP+VmmDGMN5t9UJ0Z" crossorigin="anonymous">
<title>Hello, world!</title>
</head>
<body>
<h1>Hello, world!</h1>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
Launch demo modal
</button>
<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
<div class="modal-dialog" role="document">
<div class="modal-content">
<div class="modal-header">
<h5 class="modal-title" id="exampleModalLabel">Modal title</h5>
<button type="button" class="close" data-dismiss="modal" aria-label="Close">
<span aria-hidden="true">×</span>
</button>
</div>
<div class="modal-body">
<div id="hco-embedded">
</div>
</div>
<div class="modal-footer">
<button type="button" class="btn btn-secondary" data-dismiss="modal">Close</button>
<button type="button" class="btn btn-primary">Save changes</button>
</div>
</div>
</div>
</div>
<script src="https://code.jquery.com/jquery-3.6.0.slim.min.js" integrity="sha256-u7e5khyithlIdTpu22PHhENmPcRdFiHRjhAuHcs05RI=" crossorigin="anonymous"></script>
<script src="https://cdn.jsdelivr.net/npm/bootstrap@4.5.2/dist/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="https://gateway-na.americanexpress.com/static/checkout/checkout.min.js" ></script>
<script>
// Configure Checkout first
Checkout.configure({
session: {
id: "<your_initiate_checkout_ID>"
}
})
// after the modal is shown, then call Checkout.showEmbeddedPage('#hco-embedded')
$('#exampleModal').on('shown.bs.modal', function (e) {
Checkout.showEmbeddedPage('#hco-embedded',
() => { $('#exampleModal').modal() } // tell Checkout how to launch the modal
)
});
$('#exampleModal').on('hide.bs.modal', function (e) {
sessionStorage.clear(); // tell Checkout to clear sessionStorage when I close the modal
});
</script>
</body>
</html>
Step 4: Implementing callbacks
Callbacks are provided to handle events that can occur during the payment interaction. Using callbacks is optional, but if you need them, you must define them in the body of the same <script> tag that references checkout.min.js.
All defined callbacks must have an implementation. They are invoked when the relevant event is triggered. The following code sample shows an example of a callback (triggered if the payer cancels the payment) being defined and implemented on a page.
<script src="https://gateway-na.americanexpress.com/static/checkout/checkout.min.js"
data-cancel="cancelCallback"
data-beforeRedirect="Checkout.saveFormFields"
data-afterRedirect="Checkout.restoreFormFields">
</script>
<script>
function cancelCallback() {
confirm('Are you sure you want to cancel?');
// code to manage payer interaction
}
// or if you want to provide a URL:
// cancelCallback = "someURL"
</script>
There are two types of callback methods: basic callbacks and redirect callbacks.
Basic callbacks
Basic callbacks are provided for the following events:
- cancel: When the payer cancels the payment interaction.
The cancel callback can only be used with a Payment Page, it does not work with an Embedded Page.
- error: When an error is encountered.
- complete: When the payer completes the payment interaction.
- timeout: When the payment is not completed within the duration available to the payer to make the payment.
Redirect callbacks
Since Hosted Checkout supports payment interactions that require the payer to be redirected away to other web sites to progress the payment, such as PayPal, callbacks are provided to manage what happens before the redirect and after the return to Hosted Checkout to finalize transaction processing:
- beforeRedirect: Before the payer is presented with the payment interface. Returns data required to restore the payment interface state for use by afterRedirect.
- afterRedirect: When the payer returns from completing the payment interaction. Uses the data saved by beforeRedirect to return the saved payment interface state.
The Checkout object also provides two functions to help you implement the beforeRedirect and afterRedirect callbacks:
- saveFormFields(): Saves all current form fields for use by restoreFormFields(). Use in your beforeRedirect implementation or implement beforeRedirect as Checkout.saveFormFields().
- restoreFormFields(): Restores form fields saved by saveFormFields(). Use in your afterRedirect implementation or implement afterRedirect as Checkout.restoreFormFields().
Frequently asked questions
What should I do if Hosted Checkout returns an error?
Hosted Checkout can return a number of integration errors. See Testing Steps for more information about testing and errors.
Why am I getting an error page instead of the Hosted Payment Page?
An error page displays when an incorrect Hosted Checkout request is attempted. Common causes for errors include:
- Missing mandatory fields.
- URLs provided in the request not being absolute.
What happens if the payer double-clicks the Pay button?
If the payer double-clicks the Pay button, that is, submits the payment twice, then the transaction is not repeated with your or the payer's bank.