Bancontact QR

🚧

Coming soon

📘

This feature is only available in EMEA and limited to certain acquirers.

Bancontact is a popular electronic payment method used in Netherlands and Belgium. In order to enable a quick and convenient payment experience customers can complete the payment process by scanning a QR and complete the paymnet within the Bancontact app.

Initiate a Sale transaction

In the first step you need to send the API request using requestType="ApmSaleTransaction" and payment method type = "BANCONTACT_QR" indicating you wish to initiate a QR code flow with Bancontact.

For this purpose you need to send a POST request to the Gateway's /payments endpoint including all mandatory elements as per below table.

ElementDescription
requestTypeThe only allowed requestType for Bancontact QR is 'ApmSaleTransaction'
paymentMethod.type'BANCONTACT_QR' is the only value for this payment method
integrationDataThe integration data from the external application, e.g. regularly optional values, which for this payment method are mandatory. Can be used during integration, or to allow generic parameter loading with a data-protected opt-in policy.
item represents the type of the value that is defined under value. Use the value "RETURN_URL"
value represents URL to which the customer should be redirected to after payment completion.

The following JSON document represents an example of a Bancontact QR transaction request including minimal set of elements:

"requestType": "ApmSaleTransaction",
"transactionAmount": {
    "total": "20.85",
    "currency": "EUR",
    "components":{
        "shipping": 0.85,
        "subtotal": 15,
        "vatAmount": 4
    }
},
"paymentMethod": {
    "type": "BANCONTACT_QR"
},
"storeId": "541xxxxxx1806",
"order": {
    "shipping": {
        "name": "Max Mustermann",
        "address": {
            "company": "Test Company",
            "address1": "Middle street 1",
            "city": "Amsterdam",
            "postalCode": "1000",
            "region": "Flevoland",
            "country": "NL"
        }
    },
},

"transactionOrigin": "ECOM",
"integrationData": [
    {
        "item": "RETURN_URL",
        "value": "https://www.example123.com"
    },
    {
        "item": "FAILURE_RETURN_URL",
        "value": "https://www.example456.com"
    }

]
}

You will receive the QR code in the response. The following JSON document represents an example of a Bancontact QR transaction response in "WAITING" status. It includes the requiredRedirectionDataelement:

{  
"type": "transactionResponse",  
"clientRequestId": "f1c00c98-c7a9-4d04-8297-c77b86481bb8",  
"apiTraceId": "ZtRPcmzUSxuigIaPqE-6KQAAAGM",  
"ipgTransactionId": "84510766934",  
"orderId": "R-8a4a43a4-d7d1-48b8-b0d7-f09d746e4bcc",  
"paymentToken": {  
    "reusable": true,  
    "declineDuplicates": false  
    },  
"transactionTime": 1725190002,  
"transactionAmount": {  
    "total": 100.00,  
    "currency": "EUR",  
    "components": {}  
    },  
"transactionStatus": "WAITING",  
"approvalCode": "?:waiting BANCONTACT",  
"requiredActions": {  
    "requiredRedirectionData":
  	[ 
				{
         "hint":"BEP//1www.test3.ipg-online.de/ipgconfirmation/services/bancontactQR/123456789" ,
         "key": "QR_CODE"
        }
    ]
}  
}

Display the QR code on your website.


Customer scans the QR code and completes the payment within the Bancontact app.


Pull the transaction status

Once the QR code is displayed, you can start checking the status individually by submitting a GET request to the /payments/ endpoint including referenced "ipgTransactionId", e.g. GET .../payments/123456789.

In case the initial transaction has been approved, you will receive the response as on an example below:

{
    "clientRequestId": "2838649",
    "apiTraceId": "ZMpbcxxxxxxxx5QAAAK0",
    "ipgTransactionId": "123456789",
    "orderId": "R-dcfd788a-00c6-42b4-9ac9-dxxxxxxxfac46",
    "paymentToken": {
        "reusable": true,
        "declineDuplicates": false
    },
    "transactionTime": 1690983271,
    "approvedAmount": {
        "total": 5555,
        "currency": "EUR",
        "components": {
            "subtotal": 5555
        }
    },
    "transactionAmount": {
        "total": 5555,
        "currency": "EUR",
        "components": {
            "subtotal": 5555
        }
    },
    "transactionResult": "APPROVED",
    "approvalCode": "Y:0:4445425891:PP X:74902486733",
    "transactionState": "CAPTURED",
    "processor": {
        "referenceNumber": "7490xxxxx733",
        "authorizationCode": "0",
        "responseCode": "0",
        "responseMessage": "SUCCESS"
    }
}

Want a quick overview?