Bancontact

REST API & Wirecard Payment Page v1

Bancontact is a type of Online Bank Transfer.

Countries and Currencies

Countries

Belgium

Currencies

EUR

Communication Formats

This table illustrates how Bancontact notifications are encoded, and which formats and methods can be used for requests and responses.

Requests/Responses

Format

XML, JSON

Methods

POST, GET

IPN Encodement

Please follow the instructions given at Instant Payment Notification to set up IPN.

Transaction Types

Bancontact refund and recurring transactions are not provided by Bancontact directly. They can be accomplished using the payment method SEPA. See refund and recurring for details.

For transaction type details which are not given here, look at Transaction Types.

Transaction Type Description Link to the Sample

debit

debit samples

refund-debit

Bancontact does not support refund-debit. Use SEPA Credit Transfer to wire funds back to the consumer.

recurring

Bancontact does not support recurring transactions. Use SEPA Direct Debit to initiate recurring transactions

Test Credentials

URLs (Endpoints)

REST API

https://api-test.wirecard.com/engine/rest/paymentmethods/

Payment Page

https://api-test.wirecard.com/engine/hpp/

Merchant Account ID (MAID)

86f03c98-6691-421d-94c8-232c3d5c2573

Username

REST API

16390-testing

Password

REST API

3!3013=D3fD8X7

Secret Key

Payment Page

2341ae35-aa13-4511-95d5-acd80f0fcb52

When using our testing environment, the Wirecard Payment Gateway does not send the request to Bancontact servers. Instead, it will be sent to a simulation endpoint that looks similar to the Bancontact landing page.

It covers the most basic situations, such as:

  • Success scenario

  • User cancellation

  • Invalid card data

The look and feel of the simulated landing page will not be regularly updated which may lead to differences when comparing with real Bancontact landing page.

You can skip the input fields Card Number and Expiry Date as our testing endpoint is ignoring them. To simulate a specific scenario use one of the options presented by field Error code.

Bancontact error code
Workflow: debit
Using ReST API
Bancontact workflow debit using ReST API
  1. Consumer wants to pay a product/service.

  2. Consumer selects payment method Bancontact (BC).

  3. WPG redirects consumer from website to Bancontact landing page (WPG uses the field payment-methods/payment-method/@url in the response).

  4. Consumer enters Bancontact card data.

  5. Now two actions occur simultaneously:

    1. Consumer is sent back to the shop via Redirect URL informing them of the status of the payment. The destination depends on the given redirect URLs in the debit Request (Successful) sample (provided in the success-redirect-url field).

    2. WPG sends a notification (IPN) of the payment outcome to the merchant. In order to receive server-to-server notifications, you have to provide the URL of your endpoint in the debit Request (Successful) sample that will process IPNs (provided in the notifications/notification/@url field).

Using Payment Page
Bancontact workflow debit using payment page
  1. Consumer wants to pay a product/service.

  2. Merchant redirects consumer to Payment Page.

  3. Consumer selects payment method Bancontact (BC).

  4. Payment Page redirects the consumer to Bancontact landing page (WPG uses the field payment_methods/payment_method/@url in the response).

  5. Consumer completes the payment.

  6. Now two actions occur simultaneously:

    1. Consumer is sent back to the Payment Page via Redirect URL informing them of the status of the payment. The destination depends on the given redirect URLs in the Payment Page sample, debit Request (provided in the field success_redirect_url).

    2. Payment Page sends a notification (IPN) of the payment outcome to the merchant. In order to receive server-to-server notifications, you have to provide the URL of your endpoint in the Payment Page sample, debit Request that will process IPNs (notification_url).

refund

Although, BCMC does not support a native refund mechanism, the Wirecard Payment Gateway offers a solution by which you are able to move funds to your consumer. Wirecard Payment Gateway employs the SEPA Credit Transfer to wire funds back to consumer.

In order to initiate a refund using SEPA Credit Transfer, look at the SEPA Credit Request sample.

The workflow is as follows:

Bancontact workflow using credit refund
  1. Merchant receives a request for refund from the consumer.

  2. Merchant agrees on refund amount with the consumer to refund a specific debit transaction.

  3. Refund transaction.

  4. Merchant refunds by referencing the credit to a previous debit transaction; or

  5. Funds are transferred and consumer receives refund.

