General

For a Bancontact transaction the merchant starts by sending the request to a BPE transaction gateway. The gateway processes the request and sends a response to the merchant. If the request is sent to a gateway without a customer redirect, the response will contain a redirect URL to which the customer must be redirected. If in the original request the customer was already redirected to the public gateway, the customer is automatically redirected to this page by the transaction gateway. Once the customer reaches this page, he can enter his card details. Once these have been entered and verified and the card is not secured with a 3D Secure code, the payment is processed immediately and the customer will be redirected back to the merchant website, along with the result. If the card is secured with a 3D Secure code, the customer is redirected to the 3D Secure page for its specific card. After completing the process at this page, the customer returns to the BPE transaction gateway and the Payment Engine will process the credit card payment, after which the customer is also redirected back to the merchant website, along with the payment result. Additionally, the Payment Engine will also perform a Transaction Push, with the status of the payment.

Servicecodes and actions

The servicecode for Bancontact is: bancontactmrcash

The Bancontact service supports the following actions: Pay, Refund. Both actions can be used with channel 'Web'.

Recurring payments

It is also possible to use a Bancontact transaction as a reference transaction for recurring SEPA Direct Debit transactions. To do this, add the basic parameter "StartRecurrent" with value "True" to your Bancontact API request. Once successful, you can perform a recurring SEPA direct debit transaction. Please see the SEPA Direct Debit section for an explanation of the "PayRecurrent" request.

Bancontact app

When Buckaroo is your Bancontact acquirer, it is possible for the customer to finish a Bancontact transaction with the Bancontact app. The "pay with Bancontact app"-button will appear automatically when the customer is redirected to the Buckaroo checkout, below the fields where the customer can enter its card data. When a customer clicks on this button, it will either see a QR-code which the customer can scan with its Bancontact app, or, when a customer is on a mobile device, it will be redirected directly to the Bancontact app, and the customer can finish the transaction.

It is also possible to show this button (and show the QR-code, or redirect to the Bancontact app) on your own webshop checkout. To be able to do this you have to implement our Client SDK. And initiate a server side Pay request. With the "Key" given in the Pay response, you can call the Client SDK like this:

$(document).ready(function() { BuckarooSdk.BancontactMobile.initiate("#bancontactMobileButton", "TransactionKey"); });

Where "#bancontactMobileButton" is the id of the location where you want to show the button.

Click here for more information about our Client SDK.

App or Card on your own webshop checkout

It is also possible to let the consumer choose between paying with the Bancontact App or Bancontact Card on your own webshop checkout. Al you have to do is send a Pay request to our Transaction API. And send a GET request to https://checkout.buckaroo.nl/api/BancontactMobile/GetCodeUrl?transactionKey=*TRANSACTIONKEY* where *TRANSACTIONKEY* is the retrieved transaction key from the Pay request. The response contains the data you have to use to show the QR-Code. When the consumer pays with the Bancontact App, you don't have to do anything. When the consumer pays with its Bancontact Card, you have to send the encrypted card data in a CompletePayment request to our DataRequest API to complete the payment.

Pay

This action is used to perform a single payment with the Bancontact card.

View in playground

Request


JSON gateway request

This action does not have service specific request variables.

JSON

copy
{
  "Currency": "EUR",
  "AmountDebit": 10.00,
  "Invoice": "testinvoice 123",
  "ClientIP": {
      "Type": 0,
      "Address": "0.0.0.0"
   },
  "Services": {
    "ServiceList": [
      {
        "Name": "bancontactmrcash",
        "Action": "Pay"
      }
    ]
  }
}

Response


JSON gateway response

If the request has a valid structure and a valid signature, a transaction will be created in the Payment Engine and a response will be returned. In this case, an additional action is required before the transaction can be completed. The customer needs to be redirected to the payment environment through the returned redirect URL. The response does not contain service specific variables.

JSON

copy
{
    "Key": "0EF39AA94BD64FF38F1540DEB6XXXXXX",
    "Status": {
        "Code": {
            "Code": 790,
            "Description": "Pending input"
        },
        "SubCode": null,
        "DateTime": "2017-03-30T12:50:36"
    },
    "RequiredAction": {
        "RedirectURL": "https://testcheckout.buckaroo.nl/html/redirect.ashx?r=77C66A69FF4240DBB497CA73E5XXXXXX",
        "RequestedInformation": null,
        "PayRemainderDetails": null,
        "Name": "Redirect",
        "TypeDeprecated": 0
    },
    "Services": null,
    "CustomParameters": null,
    "AdditionalParameters": null,
    "RequestErrors": null,
    "Invoice": "testinvoice 123",
    "ServiceCode": null,
    "IsTest": true,
    "Currency": "EUR",
    "AmountDebit": 10,
    "TransactionType": null,
    "MutationType": 0,
    "RelatedTransactions": null,
    "ConsumerMessage": null,
    "Order": null,
    "IssuingCountry": null,
    "StartRecurrent": false,
    "Recurring": false,
    "CustomerName": null,
    "PayerHash": null,
    "PaymentKey": null
}

