Hosted Checkout

The Hosted Checkout integration method is ideal when you want a solution that is both secure and fast to deploy. In this integration, you create a checkout session where the Mastercard Gateway hosts a payment page UI that gathers payment information from the customer, so you need not handle sensitive data at all.

For initial transactions that require payer participation (to provide their payment details), you use the checkout session to display a Hosted Payment Page for the payer. For merchant-initiated and subsequent transactions that do not require payer participation, you simply send an API request from your server.

Hosted Checkout does have some limitations, mainly that you cannot customize the payment flow and payment page UI beyond adding your merchant-specific name and logo.

Integration Steps

Prerequisites

Before implementing a Hosted Checkout solution, check with your payment service provider to ensure you meet the following prerequisites:

Have an account with Prahsys and get your API keys and Merchant ID.
Create a webhook for notifications.

When payer participation is needed, each task you perform with Hosted Checkout consists of the following steps:

Steps to Implementation

When payer participation is needed, each task you perform with Hosted Checkout consists of the following steps:

1. Establish a Checkout Session

2. Show the Payment Page

3. Interpret the response

Establishing a Checkout Session

The first step of a Hosted Checkout transaction is to send an API request to the Mastercard Gateway using the INITIATE CHECKOUT operation. The request creates a checkout session in the gateway, and must include:

Details related to the PAY, AUTHORIZE, or VERIFY transaction you want to create.
Information about how the Hosted Payment Page must interact with the payer.
Instructions for completing the Hosted Payment Page process.

Establish a checkout session

/v1/PRAHSYS_MERCHANT_ID/session

// Import the prahsys-api library
const prahsysApi = require('prahsys-api');

// Initialize the library with Merchant ID and API Key
prahsysApi.init({
  merchantId: '<PRAHSYS_MERCHANT_ID>',
  apiKey: '<API_KEY>'
});

// Define order details
const orderDetails = {
  merchantName: '<merchant_name>',
  orderId: '<order_ID>',
  orderDescription: '<description_of_order>',
  amount: '100.00',
  currency: 'USD'
};

// Initialize a checkout session
const response = await prahsysApi.initiateCheckout(orderDetails);
console.log('Checkout session initiated successfully:', response);

Establish Checkout Response

Whenever a request is unsuccessful, the Prahsys API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

Here is a list of the two error types supported by the Prahsys API — use these to understand what you have done wrong.

Name
checkoutMode
Type
string
Description
Defines how the Hosted Checkout interaction can be launched. If you want to immediately redirect the payer from your website (Hosted Payment Page) or launch the Lightbox to make the payment, set this value to WEBSITE. This is the default behavior if the field is not provided.
Name
merchant
Type
string
Description
The unique identifier issued to you by your payment provider.
Name
result
Type
enum
Description
- FAILURE The operation was declined or rejected by the gateway, acquirer or issuer
- PENDING The operation is currently in progress or pending processing
- SUCCESS The operation was successfully processed
- UNKNOWN The result of the operation is unknown
Name
successIndicator
Type
ASCII Text
Description
An identifier to determine the success of the hosted payment.
Name
session.id
Type
string
Description
The session identifier for the Hosted Checkout interaction.

Establish checkout response

{{
  "checkoutMode": "WEBSITE",
  "merchant": "pm_1234567890",
  "result": "SUCCESS",
  "successIndicator": "XXXXX",
  "session": {
    "id": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  }
}}

Show the 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.

The complete callback must be defined using the data-complete attribute on the Checkout script tag. The attribute value may be the name of a global function or a URL string. URLs will have a query parameter appended for each argument.

Example Show the Payment Page

<html>
    <head>
        <script src="https://gateway.prahsys.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback" data-complete="completeCallback"/></script>
        <!-- OR you can do this to return back to your receipt page-->
        <script src="https://gateway.prahsys.com/static/checkout/checkout.min.js" data-error="errorCallback" data-cancel="cancelCallback" data-complete="http://[your domain]/receiptPage"/></script>

        <script type="text/javascript">
          function errorCallback(error) {
                console.log(JSON.stringify(error));
          }
          function cancelCallback() {
                console.log('Payment cancelled');
          }
          function completeCallback(response) {
               console.log ("response: ", response);
               console.log ("resultIndicator: ", response.resultIndicator);
               console.log ("sessionVersion: ", response.sessionVersion);
           }
          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>