Characteristics of this workflow are:

  • The workflow is offline, so you have to wait a longer period for the outcome (it is a matter of a few days).

  • SEPA Credit Transfer must be referenced to a successful debit transaction; the Transaction ID is taken from the successful debit notification.

The refund is not available immediately. You can initiate it 24 hours after the initial debit.

When making a SEPA Credit Transfer request, keep in mind:

  1. You have to reference the successful debit in the parent-transaction-id field.

  2. Bank account details like IBAN and BIC are not provided by you in the request.

recurring

Although, BCMC does not support native mechanism for recurring payments, the Wirecard Payment Gateway offers a solution by which you are able to charge the consumer repeatedly. Wirecard Payment Gateway employs SEPA Direct Debit to withdraw funds from the consumer.

In order to initiate a recurring transaction using SEPA Direct Debit,

For the characteristics of the workflow see refund above. These characteristics also apply for recurring in combination with SEPA Direct Debit.

When making a SEPA Direct Debit Request, keep in mind:

  1. You have to reference successful debit in the parent-transaction-id field.

  2. Bank account details like IBAN and BIC are not provided by you in the request.

  3. You need a Mandate, which represents the consumer’s consent of being charged via SEPA Direct Debit.

  4. You need to provide your Creditor-ID in each SEPA Direct Debit request.

Fields

The fields used for Bancontact requests, responses and notifications are the same as the REST API Fields resp. Payment Page. Please refer to: ReST API Fields or Payment Page.

The fields listed below are Bancontact specific and either mandatory M or optional O.

Field Cardinality Data Type Description

transaction-type

M

Alphanumeric

This is the type for a transaction.

Use debit.

payment-methods

M

Alphanumeric

The name of the Payment Method.

Use bancontact.

Locale

O

Language used to localize the Bancontact landing page.

Supported by Bancontact
  • zh Chinese

  • nl Dutch

  • en English

  • fr French

  • de German

  • hi Hindi

  • it Italian

  • ja Japanese

  • pt Portuguese

  • ru Russian

  • sk Slovak

  • es Spanish

  • ru Russian

  • sk Slovak

  • es Spanish

Default locale is en English.

Samples

Go to Notification Examples if you want to see corresponding notification samples.

