Bancontact Mobile via Nuvei Acquiring

Home    APMs    Bancontact Mobile via Nuvei Acquiring

On this page:
Attributes
  • METHOD TYPECards
  • PAYMENTS
  • PAYOUTS
  • REFUNDS
  • RECURRING

Introduction

Nuvei’s Bancontact Mobile payment solution offers merchants the following options for initiating payments:

Initiation TypeInitiation FlowSame Device Used for Purchasing and PaymentDifferent Devices Used for Purchasing and Payment
Nuvei Hosted Payment PageMerchant redirects the user to the Nuvei’s Bancontact payment page (see User Experience), which includes both a QR code and a payment app launch button.YesYes
QR code generation by merchantMerchant generates a Bancontact payment QR code using the metadata received from Nuvei and presents it on their website, allowing the user to scan it with their mobile device.NoYes
Payment app redirectMerchant uses a URL received from Nuvei to redirect the user to the Bancontact payment app installed on his mobile.YesNo

A special configuration is required from Nuvei’s side for some of the options; please contact Nuvei’s Integration Support Team.

Supported Countries

  • Belgium

Supported Currencies

  • EUR

Supported Transaction Types

The Bancontact Mobile solution allows merchants and customers to perform the following transaction types:

Transaction TypeDescriptionAuthentication Method
E-Commerce QR CodeA Card Not Present (CNP) payment transaction initiated when the customer scans a QR Code with their Bancontact mobile app (applicable for cases where different devices are used for shopping and paying).In-app authentication (fingerprint, code, etc.)
E-Commerce URL IntentA Card Not Present (CNP) payment transaction initiated when the customer presses the button for opening their Bancontact mobile app (applicable for cases where the same device is used for shopping and paying).In-app authentication (fingerprint, code, etc.)
RefundA full/partial credit transaction initiated using Bancontact card details or a token for product returns or purchase cancellations.N/A
PayoutOriginal credit transaction (OCT) initiated using Bancontact card details or a token for customer funding cases such as gambling winnings, insurance payouts, etc.N/A

Payment (Deposit) Flow

Press tab to open…

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters, including:

  • userTokenId
  • amount
  • currency
  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_Bancontact_DI“
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, country, email, address, city, phone, zip
  • userDetails class containing: firstName, lastName, country, email, address, city, phone, zip, dateOfBirth, gender
  • urlDetails class containing: successUrl, failureUrl, pendingUrl, appUrl
