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.

If you have originally implemented a Lightbox page (with API v62 or earlier), your payment page is a modal dialog displayed on top of your existing checkout page. The newer API versions do not directly support this implementation, but if you are migrating to a newer API version, you can use a Modal mode, which allows you to use the Lightbox as an extension of the Embedded Page.

Once a checkout session has been established, the process of implementing the Hosted Payment Page for Hosted Checkout consists of the following steps:

  1. Create a Checkout object.
  2. Configure the Checkout object.
  3. 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.

Example

<script src="https://cnp.merchantlink.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback"></script>
If you are enabled for both the AUTHORIZATION and PAY operations, you must use Hosted Checkout v52 or above.

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.

Example

        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

Example



<html>
    <head>
<script src="https://cnp.merchantlink.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

Example



<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://cnp.merchantlink.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.

Callback Example


<script src="https://cnp.merchantlink.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.
These callbacks can be defined as functions, as in the example above, or as URLs. If you provide a URL instead of a function in a callback, the payer is redirected to this URL when the event is triggered.

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 Copied to Clipboard

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.