IFrame integration - Hosted card iFrame

With the hosted card iFrame you can use our hosted card page in an iFrame. This iFrame will also be used to (optionally) show 3D Secure to the customer.

Transaction initialization

In addition to the normal initializing a card transaction request you have to supply the details.origin parameter. Optionally you can supply a details.redirect_parent_function parameter.

Here is a valid request body that initiates the card transaction:

{
    "payment_profile": "7c23a50d-8699-431c-a82b-a78718d2b6f6",
    "amount": 14,
    "customer": "cbbfa6ec-fb44-4da4-94c4-d81e92fd43e6",
    "customer_ip": "127.0.0.1",
    "dynamic_descriptor": "orderdesc01",
    "merchant_reference": "my order id",
    "payment_product": "card",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/86.0.4240.198 Safari/537.36",
    "details": {
        "redirect_url": "https://example.com/finalize",
        "origin": "https://example.com/",
        "redirect_parent_function": "iframeParent"
    },
    "webhook_transaction_update": "https://example.com"
}

Redirect URL

When you supply a details.redirect_url the customer will be redirected (in the iFrame) to this URL. If you do not want to show your result URL in the iFrame there are two options:

Omit the redirect_url
For an iFrame transaction it is allowed to omit the details.redirect_url from the transaction initialization. We'll then show the payment link result page in the iFrame.

Redirect the parent
You can use the details.redirect_parent_function (alphanumeric) parameter to set a redirect function name. When the customer is sent to a result URL we'll use Window.postMessage to pass an object to the parent window. Allowing you to redirect the customer in the parent window.

The object we'll be passing using Window.postMessage will also contain your function name. Example of the object (e.data in the event listener):

{
    "function": "iframeParent",
    "url": "https://example.com/finalize?transaction_id=9e0377c06-a9e0-43a8-9885-8799a8338b5a"
}

Example of the function necessary in the parent window:

/** iFrame event listener */
window.addEventListener('message', (e) => {
    if (e.data.function === 'iframeParent') {
        window.location.href = e.data.url;
    }
});

Response - Show the iFrame

The transaction initiation call will result in a response. In this response, we reply with a JSON representation of an initiated transaction. This transaction object also includes the details property, which has been augmented with an approval_url. You will need to use the approval_url as the iFrame src attribute.

Example

To see an example, take a look at the example checkout.