Integration method to choose if you want to display the payment page in an iFrame.
In iFrame integration, you will have the possibility to display the payment page in an iFrame.
Requirements :
- A dedicated and not shared IP
- Your IP must have a good reputation on this website : https://www.brightcloud.com/tools/url-ip-lookup.php . If not, you can request a change using the form.
- You have provided us with your iFrame domains and have authorized them to display the iFrame payment page
- Calls to FLOA services must be made on the server side, the authentication token being provided for each call to our services must not be on the client side
- Sign a PCI-SAQ-A certification if you do more than 6M transactions a year
In the integration environment, you must install a plugin on your browser to allow the payment iFrame to be displayed on your site.
- Firefox : https://addons.mozilla.org/fr/firefox/addon/ignore-x-frame-options-header/
- Chrome : https://chrome.google.com/webstore/detail/ignore-x-frame-headers/gleekbfjekiniecknbkamfmkohkpodhe
In the production environment, it is necessary to provide us with the URL that will be used to host the iFrame so that we can authorize it to display the iFrame.
This integration offers the following advantages :
- You can integrate the payment page into your environment.
Disadvantages of this integration :
- Requires PCI SAQ-A validation if you do more than 6M transactions a year
- Requires authorization from your domains to display the payment in iFrame
- • More development work than a Payment page integration
Workflow
Services to call
Authentication
Example in the integration environment
GET https://paymentgateway.integration-cb4x.fr/v1/auth/token
Headers
authorization : login:password (en base 64)
Body
Empty
PreEligibility
Subject to customer information and consent (workshop to be conducted with your account manager)
PreEligibility
For a 1XD payment, specify the number of days of deferment in reportDelayInDays
Example in the integration environment
POST https://eligibility.integration-cb4x.fr/api/v1/pre-eligibilities?merchantId=38&merchantSiteIds=7017
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
{
"presaleFolder": {
"shoppingCarts": [
{
"reference": "order reference",
"rawAmount": order amount in cents,
"productsCount": 1,
"products": [
{
"name": "Product A",
"raw_amount": product’s amount in cents,
"shipping": {
"method": "UPS"
}
}
]
}
],
"customer": {
"reference": "customer reference",
"civility": "Mr",
"firstName": "fTest",
"lastName": "lTest",
"email": "[email protected]",
"homePhoneNumber": "0512345678",
"homeAddress": {
"line1": "route de bordeaux",
"zipCode": "33000",
"city": "Bordeaux",
"countryCode": "FR"
}
},
"saleChannel": "Desktop"
}
}
Eligibility
Eligibility
For better tracking of the orders, we recommend you put the same value in presaleFolder/shoppingCarts/reference for the PreEligibility and Eligibility
In the case of a 1XD payment, indicate the number of deferred days in reportDelayInDays
In the case of a iXC payment, birthDate, birthZipCode, maidenName are not mandatory
Example in the integration environment
POST https://eligibility.integration-cb4x.fr/api/v1/eligibilities?merchantId=38&merchantSiteIds=7017
If pre-eligibility is made, link the pre-eligibility to the eligibility via the pre-eligibility requestId in the URL :
POST https://eligibility.integration-cb4x.fr/api/v1/eligibilities?merchantId=38&merchantSiteIds=7017&requestId=123456
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
{
"presaleFolder": {
"shoppingCarts": [
{
"reference": "order reference",
"rawAmount": order amount in cents,
"productsCount": 1,
"products": [
{
"name": "Product A",
"raw_amount": product’s amount in cents,
"shipping": {
"method": "UPS"
}
}
]
}
],
"customer": {
"reference": "60128411000001321",
"firstName": "fTest",
"lastName": "lTest",
"email": "[email protected]",
"birthDate": "1986-07-16T00:00:00.0000000+00:00",
"birthZipCode": "33",
"civility": "Mr",
"homePhoneNumber": "0512345678",
"cellPhoneNumber": "0612345678",
"homeAddress": {
"line1": "route de bordeaux",
"zipCode": "33000",
"city": "Bordeaux",
"countryCode": "FR"
}
},
"saleChannel": "Desktop"
}
}
Create a payment session
Creates a payment session
Put the iframe value in configuration/formType
For better tracking of orders, we recommend you put the same value in orderData/orderSummaryRef, orderData/orderRef as presaleFolder/shoppingCarts/reference
In the case of a 1XD payment, indicate the number of days of delay in configuration/reportDelayInDays
Example in the integration environment
POST https://paymentgateway.integration-cb4x.fr/v1/payment-sessions
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
{
"merchantId": 38,
"merchantSiteId": "7017",
"customer": {
"customerRef": "00000001",
"firstName": "fTest",
"lastName": "lTest"
},
"orderData": {
"amount": amount returned by the eligibility service (contains Floa fees if any),
"orderSummaryRef": "order reference",
"orderRef": "order reference",
"orderDate": "2021-06-12T02:36:28.639Z",
"salesChannel": "Desktop",
"shippingMethod": "UPS",
"scoringToken": "token returned by the eligibility service"
},
"configuration": {
"culture": "FR",
"template": "Generic",
"formType": "iframe",
"merchantBackUrl": "back to cart URL",
"merchantHomeUrl": "merchant home URL",
"merchantNotifyUrl": "URL to which the payment notification will be sent",
"merchantReturnUrl": "URL to which the customer will be redirected after the payment (this redirection also returns the payment result)",
"paymentOptionRef": "63"
}
}
iFrame payment page
Display the payment page in an iFrame.
Payment result
The payment result must be retrieved via the Gets the payment result from its session id. method.
Example in the integration environment
GET https://paymentgateway.integration-cb4x.fr/v1/payment-sessions/xxxxxxx-xxxx-xxx-xxxx-xxxx/paymentResult (avec xxxxxxx-xxxx-xxx-xxxx-xxxx votre sessionId de paiement)
Headers
Content-type : application/json
authToken : the token retrieved via the call to the authentication service
Body
Empty
Example of a response
{
"paymentResultCode": 0,
"paymentResultCodeMessage": "succeeded",
"paymentResultComplementaryCode": 4,
"paymentResultComplementaryCodeMessage": "authorized",
"storedPaymentMethodId": "",
"storedPaymentMethodLabel": "",
"subOrders": [],
"amount": 43055,
"paymentMethodType": "CB",
"paymentSessionId": " xxxxxxx-xxxx-xxx-xxxx-xxxx",
"orderRef": "1629271248",
"orderTag": "",
"sessionDate": "2021-08-18T07:20:52.34"
}
paymentResultCode :
0 : Successful, authorization ok
1 : refused
2 : refused by bank
3 : Failed (technical failure)
4 : Pending
5 : Unknown (indeterminate state)
6 : Canceled (canceled)
Preview of the payment page in iFrame mode
3rd party cookies fallback solution
In some cases, the browser will not allow 3rd party cookies and therefore block the authentication page in 3DS scenarios.
The solution we have come up with is to complete the payment in another tab like so (when we detect that 3rd party cookies are not allowed in the current browser) :
Once the user clicks the link, a new tab opens with the url of the iframe.
After completing the payment, the payment tab closes automatically and the merchant page is notified that the payment is finished.
The fallback solution can be deactivated with the optionnal parameter enable3rdPartyCookiesFallback set to false.
But keep in mind that some customers can than experience an empty authentication page from their bank due to the browser not allowing 3rd party cookies.