Push


JSON push response

CardNumberEnding

Last 4 digits of the card number.

CardExpirationDate

Card expiration date.

MaskedCardNumber

Masked card number.

CustomerIBAN

The customer's IBAN.

CustomerBIC

The BIC code belonging to the customer's IBAN.

InputType

The way the transaction was paid. Possible values are: "Manual" for a regular payment; "QrCode" for a mobile payment paid by scanning the QR-code; "UrlIntent" for a mobile payment paid by clicking on the payment button on a mobile device.

JSON

copy
{
  "Transaction": {
    "Key": "0EF39AA94BD64FF38F1540DEB6XXXXXX",
    "Invoice": "testinvoice 123",
    "ServiceCode": "bancontactmrcash",
    "Status": {
      "Code": {
        "Code": 190,
        "Description": "Success"
      },
      "SubCode": {
        "Code": "S990",
        "Description": "The request was successful."
      },
      "DateTime": "2017-03-30T12:51:10"
    },
    "IsTest": true,
    "Order": null,
    "Currency": "EUR",
    "AmountDebit": 10,
    "TransactionType": "C090",
    "Services": [
      {
        "Name": "bancontactmrcash",
        "Action": null,
        "Parameters": [
          {
            "Name": "CardNumberEnding",
            "Value": "5015"
          },
          {
            "Name": "CardExpirationDate",
            "Value": "2017-03"
          },
          {
            "Name": "MaskedCreditcardNumber",
            "Value": "670342*******5015"
          },
          {
            "Name": "CustomerIban",
            "Value": "BE68xxxxxxxxx034"
          },
          {
            "Name": "CustomerBic",
            "Value": "BANKBEBB"
          },
	  {
	    "Name": "InputType",
	    "Value": "Manual"
	  }
        ],
        "VersionAsProperty": 1
      }
    ],
    "CustomParameters": null,
    "AdditionalParameters": null,
    "MutationType": 1,
    "RelatedTransactions": null,
    "IsCancelable": false,
    "IssuingCountry": null,
    "StartRecurrent": false,
    "Recurring": false,
    "CustomerName": "T. Tester",
    "PayerHash": "null",
    "PaymentKey": "3055B6E1FA6C493881CDFCC05DXXXXXX"
  }
}

Refund

The Refund action can be used to perform a refund on an earlier Bancontact transaction. In the past, this could only take place after the money had been received, but nowadays it can be done as soon as the Bancontact transaction is successful.

View in playground

Request


JSON gateway request

OriginalTransactionKey
Required

Transaction key of the payment that needs to be refunded. Please note: This is a basic request variable, not a service specific variable.

JSON

copy
{
  "Currency": "EUR",
  "AmountCredit": 1.00,
  "Invoice": "testinvoice 123",
  "OriginalTransactionKey": "0EF39AA94BD64FF38F1540DEB6XXXXXX",
  "Services": {
    "ServiceList": [
      {
        "Name": "bancontactmrcash",
        "Action": "Refund"
      }
    ]
  }
}

Response


JSON gateway response

The gateway response does not have service specific response variables.

JSON

copy
{
    "Key": "6C1012FAF0444C1C8283404DA7XXXXXX",
    "Status": {
        "Code": {
            "Code": 190,
            "Description": "Success"
        },
        "SubCode": {
            "Code": "S990",
            "Description": "The request was successful."
        },
        "DateTime": "2017-03-30T12:54:58"
    },
    "RequiredAction": null,
    "Services": null,
    "CustomParameters": null,
    "AdditionalParameters": null,
    "RequestErrors": null,
    "Invoice": "testinvoice 123",
    "ServiceCode": "bancontactmrcash",
    "IsTest": true,
    "Currency": "EUR",
    "AmountCredit": 1,
    "TransactionType": "C092",
    "MutationType": 1,
    "RelatedTransactions": [
        {
            "RelationType": "refund",
            "RelatedTransactionKey": "0EF39AA94BD64FF38F1540DEB6XXXXXX"
        }
    ],
    "ConsumerMessage": null,
    "Order": null,
    "IssuingCountry": null,
    "StartRecurrent": false,
    "Recurring": false,
    "CustomerName": null,
    "PayerHash": null,
    "PaymentKey": "0650B22A3CC44E60AF1D67D9BEXXXXXX"
}

Push


JSON push response

The push response does not have service specific response variables.

JSON

