Bancontact QR and Bancontact Link in Checkout

Bancontact, the Belgian payment method, supports two different forms of mobile redirection:

  1. QR codes (Bancontact QR); and
  2. mobile intent links (Bancontact Link)
Want to know more about QR codes and mobile intent links? See our guide
Not using Checkout? Check out our server-to-server guide.

How to get started

Existing merchants

With Bancontact Card integration

  1. Bancontact mobile redirect guide
    Good news! You can skip straight to Checkout configuration.

No Bancontact integration

  1. Account configuration
    If Bancontact has not already been enabled for your Payvision account then the first step is to contact the Sales team to have it set up.

  2. Brand guide
    If you haven't already done so, the next step is to check out the Bancontact brand guide.

  3. Bancontact mobile redirect guide
    Now you're set to continue with this guide. Please continue reading below.

New to Payvision

Welcome on board!

  1. Account configuration
    If Bancontact has not already been enabled for your Payvision account then the first step is to contact the Sales team to have it set up.

  2. Integration guide
    If you haven't already done so, the next step is to read the Checkout integration guide.

  3. Brand guide
    The Bancontact brand guide will give you an overview of what actions you can perform with Bancontact and the minimum fields required.

  4. Checkout APIs
    Once you've read the brand guide, it's time to familiarize yourself with the Checkout APIs.

  5. Bancontact mobile redirect guide
    Done with the above? Great! Now you're set to continue with this guide. Please continue reading below.

  6. Sandbox
    Once you've read this guide, you can have a play in our Sandbox to see how it works.

  7. Integration
    Start your engines! You're now ready to integrate with Payvision Checkout. Our friendly Technical Support team are at hand if you need help.

Checkout configuration

Checkout supports three different modes for Bancontact payments:

  1. Bancontact card only
  2. Bancontact card and QR code
  3. Bancontact card and Link (mobile intent)

To see an example of a Checkout request for each of these modes, click on the tabs below:

{
  "header": {
    "businessId": "{your-business-id}"
  },
  "body": {
    "checkout": {
      "returnUrl": "https://www.merchantsite.com/payment",
      "brandIds": [
        1210
      ]
    },
    "transaction": {
      "amount": "10.00",
      "storeId": "{your-store-id}",
      "authorizationMode": "payment",
      "trackingCode": "{your-tracking-code}",
      "currencyCode": "EUR",
      "purchaseId": "{your_purchase_id}",
      "descriptor": "Example Bancontact payment"
    }
  }
}
{
  "header": {
    "businessId": "{your-business-id}"
  },
  "body": {
    "checkout": {
      "returnUrl": "https://www.merchantsite.com/payment",
      "brandIds": [
        1210
      ]
    },
    "transaction": {
      "amount": "10.00",
      "storeId": "{your-store-id}",
      "authorizationMode": "payment",
      "trackingCode": "{your-tracking-code}",
      "currencyCode": "EUR",
      "purchaseId": "{your_purchase_id}",
      "descriptor": "Example Bancontact QR payment"
    },
    "mobileRedirect": {
      "mode": "QR"
    }
  }
}
{
  "header": {
    "businessId": "{your-business-id}"
  },
  "body": {
    "checkout": {
      "returnUrl": "https://www.merchantsite.com/payment",
      "brandIds": [
        1210
      ]
    },
    "transaction": {
      "amount": "10.00",
      "storeId": "{your-store-id}",
      "authorizationMode": "payment",
      "trackingCode": "{your-tracking-code}",
      "currencyCode": "EUR",
      "purchaseId": "{your_purchase_id}",
      "descriptor": "Example Bancontact Link payment"
    },
    "mobileRedirect": {
      "mode": "Link"
    }
  }
}

Notes about the above examples:

  1. Checkout does not support displaying a QR code and mobile intent link at the same time.
  2. Although the examples only include the Bancontact brand, it is possible to have other brands (e.g. Visa, iDEAL) along with Bancontact QR or Link in the Checkout.
  3. The request is the same regardless of whether you are using Embedded Checkout or Full Redirection.

📘

Which mobile app redirection method to use - QR code or Link?

QR codes are intended for completing payment using the mobile application on a different device.

Typically this is when a customer is ordering on a desktop or tablet device and wants to complete payment using the mobile application on their mobile phone.

Mobile intent links are intended for completing payment using the mobile application on the same device.

This is when a customer is ordering on their mobile device and wants to complete payment using the mobile application on the same device. Usually this is a mobile phone but when the application is compatible with tablet devices, it can also be the case that it is a tablet device.

In summary:

Device Type

QR supported

Link supported

Desktop

🗹 Yes

🗵 No

Tablet

🗹 Yes

🗹 Yes

Mobile

🗵 No

🗹 Yes

Bancontact QR

