The iframe integration is designed to be included in a surrounding web page, and all payment related flows are handled inside the iframe. This gives CellPoint Digital clients a rapid integration to a payment solution without a PCI compliance certificate while still allowing them to control the design of the web page that hosts the iframe HPP.

Prerequisites

In order to complete an iframe integration, you must work with your CellPoint onboarding support representative to define the specifications of your integration:

Iframe URL - Your contact at CellPoint will provide the URL that you will use to post messages to the iframe. That iframe should be embedded in your checkout page.
Cancel & accept URLs - Cancel and accept URLs are not required for the iframe version of our hosted payment page.

Workflow

The steps below describe the sequence of an iframe integration:

Add message handling functionality to the parent page that contains the iframe. CellPoint will return information to your page using the postMessage function.
Add an iframe to your site and assign it an identifiable name value.
When the customer is ready to check out, use a hidden form element to send a POST message to the iframe URL you received during onboarding. This payload should include order data, the name of the event handler, and the name of the iframe in the body of the request.
When messaging the iframe URL, the iframe posts a response to your message handler with a set of dimensions. Adjust the iframe container size based on those dimensions returned by the iframe. The payment form appears in the location specified by the iframe element.
After the customer fills in the payment data and clicks the submission button, CellPoint processes the transaction. The iframe posts a message with the results in the payload.

Integration

The steps below provide details and examples of how to complete the iframe integration:

1. Add message handling to the parent page

CellPoint uses the postMessage function to communicate with your parent page. The parent page must listen for messages from the iframe to handle events triggered throughout the workflow.

Add a "message" event listener to your page similar to the example below:

window.addEventListener("message", function (event) {
    const data = event.data;

    if (data.event_id === "payment_iframe_dimensions") {
        // Adjust iframe dimensions
        const iframe = document.getElementById("payment-iframe");
        iframe.style.height = data.height + "px";
        iframe.style.width = data.width + "px";
    }
	else if (data.event_id === "payment_fail_error") {
        // Handle error messages
        console.error("Error Code:", data.code, "| Message:", data.message);
        alert("Payment Error: " + data.message);
    }
	
	else if (data.event_id === "final_payment_status") {
        // Final payment status handling
        console.log("Redirect Data:", data.redirect_data);
        console.log("Signature:", data.signature);

        // Verify signature here and process redirect_data
    }
});

2. Add the iframe to your site

Add an iframe to your webpage. As you do this, ensure the following:

The iframe is where you want the payment form to appear.
The iframe name is unique.
The iframe name matches the target of the form that submits payment data.

See the example below:

<iframe name="paymentpage" width="1024" height="700"/>

Apple Pay®

If you are using Apple Pay with the iframe, you must also include the allow="payment" attribute here, as below:

<iframe name="paymentpage" width="1024" height="700" allow="payment"/>

See our Apple Pay integration guide for more information on using an iframe with Apple Pay, including the requirement to register domains with Apple.

3. Post the request on the iframe URL

Create a hidden form that sends order details to the iframe via a POST request:

<!DOCTYPE HTML>
<html>
	<body>
		<form action="https://{iframe_url}/views/web.php" method="POST" id="order-form" target="paymentpage">
			<input type="hidden" name="country" value="200"/>
			<input type="hidden" name="clientid" value="10022"/>
			<input type="hidden" name="account" value="100220"/>
			<input type="hidden" name="orderid" value="1561120588855"/>
			<input type="hidden" name="email" value="[email protected]"/>
			<input type="hidden" name="mobile-country" value="200"/>
			<input type="hidden" name="mobile" value="9898989898"/>
			<input type="hidden" name="amount" value="1.232"/>
			<input type="submit" value="Pay" class="btn-link"/>
		</form>
		<iframe name="paymentpage" width="1024" height="700"/>
	</body>
</html>

When the user submits the form, the iframe loads the payment page with the provided details.

4. Handle iframe resizing

CellPoint posts a message to your handler that contains the iframe's required dimensions:

{  
  "event_id": "payment_iframe_dimensions",  
  "height": <Height in pixels>,  
  "width": <Width in pixels>  
}

Resize your iframe accordingly to ensure that it displays properly.

❗️
Note:
It is recommended to resize only based on height and not width to keep a seamless user interface.

5. Iframe load event

When the iframe loads and is visible on the page, this triggers the load event. This confirms the HPP was loaded correctly and is ready to process payments. See an example of the load event below:

{"event_id":"hpp_loaded","message":"HPP Page has loaded"}

6. Payment selection event

Each time the customer clicks on or expands a form of payment, this triggers the payment_method_change event.

For example, if the customer first clicks on the Apple Pay option, the following event is triggered:

{"event_id":"payment_method_change","message":"Payment Method: Apple Pay"}

If the customer then clicks to expand the 'Credit or Debit Card' option, the following event is triggered:

{"event_id":"payment_method_change","message":"Payment Method: Card"}

7. Form completion event

The form completion event occurs in case the merchant wants to show a Pay button outside the iframe. When the event occurs, the merchant can enable the Pay button.

After the customer enters payment data, the iframe triggers the form completion event as follows:

