📘

Only available for certain acquirers in BENELUX

👍

Your account must be enabled for Bancontact WIP

During onboarding, we configure the Bancontact wallet identifier and 3-D Secure capability. These values are merchant configuration and must not be included in Checkout requests.

Introduction

Bancontact Wallet Initiated Payments (WIP) let a merchant tokenize an authenticated Bancontact card during a customer-present Checkout payment, then use the saved token for a later card payment.

Supported Flow

Use a SALE when the registration should also collect payment. Use ZERO-AUTH only when Fiserv has confirmed that zero-amount Bancontact WIP registration is enabled for the store. The merchant must obtain the customer's agreement for the initial storage and for any future payments before creating or using a token.

Checkout Contract

This guide applies to POST /v2/checkouts/payment-sessions.

The public Checkout contract differs from the downstream IPG REST API:

• Put createToken directly under paymentMethodDetails.
• Put tokenBasedTransaction directly under paymentMethodDetails.
• Do not send walletType. Checkout derives BANCONTACT_WALLET internally when WIP is enabled for the store.
• Do not use the legacy paths paymentMethodDetails.cards.createToken or paymentMethodDetails.cards.tokenBasedTransaction for new integrations.

1. Register a Bancontact WIP Token

Create the payment session from the merchant backend. The customer completes the card and any required 3-D Secure interaction in the hosted Checkout experience.

POST /v2/checkouts

{
  "merchantTransactionId": "WIP-REGISTER-10001",
  "storeId": "{{storeId}}",
  "transactionType": "SALE",
  "transactionAmount": {
    "total": 26.00,
    "currency": "EUR",
    "components": {
      "subtotal": 21.00,
      "vatAmount": 2.00,
      "shipping": 3.00
    }
  },
  "order": {
    "orderId": "ORDER-10001"
  },
  "paymentMethodDetails": {
    "createToken": {
      "toBeUsedFor": "UNSCHEDULED",
      "reusable": true,
      "declineDuplicates": false,
      "customWalletRegistration": {
        "authenticationMethods": [
          "BIOMETRICS_AUTHENTICATION"
        ]
      }
    }
  },
  "checkoutSettings": {
    "locale": "nl_BE",
    "preSelectedPaymentMethod": "Cards",
    "webHooksUrl": "https://merchant.example/webhooks/payments",
    "redirectBackUrls": {
      "successUrl": "https://merchant.example/payments/return/success",
      "failureUrl": "https://merchant.example/payments/return/failure"
    }
  }
}

Registration Fields

Supported authenticationMethod values are:

• USERNAME_PASSWORD_PIN
• SECRET_KEY_HARDWARE
• SECRET_KEY_SOFTWARE
• LOCATION_BASED_AUTHENTICATION
• ENVIRONMENTAL_AUTHENTICATION
• BEHAVIORAL_AUTHENTICATION
• BIOMETRICS_AUTHENTICATION
• OUT_OF_BAND_USER_AUTHENTICATION

Multiple values may be supplied when multiple methods were used. Do not select a value merely because it is supported; the value is an assertion about the merchant's authentication process.

Complete the Registration

1. The shopper enters the Bancontact card in the hosted card fields and completes any required 3-D Secure step.
2. Process the server-side payment outcome before treating the registration as complete.
3. Persist the token only from the authoritative approved response or webhook. Treat the token as an opaque credential and associate it with the customer agreement, store ID, and initial transaction reference.

2. Submit a Subsequent WIP Payment

Create a new Checkout payment session and supply the saved token. No plaintext PAN or CVV belongs in this request.

{
  "merchantTransactionId": "WIP-SUBSEQUENT-10002",
  "storeId": "{{storeId}}",
  "transactionType": "SALE",
  "transactionAmount": {
    "total": 14.50,
    "currency": "EUR"
  },
  "order": {
    "orderId": "ORDER-10002"
  },
  "paymentMethodDetails": {
    "tokenBasedTransaction": {
      "value": "{{bancontactWipToken}}",
      "transactionSequence": "SUBSEQUENT",
      "schemeTransactionId": "{{initialSchemeTransactionId}}"
    }
  },
  "checkoutSettings": {
    "locale": "nl_BE",
    "webHooksUrl": "https://merchant.example/webhooks/payments",
    "redirectBackUrls": {
      "successUrl": "https://merchant.example/payments/return/success",
      "failureUrl": "https://merchant.example/payments/return/failure"
    }
  }
}

Each subsequent payment needs a new merchant transaction and order reference. A valid token does not guarantee approval. Do not retry a decline blindly, and do not attempt to replace the payment with a new customer charge without applying the merchant's agreed customer-notification and retry policy.