Example /payment Request
{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "100",
  "currency": "EUR",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Bancontact_DI"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "address": "22 Main Street",
    "city": "Brussels",
    "country": "BE",
    "email": "[email protected]",
    "phone": "323094526617",
    "zip": "1000"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "address": "22 Main Street",
    "city": "Brussels",
    "country": "BE",
    "email": "[email protected]",
    "phone": "323094526617",
    "zip": "1000",
    "dateOfBirth": "2000-06-30",
    "gender": "Male"
  },
  "urlDetails": {
    "successUrl": "<URL the customer is directed to after a successful transaction>", 
    "failureUrl": "<URL the customer is directed to after an unsuccessful transaction>", 
    "pendingUrl": "<URL the customer is directed to when the transaction response is pending>",
    "notificationUrl": "<URL to which DMNs are sent>",
    "appUrl": "<link to which the provider redirects the user at the end of the payment process>"
  },
  "timeStamp": "YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example /payment Response – Nuvei Hosted Payment Page
{
    "internalRequestId": 51672978106,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L",
    "sessionToken": "9e568da7-e5f7-437f-a400-848309c51e23",
    "clientUniqueId": "12345",
    "orderId": "47472448966",
    "userTokenId": "230811147",
    "paymentOption": {
        "redirectUrl": "https://cdn.safecharge.com/safecharge_resources/v1/qr-code-21382.html?qrCode=BEP://1BANCONTACTTMA.NUVEI.COM%2FBC%2FIPN%2FC478553BB431DACCEB6F8609D0F58AAD%2475B482599428AD3AC6D59E6B&requestDate=2023-10-03 14:18:19.850&merchantName=ProdTest&amount=1.00&currency=EUR&orderReference=2130000314658071&orderId=47472448966&wss=wss://ws.nuvei.com&sessionid=542a20fd51ca60c8bdf8ddcb14a7",
        "userPaymentOptionId": "3144614656",
        "card": {}
    },
    "transactionStatus": "REDIRECT"
}
Example /payment Response – QR Code Generation by Merchant
{
    "internalRequestId": 51379590866,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L",
    "sessionToken": "e8baa991-9cdc-407c-841e-44597da42bd9",
    "clientUniqueId": "12345",
    "orderId": "47263813886",
    "userTokenId": "230811147",
    "paymentOption": {
        "redirectUrl": "BEP://1BANCONTACTTMA.NUVEI.COM/BC/IPN/757D9C02EE6B8EB2DA5928CBA0767D0C$77A8335CDBB8CC57C47CEE54",
        "userPaymentOptionId": "3126116956",
        "card": {}
    },
    "transactionStatus": "REDIRECT"
}
Example /payment Response – Payment App Redirect
{
  "internalRequestId": 51206450946,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "427583496191624621",
  "merchantSiteId": "142033",
  "version": "1.0",
  "clientRequestId": "1C6CT7V1L",
  "sessionToken": "de3a397b-7cd2-44d7-9533-36d58f19b2d1",
  "clientUniqueId": "12345",
  "orderId": "47141663766",
  "userTokenId": "230811147",
  "paymentOption": {
    "redirectUrl": "{\"QRCode\":\"BEP://1BANCONTACTTMA.NUVEI.COM/BC/IPN/00E155D5174EEB7799956416E468AAB0$F1C0ADCDFBC4D4507F1C27CA\",\"APPLink\":\"BEPGenApp://DoTx?TransId=1BANCONTACTTMA.NUVEI.COM/BC/IPN/00E155D5174EEB7799956416E468AAB0$F1C0ADCDFBC4D4507F1C27CA\",\"RedirectUrl\":\"https://cdn.safecharge.com/safecharge_resources/v1/qr-code-21382.html?qrCode=BEP://1BANCONTACTTMA.NUVEI.COM%2FBC%2FIPN%2F00E155D5174EEB7799956416E468AAB0%24F1C0ADCDFBC4D4507F1C27CA&requestDate=2023-09-26 16:08:26.620&merchantName=ProdTest&amount=1.00&currency=EUR&orderReference=1120000008046520&orderId=47141663766&wss=wss://ws.nuvei.com&sessionid=19aedeab3edfc1d8369c94f5e3f3\"}",
    "userPaymentOptionId": "3115389756",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Follow these steps to perform a payment using Nuvei Web SDK integration.

1. Initiate a Session

Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.

2. Initialize the Web SDK

Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.

3. Create an APM Payment

Send a createPayment() request with its mandatory parameters including:

  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_Bancontact_DI“
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, country, email, address, phone, city, zip
  • userDetails class containing:firstName, lastName, country, email, address, phone, city, zip
  • urlDetails class containing: successUrl, failureUrl, pendingUrl, appUrl
Example createPayment() Request
sfc.createPayment({
  sessionToken: "<sessiontoken>",
  paymentOption : {        
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Bancontact_DI"
  }},           
  deviceDetails:{
    ipAddress:"<customer's IP address>"
  },
  billingAddress: {
    firstName: "John",
    lastName: "Smith",
    country: "BE",
    email:"[email protected]",
    phone: "323094526617",
    address: "22 Main Street",
    city: "Brussels",
    zip: "1000"
  },   
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    country: "BE",
    email:"[email protected]",
    phone: "323094526617",
    address: "22 Main Street",
    city: "Brussels",
    zip: "1000"
  },
  urlDetails: {
    successUrl: "<URL the customer is directed to after a successful transaction>", 
    failureUrl: "<URL the customer is directed to after an unsuccessful transaction>", 
    pendingUrl: "<URL the customer is directed to when the transaction response is pending>",
    notificationUrl: "<URL to which DMNs are sent>",
    appUrl: "<link to which the provider redirects the user at the end of the payment process>"
  },
}, function(res) {
      console.log(res);
});
Example createPayment() Response
{
    "internalRequestId": 50704983196,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "5555385017539610145",
    "merchantSiteId": "171738",
    "version": "1.0",
    "clientRequestId": null,
    "hint": null,
    "resultStatus": null,
    "resultCode": null,
    "resultDescription": null,
    "sessionToken": "9f3caa1b-eb03-459e-a8ef-e31d8470a7af",
    "clientUniqueId": "12345",
    "orderId": "46784400856",
    "userTokenId": "testUserToken1234",
    "paymentOption": {
      "redirectUrl": "https://cdn.safecharge.com/safecharge_resources/v1/qr-code-21382.html?qrCode=BEP://1BANCONTACTTMA.NUVEI.COM%2FBC%2FIPN%2FC478553BB431DACCEB6F8609D0F58AAD%2475B482599428AD3AC6D59E6B&requestDate=2023-10-03 14:18:19.850&merchantName=ProdTest&amount=1.00&currency=EUR&orderReference=2130000314658071&orderId=47472448966&wss=wss://ws.nuvei.com&sessionid=542a20fd51ca60c8bdf8ddcb14a7",
      "userPaymentOptionId": ""
      "card": {}
    },
    "transactionStatus": "REDIRECT",    
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /openOrder request.

REST API

Follow these steps to perform a payment using Nuvei REST API integration:

1. Generate a sessionToken

Press here for details.

2. Send a /payment Request

Perform the payment by sending a /payment request with its mandatory parameters, including:

  • userTokenId
  • amount
  • currency
  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_Bancontact_DI“
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, country, email, address, city, phone, zip
  • userDetails class containing: firstName, lastName, country, email, address, city, phone, zip, dateOfBirth, gender
  • urlDetails class containing: successUrl, failureUrl, pendingUrl, appUrl
Example /payment Request
{
  "sessionToken": "<sessionToken from /getSessionToken>",
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "100",
  "currency": "EUR",
  "userTokenId": "<unique customer identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "paymentOption": {
    "alternativePaymentMethod": {
      "paymentMethod": "apmgw_Bancontact_DI"
    }
  },
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "billingAddress": {
    "firstName": "John",
    "lastName": "Smith",
    "address": "22 Main Street",
    "city": "Brussels",
    "country": "BE",
    "email": "[email protected]",
    "phone": "323094526617",
    "zip": "1000"
  },
  "userDetails": {
    "firstName": "John",
    "lastName": "Smith",
    "address": "22 Main Street",
    "city": "Brussels",
    "country": "BE",
    "email": "[email protected]",
    "phone": "323094526617",
    "zip": "1000",
    "dateOfBirth": "2000-06-30",
    "gender": "Male"
  },
  "urlDetails": {
    "successUrl": "<URL the customer is directed to after a successful transaction>", 
    "failureUrl": "<URL the customer is directed to after an unsuccessful transaction>", 
    "pendingUrl": "<URL the customer is directed to when the transaction response is pending>",
    "notificationUrl": "<URL to which DMNs are sent>",
    "appUrl": "<link to which the provider redirects the user at the end of the payment process>"
  },
  "timeStamp": "YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example /payment Response – Nuvei Hosted Payment Page
{
    "internalRequestId": 51672978106,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L",
    "sessionToken": "9e568da7-e5f7-437f-a400-848309c51e23",
    "clientUniqueId": "12345",
    "orderId": "47472448966",
    "userTokenId": "230811147",
    "paymentOption": {
        "redirectUrl": "https://cdn.safecharge.com/safecharge_resources/v1/qr-code-21382.html?qrCode=BEP://1BANCONTACTTMA.NUVEI.COM%2FBC%2FIPN%2FC478553BB431DACCEB6F8609D0F58AAD%2475B482599428AD3AC6D59E6B&requestDate=2023-10-03 14:18:19.850&merchantName=ProdTest&amount=1.00&currency=EUR&orderReference=2130000314658071&orderId=47472448966&wss=wss://ws.nuvei.com&sessionid=542a20fd51ca60c8bdf8ddcb14a7",
        "userPaymentOptionId": "3144614656",
        "card": {}
    },
    "transactionStatus": "REDIRECT"
}
Example /payment Response – QR Code Generation by Merchant
{
    "internalRequestId": 51379590866,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "427583496191624621",
    "merchantSiteId": "142033",
    "version": "1.0",
    "clientRequestId": "1C6CT7V1L",
    "sessionToken": "e8baa991-9cdc-407c-841e-44597da42bd9",
    "clientUniqueId": "12345",
    "orderId": "47263813886",
    "userTokenId": "230811147",
    "paymentOption": {
        "redirectUrl": "BEP://1BANCONTACTTMA.NUVEI.COM/BC/IPN/757D9C02EE6B8EB2DA5928CBA0767D0C$77A8335CDBB8CC57C47CEE54",
        "userPaymentOptionId": "3126116956",
        "card": {}
    },
    "transactionStatus": "REDIRECT"
}
Example /payment Response – Payment App Redirect
{
  "internalRequestId": 51206450946,
  "status": "SUCCESS",
  "errCode": 0,
  "reason": "",
  "merchantId": "427583496191624621",
  "merchantSiteId": "142033",
  "version": "1.0",
  "clientRequestId": "1C6CT7V1L",
  "sessionToken": "de3a397b-7cd2-44d7-9533-36d58f19b2d1",
  "clientUniqueId": "12345",
  "orderId": "47141663766",
  "userTokenId": "230811147",
  "paymentOption": {
    "redirectUrl": "{\"QRCode\":\"BEP://1BANCONTACTTMA.NUVEI.COM/BC/IPN/00E155D5174EEB7799956416E468AAB0$F1C0ADCDFBC4D4507F1C27CA\",\"APPLink\":\"BEPGenApp://DoTx?TransId=1BANCONTACTTMA.NUVEI.COM/BC/IPN/00E155D5174EEB7799956416E468AAB0$F1C0ADCDFBC4D4507F1C27CA\",\"RedirectUrl\":\"https://cdn.safecharge.com/safecharge_resources/v1/qr-code-21382.html?qrCode=BEP://1BANCONTACTTMA.NUVEI.COM%2FBC%2FIPN%2F00E155D5174EEB7799956416E468AAB0%24F1C0ADCDFBC4D4507F1C27CA&requestDate=2023-09-26 16:08:26.620&merchantName=ProdTest&amount=1.00&currency=EUR&orderReference=1120000008046520&orderId=47141663766&wss=wss://ws.nuvei.com&sessionid=19aedeab3edfc1d8369c94f5e3f3\"}",
    "userPaymentOptionId": "3115389756",
    "card": {}
  },
  "transactionStatus": "REDIRECT"
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payment request.

Web SDK

Follow these steps to perform a payment using Nuvei Web SDK integration.

1. Initiate a Session

Before you can submit payment using the client-side Nuvei Web SDK, you need to send the /openOrder API call.

2. Initialize the Web SDK

Instantiate the Web SDK with the sessionToken received from the server call to /openOrder.

3. Create an APM Payment

Send a createPayment() request with its mandatory parameters including:

  • paymentOption.alternativePaymentMethod class containing:
    • paymentMethod: “apmgw_Bancontact_DI“
  • deviceDetails class containing: ipAddress
  • billingAddress class containing: firstName, lastName, country, email, address, phone, city, zip
  • userDetails class containing:firstName, lastName, country, email, address, phone, city, zip
  • urlDetails class containing: successUrl, failureUrl, pendingUrl, appUrl
Example createPayment() Request
sfc.createPayment({
  sessionToken: "<sessiontoken>",
  paymentOption : {        
    alternativePaymentMethod: {
      paymentMethod: "apmgw_Bancontact_DI"
  }},           
  deviceDetails:{
    ipAddress:"<customer's IP address>"
  },
  billingAddress: {
    firstName: "John",
    lastName: "Smith",
    country: "BE",
    email:"[email protected]",
    phone: "323094526617",
    address: "22 Main Street",
    city: "Brussels",
    zip: "1000"
  },   
  userDetails: {
    firstName: "John",
    lastName: "Smith",
    country: "BE",
    email:"[email protected]",
    phone: "323094526617",
    address: "22 Main Street",
    city: "Brussels",
    zip: "1000"
  },
  urlDetails: {
    successUrl: "<URL the customer is directed to after a successful transaction>", 
    failureUrl: "<URL the customer is directed to after an unsuccessful transaction>", 
    pendingUrl: "<URL the customer is directed to when the transaction response is pending>",
    notificationUrl: "<URL to which DMNs are sent>",
    appUrl: "<link to which the provider redirects the user at the end of the payment process>"
  },
}, function(res) {
      console.log(res);
});
Example createPayment() Response
{
    "internalRequestId": 50704983196,
    "status": "SUCCESS",
    "errCode": 0,
    "reason": "",
    "merchantId": "5555385017539610145",
    "merchantSiteId": "171738",
    "version": "1.0",
    "clientRequestId": null,
    "hint": null,
    "resultStatus": null,
    "resultCode": null,
    "resultDescription": null,
    "sessionToken": "9f3caa1b-eb03-459e-a8ef-e31d8470a7af",
    "clientUniqueId": "12345",
    "orderId": "46784400856",
    "userTokenId": "testUserToken1234",
    "paymentOption": {
      "redirectUrl": "https://cdn.safecharge.com/safecharge_resources/v1/qr-code-21382.html?qrCode=BEP://1BANCONTACTTMA.NUVEI.COM%2FBC%2FIPN%2FC478553BB431DACCEB6F8609D0F58AAD%2475B482599428AD3AC6D59E6B&requestDate=2023-10-03 14:18:19.850&merchantName=ProdTest&amount=1.00&currency=EUR&orderReference=2130000314658071&orderId=47472448966&wss=wss://ws.nuvei.com&sessionid=542a20fd51ca60c8bdf8ddcb14a7",
      "userPaymentOptionId": ""
      "card": {}
    },
    "transactionStatus": "REDIRECT",    
}

After the transaction is processed, Nuvei sends a Direct Merchant Notification (DMN) that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /openOrder request.

Payout (Withdrawal) Flow

You can perform a payout using a previously captured UPO (where the UPO was returned from a previous /payment request).

Send a /payout request with its mandatory parameters including:

  • userTokenId
  • A previously generated userPaymentOptionId
Example /payout Request with UPO
{
  "merchantId": "<your merchantId>",
  "merchantSiteId": "<your merchantSiteId>",
  "userTokenId": "<unique user identifier in merchant system>",
  "clientUniqueId": "<unique transaction ID in merchant system>",
  "clientRequestId": "<unique request ID in merchant system>",
  "amount": "200",
  "currency": "EUR",
  "userPaymentOption": {
    "userPaymentOptionId": "<UPO received from a previous request>"
  },  
  "deviceDetails": {
    "ipAddress": "<customer's IP address>"
  },
  "timeStamp": "<YYYYMMDDHHmmss>",
  "checksum": "<calculated checksum>"
}
Example /payout Response with UPO
{
  "userTokenId":"EV013",
  "clientUniqueId":"20230329125742",
  "transactionStatus":"APPROVED",
  "gwErrorCode":0,
  "gwExtendedErrorCode":0,
  "userPaymentOptionId":"80244118",
  "externalTransactionId":"",
  "transactionId":"711000000021780909",
  "cardData":{
    "acquirerId":"19",
    "visaDirect":"NO"
  },
  "internalRequestId":639118498,
  "status":"SUCCESS",
  "errCode":0,
  "reason":"",
  "merchantId":"979047831696752006",
  "merchantSiteId":"217268",
  "version":"1.0"
}

After the transaction is processed, Nuvei sends a DMN that includes the result of the transaction to urlDetails.notificationUrl, which Nuvei recommends including in the /payout request.

For more details, please see Payout.

User Experience

Nuvei-Hosted Payment Page

The mobile device digital wallet performs authentication (fingerprint, face recognition, and so on.). There is no need for 3D-Secure.

  1. The user is redirected to a payment page.
  2. The user either presses Use the app or scans the QR code with the Payconiq by Bancontact mobile app to proceed to payment.
  3. In the app, the user:
    1. Reviews and confirms the transaction and merchant details.
    2. Performs in-app authentication (PIN code, fingerprint, and so on).
    3. Chooses a card for payment.

A successful/failed transaction message appears on the screen.

Last update iconLast modified November 2024