Benefits of iFrame
This option allows the buyer to stay in a familiar and trusted environment.
The payment tunnel is smooth and cart abandonment is less frequent.
It is possible to use a custom Template for the card form which will be integrated into the payment page. For more details: Mise en place d'un Template Personnalisé
The iframe is web responsive and can be integrated into a mobile application.
Table of Contents
Summary of the iframe implementation
- Implementation of the iframe in the merchant's payment page
- Configuration of URLs passed in the "urls" object of the payment request
Preparation of the urls.return and urls.cancel parameters with the URLs for successful and abandoned payment.
- Placement of these 2 parameters in the Data parameter hash
- Passing Data as a parameter in the URL provided to the src attribute of the iframe
- Addition of the CustomField14=iframe parameter to display only the payment block
- Creation of the 'Success' and 'Failure' pages
- Preparation of the HTML code for redirect-success and redirect-failure
- Implementation of JavaScript redirection
- Integration of the postMessage method in redirect-success and redirect-failure
- Integration of the event listener (Event Listener) in the merchant's payment page
Implementation of the iframe and configuration of the URL passed to the src attribute
Iframe tag & customField14
An iframe is an HTML tag that allows embedding an HTML page within another.
To do this, you need to use the <iframe> tag and specify the URL of the page you want to display in the src attribute. The URL of the payment page must include the following value: customField14=iframe.
<!DOCTYPE html>
<HTML lang="en">
<HEAD>
<META charset="UTF-8" />
<META http-equiv="X-UA-Compatible" content="IE=edge" />
<META name="viewport" content="width=device-width, initial-scale=1.0" />
<TITLE>Merchant website - Order</TITLE>
</HEAD>
<BODY>
...
<IFRAME
src="https://paymentpage.axepta.bnpparibas/payssl.aspx?token=YOUR_PAYMENT_TOKEN"
/>
...
</BODY>
</HTML>
Warning
You will need to pass the required parameters for payment with this URL
At a minimum: MerchantID, Data, and Len
Settings: Height & Width
In pixels
<IFRAME src="https://paymentpage.axepta.bnpparibas/payssl.aspx?MerchantID=YourMID&Len=123&Data=AGSDJ…ASDF&CustomField14=iframe" height="600" width="800" />
In CSS
#payment-iframe {
height: 600px;
width: 800px;
}
// or for a fullscreen display
#payment-iframe {
height: 100vh;
width: 100vw;
}
<IFRAME
id="payment-iframe"
src="https://paymentpage.axepta.bnpparibas/payssl.aspx?MerchantID=YourMID&Len=123&Data=AGSDJ…ASDF&CustomField14=iframe"
/>
Creation of 'Return' pages
When the cardholder submits the payment form, a request is sent to the Axepta server.
If the payment go to this end (approved or not), a response is sent to the urls.return address.
If the cardholder cancel the payment processing a response is sent to the urls.cancel address.
The goal is to display a success or failure page instead of the iFrame depending on the payment result.
Note: the server returns an HTTP response with the POST method. Therefore, a route must be created on the merchant site's server to handle this response.
Returns or cancel urls are detailled in 'Callback and Payment Notification Management' documentation.
Remember that you need to check if the payment have been approved or not, using the 'getByPayId' API: see
The merchant creates these pages which will be displayed during the cardholder's redirection.
Each will run a script that will redirect the user to the payment success or error page.
The setup of this script is described in the following section.
Setting up redirection in JavaScript
Integration of the postMessage method in redirect-success and redirect-failure
The postMessage solution "allows secure cross-domain communication."
The goal is to "communicate" with the parent page. This communication will take place through a MessageEvent.
<!DOCTYPE html>
<HTML lang="en">
<HEAD>
<META charset="UTF-8" />
<META http-equiv="X-UA-Compatible" content="IE=edge" />
<META name="viewport" content="width=device-width, initial-scale=1.0" />
<TITLE>Site marchand - redirection</TITLE>
</HEAD>
<BODY>
<SCRIPT>
function sendMessage() {
// we target the parent page with window.parent
// and we send him a postMessage
window.parent.postMessage(
// message in string
"payment success",
// we specify the origin of this message
"https://mon-site.com"
);
}
sendMessage();
</SCRIPT>
</BODY>
</HTML>
Integration of the (Event Listener) in the payment page
In the page that contains the iframe, we will set up an event listener. It will be responsible for executing a function when it receives an event of type message.
<!DOCTYPE html>
<HTML lang="en">
<HEAD>
<META charset="UTF-8" />
<META http-equiv="X-UA-Compatible" content="IE=edge" />
<META name="viewport" content="width=device-width, initial-scale=1.0" />
<TITLE>Merchant website - order</TITLE>
</HEAD>
<BODY>
<SCRIPT>
// on the current page
// we place a listener with the addEventListener method
window.addEventListener(
// event type to listen to
"message",
// callback function that will be executed
// when an event of type "message" will be emitted
(event) => {
// If the origin is not the same as the one placed in the message
// we stop the execution of the function
if (event.origin !== "https://mon-site.com") return;
// we redirect the user to the desired page
}
);
window.location.href = "https://mon-site.com/payment-success";
}
);
</SCRIPT>
...
<IFRAME
src="https://paymentpage.axepta.bnpparibas/payssl.aspx?MerchantID=YourMID&Len=123&Data=AGSDJ…ASDF&CustomField14=iframe"
/>
...
</BODY>
</HTML>
Dynamic customization
Additional custom fields can be added to the request to dynamically change the iframe.
Please find below the available fields:
* CustomField100: background color
* CustomField101: text color of the buttons when they are active
* CustomField102: background color of the buttons when they are active
* CustomField103: hover color of the text of the buttons when the button is active
* CustomField104: hover color of the background of the buttons when the button is active
* CustomField105: text color of the buttons when they are inactive
* CustomField106: background color of the buttons when they are inactive
Hexadecimal color values must be used in the CustomField fields, and the symbol '#' must be encoded, it will be replaced by the value '%23'.
Thus, to display a red button (when it is activated), you will need to value the CustomField102 as follows: CustomField102=%23FF0000.