When the customer journey is split between two separate devices, there are extra challenges that have to be managed such as maintaining the customer informed on both devices.

Customer Journey

Successful payment

With QR code, the customer flow starting from the checkout is:

On device 1 (desktop/tablet)

On device 2 (mobile/tablet)

  1. Select Bancontact
  1. Select to pay using mobile application
  1. Press Pay
  1. QR code is displayed
  1. Customer opens mobile application
  1. Customer scans QR code
  1. Payment in progress message displayed
  1. Customer completes payment in mobile application
  1. Redirection to returnUrl

Customer cancels selection

If the customer presses the "Cancel" button, the checkout will redirect to the URL (returnUrl) supplied in the request. For the customer to complete payment using a different payment method, a new Checkout will need to be generated.
Please note that the previous transaction is not cancelled but it will time out once the session expires.

Corrupt QR code

In the event that the QR code is corrupt, an error will be displayed in the checkout and the customer will be presented with the "Cancel" button. When the customer presses the "Cancel" button, the behavior is the same as outlined above.

Timeout

If the customer does not scan the QR code or complete payment before the session times out, when the session expires, the checkout will redirect to the URL (returnUrl) supplied in the request.
The session timeout is 17 minutes from when the transaction is created.

Realtime connection issue

In the case that the checkout loses connectivity with the server, the checkout will switch to "manual confirmation" mode. The "Cancel" button will be replaced with a "Payment completed" button and a toast message will be displayed warning the customer that connection has been lost and asking them to press the button to continue once payment has been completed on their mobile device. When the customer presses the button, the checkout will redirect to the URL (returnUrl) supplied in the request.

Transaction and Checkout Status

There are two mechanisms by which the transaction status can be known:

  1. Webhooks (see documentation)
  2. Polling for the checkout status (see Checkouts API)

The transaction status values you will see during the payment lifecycle are:

Transaction status

Comments

Merchant Pending

The Bancontact QR transaction has been created. The QR code has been displayed but has not yet been scanned.

Pending

The QR code has been scanned but the transaction is not yet complete.

Complete

The transaction has been completed.

The Checkout status you will likely encounter are:

Result code

Checkout status

Comments

2

Pending

Checkout has been initiated and is waiting for the customer to complete payment.

4

Abandoned

The Bancontact Link has been triggered but the transaction is not yet complete.

0

Complete

Checkout has been completed. Please note that this does not mean that the transaction was successful.

For the full list of result codes and possible status values, see Checkout result codes.
Not sure which to use - QR code or Link? Read this.

Bancontact Link

Customer Journey

Successful payment

With Bancontact Link, the customer flow starting from the checkout is:

On device 1 (mobile/tablet)

  1. Select Bancontact
  1. Select to pay using mobile application
  1. Press Pay
  1. Payment in progress displayed (in checkout)
  1. Mobile app launches
  1. Customer completes payment in mobile app
  1. Redirection to returnUrl

Note that unlike Bancontact QR, with Bancontact Link the customer stays on the same device for the entire ordering and payment process.

Timeout

If the customer does not complete payment before the session times out, when the session expires, the checkout will redirect to the URL (returnUrl) supplied in the request.
The session timeout is 17 minutes from when the transaction is created.

Transaction and Checkout Status

There are two mechanisms by which the transaction status can be known:

  1. Webhooks (see documentation)
  2. Polling for the checkout status (see Checkouts API)

The transaction status values you will see during the payment lifecycle are:

Transaction status

Comments

Pending Merchant

The Bancontact Link transaction has been created.

Pending

The Bancontact Link has been triggered but the transaction is not yet complete.

Complete

The transaction has been completed.

The Checkout status you will likely encounter are:

Result code

Checkout status

Comments

2

Pending

Checkout has been initiated and is waiting for the customer to complete payment.

4

Abandoned

Checkout has expired or been abandoned by the customer.

0

Complete

Checkout has been completed. Please note that this does not mean that the transaction was successful.

For the full list of result codes and possible status values, see Checkout result codes.
Not sure which to use - QR code or Link? Read this.

Troubleshooting

Bancontact QR

Scanning the QR code does not launch the mobile app

The QR code is not intended to launch the app. The user must open the Payconiq by Bancontact mobile app or a banking mobile app that supports Bancontact and scan the QR code using the scan function within the app.

Bancontact Link

Mobile app does not open automatically

  • On a desktop device? Please use Bancontact QR instead. Bancontact Link is not supported on desktop devices.
  • Check that either the Payconiq by Bancontact mobile app or a valid banking mobile app is installed on the mobile device
  • If using a banking mobile app, confirm that the mobile app supports Bancontact

Useful links

Contact us

Have a question? Contact us.

Updated 4 months ago


Bancontact QR and Bancontact Link in Checkout


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.


Top