copy
{
  "Transaction": {
    "Key": "6C1012FAF0444C1C8283404DA7XXXXXX",
    "Invoice": "testinvoice 123",
    "ServiceCode": "bancontactmrcash",
    "Status": {
      "Code": {
        "Code": 190,
        "Description": "Success"
      },
      "SubCode": {
        "Code": "S001",
        "Description": "Transaction successfully processed"
      },
      "DateTime": "2017-03-30T12:54:58"
    },
    "IsTest": true,
    "Order": null,
    "Currency": "EUR",
    "AmountCredit": 1,
    "TransactionType": "C092",
    "Services": null,
    "CustomParameters": null,
    "AdditionalParameters": null,
    "MutationType": 1,
    "RelatedTransactions": [
      {
        "RelationType": "refund",
        "RelatedTransactionKey": "0EF39AA94BD64FF38F1540DEB6XXXXXX"
      }
    ],
    "IsCancelable": false,
    "IssuingCountry": null,
    "StartRecurrent": false,
    "Recurring": false,
    "CustomerName": null,
    "PayerHash": null,
    "PaymentKey": "0650B22A3CC44E60AF1D67D9BEXXXXXX"
  }
}

SDK

copy

PayEncrypted

For a regular Pay action, the consumer has to be redirected to our checkout to fill in its card data. With this action and our Client Side Encryption SDK we have introduced a way where this redirection is not necessary and you can ask for the consumers' card data on your own webshop. All you have to do is encrypt the card data with our Client Side Encryption SDK (for more info on our Client Side Encryption SDK, click here) and call this action with the "EncryptedCardData"-parameter. The value of this parameter is the result of the "encryptCardData"-function in our CSE SDK.

View in playground

Request


The request is much like the Pay request, except for the EncryptedCardData parameter.

EncryptedCardData
Required

The value of this parameter is the result of the "encryptCardData"-function of our Client Side Encryption SDK.

JSON

copy
{
  "Currency": "EUR",
  "AmountDebit": 0.01,
  "Invoice": "BancontactPayEncryptedTest123",
  "Description": "Bancontact PayEncrypted Test 123",
    "Services": {
    "ServiceList": [
      {
        "Name": "bancontactmrcash",
        "Action": "PayEncrypted",
        "Version": 0,
        "Parameters": [
          {
            "Name": "EncryptedCardData",
            "GroupType": "",
            "GroupID": "",
            "Value": "001SlXfd8MbiTd/JFwCiGVs3f6o4x6xt0aN29NzOSNZHPKlVsz/EWeQmyhb1gGZ86VY88DP7gfDV+UyjcPfpVfHZd7u+WkO71hnV2QfYILCBNqE1aiPv2GQVGdaGbuoQloKu1o3o3I1UDmVxivXTMQX76ovot89geA6hqbtakmpmvxeiwwea3l4htNoX1IlD1hfYkDDl9rzSu5ypcjvVs6aRGXK5iMHnyrmEsEnfdj/Q5XWbsD5xAm4u3y6J8d4UP7LB31VLECzZUTiJOtKKcCQlT01YThIkQlj8PWBBMtt4H52VN3IH2+wPYtR8HiOZzcA2HA7UxozogIpS53tIURj/g=="
          }
        ]
      }
    ]
  }
}

Response


The response is the same as the Pay response.

JSON

copy
{
  "Key": "AF4BB6D14C364404ADF925958FXXXXXX",
  "Status": {
    "Code": {
      "Code": 791,
      "Description": "Pending processing"
    },
    "SubCode": {
      "Code": "S002",
      "Description": "An additional action is required: 3-D Secure"
    },
    "DateTime": "2018-10-19T15:30:39"
  },
  "RequiredAction": {
    "RedirectURL": "https://checkout.buckaroo.nl/html/redirect.ashx?r=0D7D9B311EC3410CB20D7F89C0XXXXXX",
    "RequestedInformation": null,
    "PayRemainderDetails": null,
    "Name": "Redirect",
    "TypeDeprecated": 0
  },
  "Services": [
    {
      "Name": "bancontactmrcash",
      "Action": null,
      "Parameters": [
        {
          "Name": "CardNumberEnding",
          "Value": "5015"
        },
        {
          "Name": "CardExpirationDate",
          "Value": "2023-10"
        },
        {
          "Name": "MaskedCreditcardNumber",
          "Value": "670342*******5015"
        },
        {
          "Name": "Enrolled",
          "Value": "Y"
        }
      ]
    }
  ],
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "Invoice": "BancontactPayEncryptedTest123",
  "ServiceCode": "bancontactmrcash",
  "IsTest": false,
  "Currency": "EUR",
  "AmountDebit": 0.01,
  "TransactionType": "C090",
  "MutationType": 1,
  "RelatedTransactions": null,
  "ConsumerMessage": null,
  "Order": null,
  "IssuingCountry": null,
  "StartRecurrent": false,
  "Recurring": false,
  "CustomerName": "Automated Encryptietest",
  "PayerHash": null,
  "PaymentKey": "98944CC3B3FA4ACD9A837D3A22XXXXXX"
}

