Bancontact

Bancontact is a local payment method that allows customers in Belgium to pay using a Bancontact card or the Bancontact mobile app.

Overview

Property	Details
Markets (consumer)	`BE`
Consumer currencies	`EUR`
Authentication methods	`REDIRECT`
Authentication timeout	Subject to channel rules
Minimum payment amount	Subject to channel rules
Maximum payment amount	Subject to channel rules
Payment instrument	`BANK_REDIRECT` / `DEBIT_CARD`
One-time payment	Yes
Recurring payments	No
Separate captures	No
Refund	Full · Partial
Refund validity	Subject to channel rules
Disputes	No standard chargeback flow
Supported products	`Checkout Session` · `Hosted Checkout` · `Embedded Checkout` · `API`

Payment Flow

Customer selects Bancontact at checkout.

UseePay creates and confirms the PaymentIntent.

UseePay returns a redirect URL in next_action.redirect.url.

The merchant redirects the customer to the Bancontact payment page.

The customer completes the payment using a Bancontact card or the Bancontact mobile app.

After authorization, the customer is returned to the URL specified in return_url.

UseePay updates the PaymentIntent and sends a webhook notification containing the final payment status.

Notes

Bancontact is primarily available to customers in Belgium.

The payment currency is EUR.

Bancontact is a redirect-based payment method. A valid return_url must be provided when creating or confirming the PaymentIntent.

Bancontact only supports automatic capture. Set auto_capture to true or omit it to use the default value.

The browser redirect does not represent the final payment result. Always retrieve the PaymentIntent or process the webhook notification before fulfilling the order.

The payment_method_data.bancontact object currently does not require any Bancontact-specific business parameters. The optional extra_params object is reserved for extended channel parameters and should only be provided when instructed by UseePay.

Integration Guide

Create and Confirm a PaymentIntent

UseePay recommends creating and confirming the PaymentIntent in a single request by setting confirm to true.

Set:

currency to EUR

payment_method_data.type to bancontact

billing.address.country to BE

confirm to true

return_url to the merchant result page

Request Example

{
  "merchant_order_id": "order_bancontact_001",
  "amount": 1000,
  "currency": "EUR",
  "confirm": true,
  "auto_capture": true,
  "return_url": "https://merchant.example.com/payment/return",
  "payment_method_data": {
    "type": "bancontact",
    "billing": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com",
      "address": {
        "country": "BE"
      }
    },
    "bancontact": {}
  }
}

Request Example (Java SDK)

Response Example

When customer authorization is required, the PaymentIntent returns requires_customer_action.

{
  "id": "1012611020000000001",
  "code": "0000",
  "message": "Approved or completed successfully",
  "amount": 1000,
  "currency": "EUR",
  "status": "requires_customer_action",
  "confirm": true,
  "orderType": "sale",
  "mode": "payment",
  "sale": true,
  "merchant_no": "500000000000000",
  "app_id": "merchant.example.com",
  "merchant_order_id": "order_bancontact_001",
  "refunded_amount": 0,
  "next_action": {
    "type": "redirect",
    "redirect": {
      "method": "GET",
      "url": "https://payment.example.com/bancontact/authorize",
      "content_type": null,
      "app_url": null,
      "package_name": null
    }
  },
  "return_url": "https://merchant.example.com/payment/return",
  "auto_capture": true,
  "payment_attempt": {
    "payment_method_details": {
      "type": "bancontact"
    }
  }
}

When status is requires_customer_action, redirect the customer to:

next_action.redirect.url

Do not mark the merchant order as paid at this stage.

Handling the Payment Result

After the customer completes the Bancontact authorization, the browser is redirected to the configured return_url.

The merchant must then:

Retrieve the PaymentIntent from the server, or wait for the UseePay webhook.

Check the final PaymentIntent status.

Fulfill the order only when the status is succeeded.

Possible statuses include:

Status	Description	Merchant Action
`requires_customer_action`	Customer authorization is still required	Redirect the customer
`pending`	The payment is pending the final result from the payment provider	Wait for the webhook notification
`succeeded`	Payment completed successfully	Fulfill the order
`failed`	Payment failed	Display the failure and allow retry
`canceled`	Payment was canceled	Close or recreate the payment

Always use the PaymentIntent status or webhook event as the source of truth. Do not rely only on the browser redirect result.

Overview#

Payment Flow#

Notes#

Integration Guide#

Create and Confirm a PaymentIntent#

Request Example#

Request Example (Java SDK)#

Response Example#

Handling the Payment Result#