Guides

Iframe

Use a CellPoint-hosted iframe to embed CellPoint's features in your application.

Suggest Edits

The iframe integration is designed to be included in a surrounding web page, and all payment related flows will be handled inside the iframe. This gives CellPoint Digital customers 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 - You will receive the URL that you will use to post messages to the iframe from your contact at CellPoint. That iframe should be embedded into 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:

  1. Add message handling functionality to the parent page that contains the iframe. CellPoint will return information to your page using the postMessage function.
  2. Add an iframe to your site and assign it an identifiable name value.
  3. 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.
  4. When messaging the iframe URL, the iframe posts a response to your message handler with a set of dimensions. To ensure that it displays properly, 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.
  5. After the customer fills in the payment data and clicks a 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 such as resizing the iframe and receiving payment results.

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

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>  
}

Ensure your iframe resizes accordingly.

❗️

Note:

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

5. Handle the transaction results

After the customer enters payment data and clicks a submission button, CellPoint processes the transaction and posts a JSON-formatted approve, decline, or error message to your handler.

On finalizing the payment – success or failure – CellPoint will issue a callback to an endpoint controlled by the client. This endpoint will be loaded inside the iframe HPP. Continuation of the payment flow – inside or outside the iframe HPP – is handled by the client.

Final Payment Status

When the transaction has been completely processed, CellPoint posts a final payment status message that contains all relevant redirect data as well as a signature to verify the response:

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

The payload includes additional important 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

Error messages include the following fields:

Field NameDescription
codeThe unique code for the error
event_idThe name of the error
messageA description of the error

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

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

Updated 7 days ago