REST API
debit Request (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>86f03c98-6691-421d-94c8-232c3d5c2573</merchant-account-id>
   <request-id>20e15877-d5fb-4893-a260-1edaba911fbf</request-id>
   <transaction-type>debit</transaction-type>
   <requested-amount currency="EUR">0.01</requested-amount>
   <payment-methods>
      <payment-method name="bancontact" />
   </payment-methods>
   <order-number>180924114516875</order-number>
   <account-holder>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <email>john.doe@wirecard.com</email>
      <phone/>
      <address>
         <street1>123 anystreet</street1>
         <city>Brantford</city>
         <country>CA</country>
         <postal-code>M4P1E8</postal-code>
         <state>ON</state>
      </address>
   </account-holder>
   <bank-account>
      <account-number/>
      <bank-code/>
   </bank-account>
   <shipping>
      <first-name>John</first-name>
      <last-name>Doe</last-name>
      <phone>+49123123123</phone>
      <address>
         <street1>123 anystreet</street1>
         <city>Brantford</city>
         <country>CA</country>
         <postal-code>M4P1E8</postal-code>
      </address>
   </shipping>
   <notifications>
      <notification url="https://merchant.com/ipn.php" />
   </notifications>
   <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
   <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
   <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
</payment>
debit Response (Successful)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>86f03c98-6691-421d-94c8-232c3d5c2573</merchant-account-id>
   <transaction-id>0bd26bfd-e3cb-40eb-a2a2-cd66059a2c22</transaction-id>
   <request-id>6d56982b-9ec8-4866-9e49-5f3da7f00251</request-id>
   <transaction-type>debit</transaction-type>
   <transaction-state>success</transaction-state>
   <completion-time-stamp>2018-09-24T10:08:01.000Z</completion-time-stamp>
   <statuses>
      <status code="201.0000" description="The resource was successfully created." severity="information" />
   </statuses>
   <requested-amount currency="EUR">0.01</requested-amount>
   <account-holder>
       <first-name>John</first-name>
       <last-name>Doe</last-name>
       <email>john.doe@wirecard.com</email>
       <phone></phone>
       <address>
           <street1>123 anystreet</street1>
           <city>Brantford</city>
           <state>ON</state>
           <country>CA</country>
           <postal-code>M4P1E8</postal-code>
       </address>
   </account-holder>
   <shipping>
       <first-name>John</first-name>
       <last-name>Doe</last-name>
       <phone>+49123123123</phone>
       <address>
           <street1>123 anystreet</street1>
           <city>Brantford</city>
           <country>CA</country>
           <postal-code>M4P1E8</postal-code>
       </address>
   </shipping>
   <order-number>180924120801003</order-number>
   <notifications>
       <notification url="https://merchant.com/ipn.php"></notification>
   </notifications>
   <payment-methods>
       <payment-method url="https://demoshop-test.wirecard.com/demoshop/rest/sandbox/bcmc/payment?redirectionVersion=IR_WS_2.6&amp;redirectionData=9e471b1c-1c0a-4a78-978c-28f3ae7fac4c" name="bancontact" />
   </payment-methods>
   <bank-account>
       <account-number></account-number>
       <bank-code></bank-code>
   </bank-account>
   <cancel-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/cancel</cancel-redirect-url>
   <fail-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/error</fail-redirect-url>
   <success-redirect-url>https://demoshop-test.wirecard.com/demoshop/#/success</success-redirect-url>
</payment>
debit Request (Failure)
<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment">
   <merchant-account-id>86f03c98-6691-421d-94c8-232c3d5c2573</merchant-account-id>
   <request-id>qqaaq20e15877-d5fb-4893-a260-1edaba911fbf</request-id>
   <transaction-type>debit</transaction-type>
   <requested-amount currency="EUR">0.01</requested-amount>
   <payment-methods>
      <payment-method name="bancontact" />
   </payment-methods>
   <order-number>180924114516811111111111111111111111175</order-number>
</payment>
debit Response (Failure)
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<payment xmlns="http://www.elastic-payments.com/schema/payment" xmlns:ns2="http://www.elastic-payments.com/schema/epa/transaction">
   <merchant-account-id>86f03c98-6691-421d-94c8-232c3d5c2573</merchant-account-id>
   <transaction-id>e2b6b05b-d76d-4d3a-9159-36af9b65a49f</transaction-id>
   <request-id>qqaaq20e15877-d5fb-4893-a260-1edaba911fbf</request-id>
   <transaction-type>debit</transaction-type>
   <transaction-state>failed</transaction-state>
   <completion-time-stamp>2018-09-24T09:58:58.000Z</completion-time-stamp>
   <statuses>
      <status code="400.1132" description="The Order Number is too long. Please check." severity="error" />
   </statuses>
   <requested-amount currency="EUR">0.01</requested-amount>
   <order-number>180924114516811111111111111111111111175</order-number>
   <payment-methods>
      <payment-method name="bancontact" />
   </payment-methods>
</payment>
Payment Page
debit Request (Successful)
var requestData = {
  "request_id" : "75887972-6777-4af6-96fb-1c5419d2e80f",
  "request_time_stamp" : "20170201131500",
  "merchant_account_id" : "9e1b95df-3928-4256-af7b-2431a3c16c33",
  "transaction_type" : "debit",
  "requested_amount" : "0.01",
  "requested_amount_currency" : "EUR",
  "request_signature" : "6bb0393236df76463afcfb2a41ddbe43e13635aab2eac9115be9a9cfc3cfc2cb",
  "first_name" : "John",
  "last_name" : "Doe",
  "email" : "john.doe@wirecard.com",
  "street1" : "123 anystreet",
  "city" : "Brantford",
  "state" : "ON",
  "country" : "CA",
  "postal_code" : "M4P1E8",
  "order_number" : "488037",
  "shipping_first_name" : "John",
  "shipping_last_name" : "Doe",
  "shipping_street1" : "123 anystreet",
  "shipping_city" : "Brantford",
  "shipping_country" : "CA",
  "shipping_postal_code" : "M4P1E8",
  "notification_url" : "https://merchant.com/ipn.php",
  "success_redirect_url" : "https://demoshop-test.wirecard.com/demoshop/#/success",
  "fail_redirect_url" : "https://demoshop-test.wirecard.com/demoshop/#/error"
};
WirecardPaymentPage.hostedPay(requestData);

Wirecard Payment Page v2

General Information

This is a reference page for Bancontact. Here you find all the information necessary for integrating this payment method in your Hosted and Embedded Payment Page.

Are you unfamiliar with Wirecard Payment Page v2 (WPP v2)?
Visit one of the integration guides (Hosted, Embedded) for a quick explanation and a step-by-step guide before continuing.

All WPP v2 integrations share a common process flow for creating payments.

Below, you find an example request for the available transaction type debit, including field lists with short descriptions.

You need to complete these requests with your production credentials. You receive your credentials with your Wirecard contract. If you need your production credentials, contact merchant support.

Testing Bancontact

Bancontact does not offer a payment testing sandbox. You need to test transactions with your production credentials.

For more details on the redirect-url, see the Configuring Redirects and IPNs for WPP v2 section.

For response verification examples, see the WPP v2 Security section.

About Bancontact

Bancontact is the most popular online payment method in Belgium. It is used in more than 80% of Belgian web shops. It allows consumers to pay with Belgian credit cards.

  • With the Bancontact mobile app, one can pay back friends without cash immediately after they took over a payment (e.g. at a restaurant).

  • Invoices can be paid at home using the Bancontact mobile app. The app is used in a growing number of businesses and stores to pay bills without the hassle of a card reader.

Countries and Currencies

Bancontact can be used by consumers with a bank account in Belgium. The available payment currency for consumers is EUR.

Test Credentials

Test Credentials for Transaction Type debit.

URL (Endpoint)

https://wpp-test.wirecard.com/api/payment/register

Merchant Account ID (MAID)

86f03c98-6691-421d-94c8-232c3d5c2573

Username

16390-testing

Password

3!3013=D3fD8X7

Secret Key (used for response verification)

2341ae35-aa13-4511-95d5-acd80f0fcb52

Transaction Type debit

A debit transaction charges the specified amount from the account holder’s bank account and marks it for immediate transfer.

For a successful debit transaction:

  1. Create a payment session (initial request).

  2. Redirect the consumer to the payment page (initial response URL).

  3. Highly recommended: Parse and process the payment response.

We provide ready-made JSON examples for each step of this process. You can find them below.

Endpoint for Bancontact transactions.

Initial Request

This example is an initial request which creates the payment session. If it is successful, you receive a URL as a response, which redirects to the Bancontact payment form.

Request Headers

Authorization

Basic MTYzOTAtdGVzdGluZzozITMwMTM9RDNmRDhYNw==

Content-Type

application/json

Optional fields

For a full list of optional fields you can use, see the REST API Bancontact specification.

1. Create a Payment Session (Initial Request)
{
  "payment": {
    "merchant-account-id": {
      "value": "86f03c98-6691-421d-94c8-232c3d5c2573"
    },
    "request-id": "{{$guid}}",
    "transaction-type": "debit",
    "requested-amount": {
      "value": 10,
      "currency": "EUR"
    },
    "payment-methods": {
      "payment-method": [
        {
          "name": "bancontact"
        }
      ]
    },
    "account-holder": {
      "first-name": "John",
      "last-name": "Doe"
    },
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error"
  }
}
Field (JSON) Data Type Cardinality Size Description

merchant-account-id

value

String

Mandatory

36

A unique identifier assigned to every merchant account (by Wirecard).

request-id

String

Mandatory

150

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later. {{$guid}} serves as a placeholder for a random request-id.

Allowed characters: [a-z0-9-_]

transaction-type

String

Mandatory

36

The requested transaction type. For Bancontact payments, the transaction-type must be set to debit.

requested-amount

value

Numeric

Mandatory

18

The full amount that is requested/contested in a transaction. 2 decimal digits allowed.

Use . (decimal point) as the separator.

currency

String

Mandatory

3

The currency of the requested/contested transaction amount. For Bancontact payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

payment-methods

payment-method

name

String

Mandatory

15

The name of the payment method used. Set this value to bancontact.

account-holder

first-name

String

Optional

32

The first name of the account holder.

last-name

String

Requested

32

The last name of the account holder.

success-redirect-url

String

Mandatory

2000

The URL to which the consumer is redirected after a successful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/success

fail-redirect-url

String

Mandatory

2000

The URL to which the consumer is redirected after a failed payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/error

cancel-redirect-url

String

Mandatory

2000

The URL to which the consumer is redirected after having canceled a payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/cancel

2. Redirect the consumer to the Payment Page (Initial Response URL)
{
  "payment-redirect-url": "https://wpp-test.wirecard.com/processing?wPaymentToken=UvnC2LM5QuDotVHTmfV2t4AZn9dJpZNt6dFAwxZHdvU"
}
Field (JSON) Data Type Description

payment-redirect-url

String

The URL which redirects to the payment form. Sent as a response to the initial request.

At this point, you need to redirect your consumer to payment-redirect-url (or render it in an iframe depending on your integration method).

Consumers are redirected to the payment form. There they enter their data and submit the form to confirm the payment. A payment can be:

  • successful (transaction-state: success),

  • failed (transaction-state: failed),

  • canceled. The consumer canceled the payment before/after submission (transaction-state: failed).

The transaction result is the value of transaction-state in the payment response. More details (including the status code) can also be found in the payment response in the statuses object. Canceled payments are returned as failed, but the status description indicates it was canceled.

In any case (unless the consumer cancels the transaction on a 3rd party provider page), a base64 encoded response containing payment information is sent to the configured redirection URL. See Configuring Redirects and IPNs for WPP v2 for more details on redirection targets after payment & transaction status notifications.

You can find a decoded payment response example below.

3. Parse and Process the Payment Response (Decoded Payment Response)
{
  "payment": {
    "merchant-account-id": {
      "value": "your-custom-MAID-..."
    },
    "request-id": "66b62159-691f-40e3-8411-24c854bb0f8b",
    "transaction-type": "debit",
    "parent-transaction-id": "8d2ec658-d234-44cb-b557-791489e8464f",
    "payment-methods": {
      "payment-method": [
        {
          "name": "bancontact"
        }
      ]
    },
    "transaction-state": "success",
    "transaction-id": "The-transaction-id-received-here-is-the-parent-transaction-id-of-the-following-capture-authorization",
    "completion-time-stamp": "2018-09-26T05:54:20",
    "requested-amount": {
      "currency": "EUR",
      "value": 10.1
    },
    "statuses": {
      "status": [
        {
          "description": "The resource was successfully created.",
          "severity": "information",
          "code": "201.0000"
        }
      ]
    },
    "api-id": "{api-id]",
    "success-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/success",
    "cancel-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/cancel",
    "fail-redirect-url": "https://demoshop-test.wirecard.com/demoshop/#/error"
  }
}
Field (JSON) Data Type Description

merchant-account-id

value

String

A unique identifier assigned to every merchant account (by Wirecard).

request-id

String

A unique identifier assigned to every request (by merchant). Used when searching for or referencing it later.

transaction-type

String

The requested transaction type. For Bancontact payments, the transaction-type must be set to debit.

parent-transaction-id

String

The ID of the transaction being referenced as a parent.

payment-methods

payment-method

name

String

The name of the payment method used.

transaction-state

String

The current transaction state.

Possible values:

  • in-progress

  • success

  • failed

Typically, a transaction starts with state in-progress and finishes with state either success or failed. This information is returned in the response only.

transaction-id

String

A unique identifier assigned to every transaction (by Wirecard). Used when searching for or referencing to it later.

completion-time-stamp

YYYY-MM-DD-Thh:mm:ss

The UTC/ISO time-stamp documents the time & date when the transaction was executed.

Format: YYYY-MM-DDThh:mm:ss (ISO).

requested-amount

currency

String

The currency of the requested/contested transaction amount. For Bancontact payments, the currency must be set to EUR.

Format: 3-character abbreviation according to ISO 4217.

value

Numeric

The full amount that is requested/contested in a transaction.

statuses

status

description

String

The description of the transaction status message.

severity

String

The definition of the status message.

Possible values:

  • information

  • warning

  • error

code

String

Status code of the status message.

api-id

String

Identifier of the currently used API.

success-redirect-url

String

The URL to which the consumer is redirected after a successful payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/success

cancel-redirect-url

String

The URL to which the consumer is redirected after having canceled a payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/cancel

fail-redirect-url

String

The URL to which the consumer is redirected after a failed payment, e.g. https://demoshop-test.wirecard.com/demoshop/#/error

Custom URL: