Recurring - Bancontact WIP
PPRO supports recurring payments for Bancontact through Bancontact Wallet Initiated Payments (WIP). You can offer Bancontact recurring payments easily with our payment agreements API.
Create the payment agreement
To create a Bancontact payment agreement, provide the following information when calling our /v1/payment-agreements API:
| Data Field | Required | Description |
|---|---|---|
| paymentMethod | M | BANCONTACT |
| consumer.name | M | Full name of the consumer. |
| consumer.country | M | The country from which the consumer is shopping. |
| authenticationSettings: REDIRECT settings.returnUrl | M | Add the url where the consumer should be redirected to after they complete the payment. Required for the REDIRECT payment flow. |
| initialPaymentCharge.amount.value | M | |
| initialPaymentCharge.amount.currency | M |
Bancontact currently only works via the "link and pay" flow. You must also include the initialPaymentCharge object in the agreement creation call to immediately initiate the first payment, without making a separate call.
Request
POST /v1/payment-agreements
{
"paymentMethod": "BANCONTACT",
"description": "PPRO Agreement",
"merchantPaymentAgreementReference": "{{$guid}}",
"startDate": "2025-05-27T20:24:27Z",
"webhooksUrl":"https://webhook",
"amount": {
"value": 300,
"currency": "EUR"
},
"amountType": "EXACT",
"authenticationSettings": [
{
"type": "REDIRECT",
"settings": {
"returnUrl": "https://www.ppro.com/"
}
}
],
"consumer": {
"name": "Ernestine Bartoletti",
"email": "[email protected]",
"country": "BE",
"client": {
"ip": "227.149.145.184"
},
"taxIdentification": "1111111111",
"billingAddress": {
"firstName": "Ernestine",
"lastName": "Bartoletti",
"street": "Rue de Fierlant 67",
"postalCode": "1190",
"city": "Bruxelles",
"region": "Bruxelles",
"country": "BE"
}
},
"initialPaymentCharge": {
"paymentDescriptor": "Link and Pay initial charge",
"merchantPaymentChargeReference": "MTR12345678",
"autoCapture": "true",
"amount": {
"value": 300,
"currency": "EUR"
}
}
}
Response
You'll receive our standard payment agreement response (see responses in the API Reference)
{
"id": "agr_TWXXaIGRgLr5QDMiBpO5i",
"status": "AUTHENTICATION_PENDING",
"description": "PPRO Agreement",
"merchantPaymentAgreementReference": "7868f408-bf21-4751-a778-b02bdef100cc",
"paymentMethod": "BANCONTACT",
"startDate": "2025-05-27T20:24:27.000Z",
"amount": {
"value": 300,
"currency": "EUR"
},
"instrumentId": "instr_0J75cbDCIrhZBsuSuvdxb",
"amountType": "EXACT",
"consumer": {
"name": "Ernestine Bartoletti",
"email": "[email protected]",
"country": "BE",
"client": {
"ip": "227.149.145.184"
},
"taxIdentification": "1111111111",
"billingAddress": {
"firstName": "Ernestine",
"lastName": "Bartoletti",
"street": "Rue de Fierlant 67",
"postalCode": "1190",
"city": "Bruxelles",
"region": "Bruxelles",
"country": "BE"
}
},
"authenticationMethods": [
{
"details": {
"mobileIntentUri": "bepgenapp://DoTx?TransId=1BANCONTACT.SANDBOX.CP-PL.PPRO.COM/BEP/LA/PWXISDCFTC49RYLZ7TB36DX95BQBMQHSGYXKK/1Y23YI6GUWEUXTJHUCSAVMLT4LDQRLSA1$LNLK62BMVBPWHYEOCP4J5RWY"
},
"type": "APP_INTENT"
},
{
"details": {
"codeType": "QR",
"codePayload": "BEP://1BANCONTACT.SANDBOX.CP-PL.PPRO.COM/BEP/LA/PWXISDCFTC49RYLZ7TB36DX95BQBMQHSGYXKK/1Y23YI6GUWEUXTJHUCSAVMLT4LDQRLSA1$LNLK62BMVBPWHYEOCP4J5RWY"
},
"type": "SCAN_CODE"
},
{
"details": {
"requestUrl": "https://authman.sandbox.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJhZ3JfVFdYWGFJR1JnTHI1UURNaUJwTzVpIiwicyI6Imh0dHBzOi8vd3d3LnBwcm8uY29tLyIsImYiOiJodHRwczovL3d3dy5wcHJvLmNvbS8_aXNGYWlsdXJlPXRydWUiLCJtIjoicHByb19wbGF5Z3JvdW5kX21lcmNoYW50In19._G-tcKSECZePEgZlanZlNxhilzQTGMB_gSKLU4upRAP1jRoy45VtmQweHCJMRQboBZ49HXpnUoMw1XDmXcCsCg",
"requestMethod": "GET"
},
"type": "REDIRECT"
}
],
"history": [
{
"id": "ahist_ofWEEdL98oLgvziSI6Y76",
"status": "AUTHENTICATION_PENDING",
"createdAt": "2025-05-26T21:49:17.042Z"
}
],
"initialPaymentChargeId": "charge_yJOAc3AHMzjIbPpLl5Kfz",
"createdAt": "2025-05-26T21:49:17.041Z",
"updatedAt": "2025-05-26T21:49:17.041Z"
}
Create a recurring payment
To initiate a subsequent recurring payment, send a request against an active agreement /v1/payment-agreements/{agreement-id}/payment-charges
Request
POST /v1/payment-agreements/{agreement-id}/payment-charges
{
"amount": {
"value": 300,
"currency": "EUR"
}
}
Response
{
"id": "charge_JpHQdyPNIghVel5TuVXVf",
"paymentMethod": "BANCONTACT",
"paymentMedium": "ECOMMERCE",
"scheduleType": "UNSCHEDULED",
"instrumentId": "instr_Zkn3z8DX9n6vD49nrLGBC",
"currency": "EUR",
"country": "BE",
"paymentDescriptor": "Bancontact Sandbox",
"status": "AUTHENTICATION_PENDING",
"consumer": {
"name": "Ernestine Bartoletti",
"email": "[email protected]",
"country": "BE",
"client": {
"ip": "227.149.145.184"
},
"taxIdentification": "39112171883",
"billingAddress": {
"firstName": "Ernestine",
"lastName": "Bartoletti",
"street": "Rue de Fierlant 67",
"postalCode": "1190",
"city": "Bruxelles",
"region": "Bruxelles",
"country": "BE"
}
},
"order": {
"orderItems": [
{
"sku": "LS123456789",
"category": "bicycle",
"name": "White T-Shirt",
"quantity": 1,
"amount": 100
}
],
"shippingAddress": {
"firstName": "Naldo",
"lastName": "Ro",
"phoneNumber": "01522113356",
"street": "Rue de Fierlant 67",
"postalCode": "1190",
"city": "Bruxelles",
"region": "Bruxelles",
"country": "BE"
},
"industryData": []
},
"authenticationMethods": [
{
"details": {
"mobileIntentUri": "bepgenapp://DoTx?TransId=1BANCONTACT.CARD-INTEGRATIONS.NON-PROD.PPRO.COM/BEP/LC/GM83TKXPUX55ZRKV8/1PTZIBX738PNUVUKT4EK1NSMP9P8UYGKM$AUWAQSHVF4X6QJAFRJ5NUMLS"
},
"type": "APP_INTENT"
},
{
"details": {
"codeType": "QR",
"codePayload": "BEP://1BANCONTACT.CARD-INTEGRATIONS.NON-PROD.PPRO.COM/BEP/LC/GM83TKXPUX55ZRKV8/1PTZIBX738PNUVUKT4EK1NSMP9P8UYGKM$AUWAQSHVF4X6QJAFRJ5NUMLS"
},
"type": "SCAN_CODE"
},
{
"details": {
"requestUrl": "https://authman.qa.lp-pl.ppro.com/v0/pages/?redirection_token=eyJhbGciOiJIUzUxMiJ9.eyJzZXNzaW9uIjp7InIiOiJjaGFyZ2VfSnBIUWR5UE5JZ2hWZWw1VHVWWFZmIn19.kooJ4gsHmRffZwiXKS75xTxhg2f2_0hQokojtG8A4mnidfsmQ-dPsPk5EDrw2X6YFlva69cGyzA1Yr-pwa5gPw",
"requestMethod": "GET"
},
"type": "REDIRECT"
}
],
"authorizations": [
{
"id": "authz_f7TKEgB8cse31haYCX4Pf",
"amount": 123,
"status": "AUTHENTICATION_PENDING",
"merchantPaymentChargeReference": "c855ca53-30d9-43f0-bbed-a0baac7e9601",
"createdAt": "2025-05-26T20:55:29.863Z",
"updatedAt": "2025-05-26T20:55:29.863Z"
}
],
"captures": [],
"refunds": [],
"voids": [],
"createdAt": "2025-05-26T20:55:29.595Z",
"updatedAt": "2025-05-26T20:55:29.863Z",
"_links": {
"authorizations": {
"href": "/v1/payment-charges/charge_JpHQdyPNIghVel5TuVXVf/authorizations"
},
"captures": {
"href": "/v1/payment-charges/charge_JpHQdyPNIghVel5TuVXVf/captures"
},
"refunds": {
"href": "/v1/payment-charges/charge_JpHQdyPNIghVel5TuVXVf/refunds"
},
"voids": {
"href": "/v1/payment-charges/charge_JpHQdyPNIghVel5TuVXVf/voids"
}
}
}
Maximum Transaction amount per Merchant
Bancontact also imposes a maximum transaction amount on each Merchant after onboarding:
- The amount of a WIP Transaction must be lower than or equal to the WIP Maximum Merchant Amount
allowed to the Merchant- The WIP Maximum Merchant Amount must be lower than or equal to the global WIP Maximum
Transaction Amount- Split Payments using WIP Transactions are not allowed. The Merchant is not allowed to trigger a payment for an amount that would be larger than its WIP Maximum Merchant Amount by initiating multiple WIP transactions of an amount lower than the WIP Maximum Merchant Amount.
Bancontact WIP Requirements for Merchant <> Cardholder Interaction
To support Bancontact WIP, the Merchant must meet specific UX requirements on its checkout page:
- The Merchant shall have a simple and easily accessible procedure in place to allow the Cardholder to dispute a WIP Transaction or to ask the Merchant to cancel a WIP transaction through a refund.
- The Merchant shall have a simple and easily accessible procedure in place to allow the Cardholder to add, update or delete his Bancontact card(s) used to perform WIP Transactions.
- An electronic transaction receipt shall be sent to the Cardholder containing all mandatory transaction data as well as a clear procedure to ask the Merchant to refund this transaction or retain any future payments in the case of a recurring payment.
- The cardholder shall have established a relationship (As a minimum, the Cardholder shall have approved the Terms and Conditions of the WIP Merchant) with the Merchant to receive ongoing services and give permission to the WIP Merchant to debit his account on a recurring or ad-hoc basis.
Disputes, Chargeback and Fraud Management
Bancontact WIP transactions have the same risk/authentication profile as 3DS authenticated transactions, so disputes are extremely uncommon, and there is a liability shift from the merchant to the issuer in these purchases.
However, onboarding reliable merchants is extremely important, as the risk of fraudulent merchants can rely on PPRO and the PSP customer.
If Dispute or Fraudulent transactions exceed exclusion rates set by the scheme, the merchant might be excluded from Bancontact WIP, reach your account manager for more information.
Merchant onboarding on WIP
Updated 2 days ago