Push


The push is almost the same as the Pay push, except for the ClientSideEncryptionVersion parameter.

ClientSideEncryptionVersion

The Client Side Encryption version that is used to encrypt the card data.

JSON

copy
{
   "Transaction":{
      "Key":"AF4BB6D14C364404ADF925958FXXXXXX",
      "Invoice":"BancontactPayEncryptedTest123",
      "ServiceCode":null,
      "Status":{
         "Code":{
            "Code":190,
            "Description":"Success"
         },
         "SubCode":{
            "Code":"S990",
            "Description":"The request was successful."
         },
         "DateTime":"2018-10-20T05:15:10"
      },
      "IsTest":false,
      "Order":null,
      "Currency":"EUR",
      "AmountDebit":0.01,
      "TransactionType":"C090",
      "Services":[
         {
            "Name":"BancontactMrCash",
            "Action":null,
            "Parameters":[
               {
                  "Name":"ClientSideEncryptionVersion",
                  "Value":"1"
               }
            ]
         },
         {
            "Name":"bancontactmrcash",
            "Action":null,
            "Parameters":[
               {
                  "Name":"CardNumberEnding",
                  "Value":"5015"
               },
               {
                  "Name":"CardExpirationDate",
                  "Value":"2023-10"
               },
               {
                  "Name":"MaskedCreditcardNumber",
                  "Value":"670342*******5015"
               },
               {
                  "Name":"Enrolled",
                  "Value":"Y"
               }
            ],
            "VersionAsProperty":1
         }
      ],
      "CustomParameters":null,
      "AdditionalParameters":null,
      "MutationType":1,
      "RelatedTransactions":null,
      "IsCancelable":false,
      "IssuingCountry":null,
      "StartRecurrent":false,
      "Recurring":false,
      "CustomerName":"Automated Encryptietest",
      "PayerHash":null,
      "PaymentKey":"98944CC3B3FA4ACD9A837D3A22XXXXXX"
   }
}

CompletePayment

When you want to use both the QR-Code as the Client Side Encryption on your own webshop checkout, you have to use the CompletePayment DataRequest to complete the already created payment.

Note that the ReturnUrl of the original transaction is used to redirect the consumer.

View in playground

Request


The request is much like the PayEncrypted request, except for that this is a DataRequest and the OriginalTransactionKey parameter.

OriginalTransactionKey
Required

Transaction key of the payment that needs to be completed. Please note: This is a basic request variable, not a service specific variable.

EncryptedCardData
Required

The value of this parameter is the result of the "encryptCardData"-function of our Client Side Encryption SDK.

JSON

copy
{
  "OriginalTransactionKey": "AF4BB6D14C364404ADF925958FXXXXXX",
  "Services": {
    "ServiceList": [
      {
        "Name": "bancontactmrcash",
        "Action": "CompletePayment",
		"Parameters": [
          {
            "Name": "EncryptedCardData",
            "Value": "001SlXfd8MbiTd/JFwCiGVs3f6o4x6xt0aN29NzOSNZHPKlVsz/EWeQmyhb1gGZ86VY88DP7gfDV+UyjcPfpVfHZd7u+WkO71hnV2QfYILCBNqE1aiPv2GQVGdaGbuoQloKu1o3o3I1UDmVxivXTMQX76ovot89geA6hqbtakmpmvxeiwwea3l4htNoX1IlD1hfYkDDl9rzSu5ypcjvVs6aRGXK5iMHnyrmEsEnfdj/Q5XWbsD5xAm4u3y6J8d4UP7LB31VLECzZUTiJOtKKcCQlT01YThIkQlj8PWBBMtt4H52VN3IH2+wPYtR8HiOZzcA2HA7UxozogIpS53tIURj/g=="
          }
        ]
      }
    ]
  }
}

Response


The respons is also much like the PayEncrypted response.

JSON

copy
{
  "Key": "0FDA1EC644FA4E948ADEF63694XXXXXX",
  "Status": {
    "Code": {
      "Code": 791,
      "Description": "Pending processing"
    },
    "SubCode": {
      "Code": "S002",
      "Description": "An additional action is required: 3-D Secure"
    },
    "DateTime": "2018-12-04T15:53:49"
  },
  "RequiredAction": {
    "RedirectURL": "https://checkout.buckaroo.nl/html/redirect.ashx?r=0D7D9B311EC3410CB20D7F89C0XXXXXX",
    "RequestedInformation": null,
    "Name": "Redirect",
    "TypeDeprecated": 0
  },
  "Services": null,
  "CustomParameters": null,
  "AdditionalParameters": null,
  "RequestErrors": null,
  "ServiceCode": "bancontactmrcash",
  "IsTest": false,
  "ConsumerMessage": null
}