Form-based payment methods - If the customer has selected a form-based payment method (like a credit card, UPI, or EMI), the payment_method_ready event ID indicates readiness for authorization.
Non-form-based payment methods - If the customer has selected a non-form-based payment method (like PayPal, Apple Pay, or Google Pay), the iframe returns the same payment_method_ready event ID, but no additional input is required.

This event provides relevant details, including the following:

Field Name	Description
`paymentMethodType`	The type of payment method, such as `"Card"`, or `"paypal"`
`isReady`	A boolean indicating readiness.
`timestamp`	A timestamp of when the event was triggered.

The code below shows an example of a form completion event:

{"event_id":"payment_method_ready","paymentMethodType":"Card","isReady":true,"timestamp":1760338169381}

If the customer does not select a payment method when entering payment data, the form completion event returns "isReady":"false. See the code below for an example of this scenario:

{"event_id":"payment_method_ready","paymentMethodType":"not selected","isReady":false,"timestamp":1760000528785}

8. Authorization event

When the customer clicks the Pay button and there are no validation errors, the iframe starts the authorization, triggering an event to inform the merchant that authorization has been called. This event's message depends on whether the workflow has sent an Authorize request or a Pay request.

Below is an example of the event when an Authorize call has been triggered:

{"event_id":"payment_triggered","message":"Authorize call is triggered"}

Below is an example of the event when a Pay call has been triggered:

{"event_id":"payment_triggered","message":"Pay call is triggered"}

9. Handle the transaction results

After processing the transaction, CellPoint posts a JSON-formatted approve, decline, or error message to the iframe. For more information, see the sections below. CellPoint also points the customer to the accept or fail URL designated by the merchant.

On finalizing the payment and confirming success or failure, CellPoint issues an asynchronous callback to an endpoint controlled by the client. This endpoint will be loaded inside the iframe.

Continuation of the payment flow, inside or outside the iframe, is handled by the merchant.

Final Payment Status

After processing the transaction, CellPoint posts a final payment status message that contains all relevant redirect data as well as a signature to verify the response. This occurs in the case of success, of decline, or if retry attempts are exhausted. (If there is an error, see Error Handling below.)

The final payment status message includes the following important values:

Field Name	Description
`"event_id"`	The message type. `"final_payment_status"` indicates a completed transaction.
`"redirect_data"`	Contains the final redirect data, similar to synchronous redirects sent to success or failure URLs.
`"signature"`	A signature used for validating the redirect response.

The payload includes additional information about the transaction, as shown in the sample code below:

{
    "event_id": "final_payment_status",
    "redirect_data": {
        "client_id": "11901",
        "account_id": "119010",
        "session_id": "3838271",
        "sale_amount": {
            "value": "7500",
            "currency_id": "840",
            "decimals": "2",
            "alpha3code": "USD"
        },
        "status": {
            "code": "4030",
            "message": "Session Complete"
        },
        "transactions": {
            "transaction": [{
				"id": "9268468",
				"order_id": "66QCNT",
				"fee": "0",
				"hmac": "f598f81fd6f4780cbbdd1e6b2edec4b029da11402b81b771c5e9f86ca09de8a17262918fedcfad609af703e23e612a964d4b1711bb253d899a13c424c1113603",
				"product_type": "100",
				"approval_code": "835788",
				"payment_method": "CD",
				"payment_type": "1",
				"date_time": "2024-12-17T07:48:42+00:00",
				"amount": {
					"value": "7500",
					"currency_id": "840",
					"decimals": "2",
					"alpha3code": "USD",
					"conversion_rate": "1"
				},
				"sale_amount": {
					"value": "7500",
					"currency_id": "840",
					"decimals": "2",
					"alpha3code": "USD"
				},
				"status": {
					"code": "2001",
					"message": "Payment captured by PSP"
				}
            }
        }
    }
}

Error Handling

If the transaction does not succeed, the iframe sends an error-related message to the parent window using the postMessage function. There are two types of error messages the iframe may send:

1. Response errors

Response error messages include the following fields:

Field Name	Description
`code`	The unique code for the error.
`event_id`	The name of the error.
`message`	A description of the error.

For example, CellPoint may return error messages with the following format:

`code`	`event_id`	`message`	Description
`2010`	`"payment_fail_error"`	`"Payment rejected by PSP"`	The transaction was declined.
`3021`	`"payment_fail_error"`	`"Insufficient funds"`	The account does not contain enough funds to cover the purchase.

The code below shows an example of an error response:

{
  "event_id": "payment_fail_error",
  "message": "<Error message string>",
  "code": "<Error code>"
}

Detailed error messages are present in the Error Descriptions section in Reference.

2. Session expired

If the session time limit is reached, CellPoint returns a session_expired event. This response must include order_id and timestamp values.

The code below shows an example of a session expired response:

{"event_id":"session_expired","order_id":"CPM1952123216","timestamp":1759753918022}

Prerequisites

Workflow

Integration

1. Add message handling to the parent page

2. Add the iframe to your site

Apple Pay®

3. Post the request on the iframe URL

4. Handle iframe resizing

❗️Note:

5. Iframe load event

6. Payment selection event

7. Form completion event

8. Authorization event

9. Handle the transaction results

Final Payment Status

Error Handling

1. Response errors

2. Session expired

❗️
Note: