-
Getting started
keyboard_arrow_down
Connect to the CCV Platform
Integrate our products into your software. Let's make payment happen together!
Look at all the possibilities
Integrate our products into your software. Let's make payment happen together!
Look at all the possibilitiesWhen the merchant shop and Bancontact App are on different devices, the shop can present a QR code to the customer. The code can be scanned with the Bancontact App which then asks for customer authentication.
A URL intent allows communication between apps using messages that are encoded as URL’s. The Bancontact App supports URL’s that have a specific namespace. There are several ways to use these, one of the most simple ways being a link or redirect in a browser.
Depending on the mobile OS you are developing for, you must open the Bancontact App with an
CCV Pay is Bancontact Certified including support for Mobile Payments using the BEP protocol. The next sections will describe how this functionality can be used within your shop or app.
Before you can render a QR code or use a URL intent to launch the Bancontact App, you’ll need to initiate a new payment. The PSP responds with the required data to use mobile payments.
Important: because this is Bancontact specific functionality, you must specify the brand bcmc in the request.
Request
{
"method": "card",
"brand": "bcmc",
"language": "nld",
"currency": "eur",
"returnUrl": "http://httpbin.org",
"amount": "0.1"
}
The required input data is limited. Based on your use-case, the returnUrl can be a web shop payment confirmation page,
some generic landing page, your own mobile app… Anything that conforms to a URL can be used for redirecting the
customer back to you.
Important: Be aware that Bancontact sets a maximum amount limit of 1500 Euro for Bancontact QR payments (When creating a payment with an amount over 1500 Euro, no QR Code / Url Intent will be generated / showed. The customer alternatively needs to enter their card details on the payment page. The limit does not apply for manual card entry.). More information can be found here
Response
{
"lastUpdate": 1540892561089,
"returnUrl": "http://httpbin.org",
"payUrl": "https://onlinepayments.ccv.eu/card/payment.html?reference=C181030104241082CB879161.1",
"cancelUrl": "https://onlinepayments.ccv.eu/card/cancel/merchant?reference=C181030104241082CB879161.1",
"details": {
"qrCode": "BEP://1BEP.JFORCE.BE:3717/TMI$G45D3GRCEUGA6X2PPDE6T55N",
"urlIntent": "BEPGenApp://DoTx?TransId=1BEP.JFORCE.BE:3717/TMI$G45D3GRCEUGA6X2PPDE6T55N"
},
"brand": "bcmc",
"amount": 0.1,
"reference": "C181030104241082CB879161.1",
"created": 1540892561089,
"language": "nld",
"method": "card",
"type": "sale",
"currency": "eur",
"status": "pending"
}
The response contains 2 important fields that allow a mobile payment, details.qrCode and details.urlIntent.
In the following sections we’ll describe how they can be used.
Note: It is not required to use these fields. By redirecting the customer to the payUrl, they will also be able to
complete the payment on a mobile device. The downside of this is a less seamless integration due to an extra redirect.
In short: You have 3 different options to integrate the bancontact mobile application inside your webshop or app:
You can choose to redirect the customer to the payUrl provided in the response of the initial payment request.
The customer is redirected to a webpage hosted by CCV where the customer can
open the Bancontact app button on mobile devicesAfter Authentication using the Bancontact app, the customer is redirected back to the shop. The status of the transaction can then be polled, or you can await the webhook.
Advantage
Disadvantage
payURL inside a webview, you should take note of the guidelines indicated in the edge case below.A QR code payment can be used when the device that renders the QR code is not the device that the customer uses to complete the payment. A typical scenario is embedding the QR code in a checkout page of a web shop or render it on a mobile payment terminal.
The field details.qrCode contains the data that is required to render the QR code. In order to make it available to
your customer, you must present this as a QR image that contains only the data from the response. Adding additional data may cause incorrect handling of the payment by the Bancontact App.
Example of the QR code rendered as an image
If you choose to render the QR code yourself (and not rely on our payment page), the returnUrl will not be triggered.
The Bancontact App will complete the payment, but it will not redirect the customer on their mobile device to the returnUrl.
We provide a webhook mechanism to inform you of payment status changes.
In case you use our payment page, the device that presents the QR-code will be redirected to the returnUrl once the
customer completes the payment.
A URL intent is an ideal solution when the integration between your own app and the Bancontact App should be as seamless as possible.
After completing the payment in the Bancontact App, the customer must be redirected back to your app. In order to
achieve this, the payment initiation must provide a URL intent as returnUrl.
Request
{
"method": "card",
"brand": "bcmc",
"language": "nld",
"currency": "eur",
"returnUrl": "merchantapp://ccvTx?orderId=XYZ",
"amount": "0.1"
}
In this example, the Bancontact App will redirect the customer to the merchant app which registered the merchantapp:// DeepLink with iOS or Android OS and passes through the orderId XYZ.
Deeplinking is a functionality provided by the mobile OS to register a URL for your app so that your app opens when someone clicks on a link with the deeplink associated.
For example, the Messenger app Whatsapp links itself to the whatsapp:// Deeplink. Every time a user clicks on a whatsapp://xxxxx link, the app Whatsapp will open. They provide an action on their deeplink send with an optional parameter text to pass the message to the deeplink. So whatsapp://send?text=Hello will open the app Whatsapp and start a new text with the context Hello prefilled.
As a merchant you are free to design your app in any way so that CCV / The bancontact app can return to your app on a path which easily identifies the transaction inside your payment flow.
For Example, you can implement a return action specifically designed for when the customer returns to your app after using the bancontact app, so that you can acknowledge the flow and show some specific UX to the customer.
merchantapp://ccvTx?orderId=XYZ can return the customer to a specific CCV page inside your app, where you can let the customer know OrderId XYZ was successfully acknowledged and processed.
The return of the customer to the app is the best case scenario. There can be cases that the customer does not return to your app for some unknown reason. It is highly recommended that you don’t rely on the customer returning to the app. The actual transaction status is independent of whether the customer returns or not. You should always verify the status of the actual transaction with CCV to know if the payment succeeded or not. This could be done by using webhooks on the backend system or polling. You should not let your business logic depend on the return of the customer to the app.
If you provide a returnUrl, that the bancontact app can redirect the customer to, which is a standard HTTPS link instead of a deeplink app link, you should be aware that the bancontact app will redirect the customer to the default browser of the customer. You should not depend on the fact that the customer will return to the same browser that the payment was started on. Every session data your business logic depends on will be unusable if the customer returns in a different browser. You should be able to handle this difference.
When using the redirection to the payUrl inside a webview, you should take care to allow your app to open the BepGenApp URL Scheme. If you do not allow this, then the Bancontact app will not open.
See the links below for more information
Android Documentation
iOS Documentation
Note: iOS has to be updated with the scheme Id so that the canOpenUrl function also supports BepGenApp.
Due to the unavailability of an official Bancontact test App, different steps need to be followed for live and test transactions for the integration of the mobile payment flow.
Live transactions are initiated with an API key that has operating mode LIVE.
By starting a new intent, the Bancontact App will be launched from within the merchant app. Once the payment is completed,
the Bancontact App redirects the customer back to the returnUrl which is most likely the merchant app.
Live transactions are initiated with an API key that has operating mode TEST.
The payment initiation response contains the same data for both a live and test transactions, however the qrCode
and urlIntent have a different format. It is a plain web URL which leads to our Bancontact simulator.
Response
{
"returnUrl": "merchantapp://ccvTx?orderId=XYZ",
"details": {
"qrCode": "https://shop-vpos-test.jforce.be/bep/authenticate.html?secureTransferId=ed71f3bd-6e36-4107-8be4-e0781743cba9&trm=50",
"urlIntent": "https://shop-vpos-test.jforce.be/bep/authenticate.html?secureTransferId=ed71f3bd-6e36-4107-8be4-e0781743cba9&trm=51"
},
"brand": "bcmc"
}
Other fields omitted for brevity
Because we don’t have any test Bancontact App we use the browser as the mobile payment app. The intent is a plain web URL so any mobile device with an HTTP compliant browser can be used as test device.
By starting a new intent, the browser will be launched from within the merchant app. Once the payment is completed,
the browser redirects the customer back to the returnUrl which is the merchant app.