Accept a Bancontact payment

Learn how to accept Bancontact, a common payment method in Belgium.

Bancontact is a single use payment method where customers are required to authenticate their payment. Customers pay with Bancontact by redirecting from your app, authenticating the payment, then returning to your app where you get immediate notification on whether the payment succeeded or failed.

Your use of Bancontact must be in accordance with the Bancontact Terms of Service.

Set up Stripe
Server-side

Use our official libraries for access to the Stripe API from your application:

Terminal

# Available as a gem
sudo gem install stripe

Gemfile

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Create a PaymentIntent
Server-side

A PaymentIntent is an object that represents your intent to collect payment from a customer and tracks the lifecycle of the payment process through each stage.

Create a PaymentIntent on your server and specify the amount to collect and the eur currency (Bancontact does not support other currencies). If you have an existing Payment Intents integration, add bancontact to the list of payment method types.

Terminal

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "payment_method_types[]"="bancontact"

The default language of the Bancontact authorization page is English (en). You can match the preferred language of your customer by setting preferred_language to fr, nl, or de.

Terminal

curl https://api.stripe.com/v1/payment_intents \
  -u sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "amount"=1099 \
  -d "currency"="eur" \
  -d "payment_method_types[]"="bancontact" \
  -d "payment_method_options[bancontact][preferred_language]"="fr"

Instead of passing the entire PaymentIntent object to your app, return its client secret. The PaymentIntent’s client secret is a unique key that lets you confirm the payment and update payment details on the client, without allowing manipulation of sensitive information, like the payment amount.

You can retrieve the client secret from an endpoint on your server using the browser’s fetch function on the client side. This is generally the best approach when your client side is a single-page application, especially one built with a modern frontend framework such as React. This example shows how to create the server endpoint that serves the client secret:

main.rb

get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

This example demonstrates how to fetch the client secret with JavaScript on the client side:

var response = fetch('/secret').then(function(response) {
  return response.json();
}).then(function(responseJson) {
  var clientSecret = responseJson.client_secret;
  // Call stripe.confirmBancontactPayment() with the client secret.
});

Collect payment method details
Client-side

Create a payment form on your client to collect the required billing details from the customer:

Field	Value
`name`	The full name (first and last) of the customer.

checkout.html

<form id="payment-form">
  <div class="form-row">
    <label for="name">
      Name
    </label>
    <input id="name" name="name" required>
  </div>

  <!-- Used to display form errors. -->
  <div id="error-message" role="alert"></div>

  <button id="submit-button">Pay with Bancontact</button>
</form>

Submit the payment to Stripe
Client-side

Create a payment on the client side with the client secret of the PaymentIntent. The client secret is different from your API keys that authenticate Stripe API requests. It should be handled carefully because it can complete the charge. Do not log it, embed it in URLs, or expose it to anyone but the customer.

When a customer clicks to pay with Bancontact, use Stripe.js to submit the payment to Stripe. Stripe.js is the foundational JavaScript library for building payment flows. It automatically handles complexities like the redirect described below, and enables you to extend your integration to other payment methods. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html

<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/v3/"></script>
</head>

Create an instance of Stripe.js with the following JavaScript on your checkout page.

client.js

// Set your publishable key. Remember to change this to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

Call stripe.confirmBancontactPayment to redirect your customer to Bancontact’s website or app to complete the payment. Include a return_url to redirect your customer after they complete the payment. You must also provide the customer’s full name in billing_details.

client.js

var stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

// Redirects to Bancontact website or app
stripe.confirmBancontactPayment(
  '{{PAYMENT_INTENT_CLIENT_SECRET}}',
  {
    payment_method: {
      billing_details: {
        name: "Jenny Rosen"
      }
    },
    return_url: 'https://example.com/checkout/complete',
  }
).then(function(result) {
  if (result.error) {
    // Inform the customer that there was an error.
  }
});

Handling the redirect

The following URL query parameters are provided when Stripe redirects the customer to the return_url.

Parameter	Description
`payment_intent`	The unique identifier for the `PaymentIntent`.
`payment_intent_client_secret`	The client secret of the `PaymentIntent` object.

You may also append your own query parameters when providing the return_url. They persist throughout the redirect process. The return_url should correspond to a page on your website that provides the status of the payment. You should verify the status of the PaymentIntent when rendering the return page. You can do so by using the retrievePaymentIntent function from Stripe.js and passing in the payment_intent_client_secret.

var url = new URL(window.location);
var clientSecret = url.searchParams.get('payment_intent_client_secret');

stripe.retrievePaymentIntent(clientSecret).then(function(response) {
  if (response.error) {
    // Handle error
  } else if (response.paymentIntent && response.paymentIntent.status === 'succeeded') {
    // Handle successful payment
  }
});

Bank account details

You can find details about the bank account the customer used to complete the payment on the resulting charge under payment_method_details.

{
  "charges": {
    "data": [
      {
        "payment_method_details": {
          "bancontact": {
            "bank_code": "VAPE",
            "bank_name": "VAN DE PUT & CO",
            "bics": "VAPEBE22",
            "iban_last4": "7061",
            "preferred_language": "en",
            "verified_name": "Jenny Rosen"
          },
          "type": "bancontact"
        },
        "id": "src_16xhynE8WzK49JbAs9M21jaR",
        "object": "source",

Accept a Bancontact payment

Set up Stripe
Server-side

Create a PaymentIntent
Server-side

Collect payment method details
Client-side

Submit the payment to Stripe
Client-side

Handling the redirect

Bank account details

OptionalHandle post-payment events

OptionalHandle the Bancontact redirect manually

Accept a Bancontact payment

Set up StripeServer-side

Create a PaymentIntentServer-side

Collect payment method detailsClient-side

Submit the payment to StripeClient-side

Handling the redirect

Bank account details

OptionalHandle post-payment events

OptionalHandle the Bancontact redirect manually

Set up Stripe
Server-side

Create a PaymentIntent
Server-side

Collect payment method details
Client-side

Submit the payment to Stripe
Client-side