# Bancontact for Unified Payments API Bancontact payments follow a two-step process: 1. [Request a Bancontact payment](#Request_a_payment). 2. [Redirect the customer](#Redirect_the_customer). --- ## Request a payment ### Endpoints For the full API specification, see the [API reference](https://api-reference.checkout.com/). > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Live** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ### Request example ```json { "amount": 100, "currency": "EUR", "source": { "type": "bancontact", "account_holder_name": "Hannah Bret", "payment_country": "BE", "billing_descriptor": "Test payment" } } ``` ### Response example If you receive a `202 Success` response, with a `status` field set to `Pending`, your request was successful. You now need to [redirect your customer](#Redirect_the_customer). ```json { "id": "pay_scoqartlkpzerp45c5ujmj6uue", "status": "Pending", "customer": { "id": "cus_wqzgcjuiwucudpmfu7kn5mukh4" }, "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_scoqartlkpzerp45c5ujmj6uue" }, "redirect": { "href": "https://trusted.girogate.de/ti/dumbdummy?tx=455332564&rs=O34Tn460YM76zZzI7yfXXPIsVnnWAhaV&cs=bb716499d072a5adfb314437c5965e1150b15550aac7a298b5d9d317653427a1" }, "bancontact:mobile": { "href": "BEPGenApp://DoTx?TransId=1BC.GIROGATE.DE/BCMC/123456789$ICAE3BUIH5P9U53Y5HKA9CRT" } } } ``` --- ## Redirect the customer Redirect your customer to the `redirect` link’s href in the response. This will allow the customer to authorize the payment, before they are transferred to your predefined success or failure URL. Alternatively, use the `bancontact:mobile` redirection link in the response to take them to the Bancontact mobile app. This mobile redirection link, however, is only provided in the production environment and only when the `amount` is less than or equal to `50000` (500 EUR). --- ## Recurring payments > **Information** > > Bancontact recurring payments are available to eligible merchants only. To check availability, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes). Bancontact recurring payments follow a three-step process: 1. Request the initial payment to create the agreement. 2. Authenticate the initial payment. Once the authentication succeeds, the agreement becomes active and Checkout.com stores it as a payment instrument for future use. 3. Request subsequent payments using the payment instrument. ### Request the initial payment The initial payment is a customer-initiated transaction (CIT) in which the customer authenticates and pays. If the payment succeeds, Checkout.com creates an agreement and stores it as a payment instrument that you can reuse in subsequent payment requests. Call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint and provide the following fields: - `payment_type` – Set to `Recurring`. - `merchant_initiated` – Set to `false`. > **Information** > > The Payments API supports idempotency. You can safely retry API requests without the risk of duplicate payments. > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` #### Request example ```json { "amount": 1000, "currency": "EUR", "source": { "type": "bancontact", "account_holder": { "first_name": "Hannah", "last_name": "Bret", "billing_address": { "country": "BE" } } }, "payment_type": "Recurring", "merchant_initiated": false, "billing_descriptor": { "name": "Test payment" } } ``` #### Response example If you receive a `202 Accepted` response with a `status` field set to `Pending`, your request was successful. ```json { "id": "pay_jwvjl5tin54ubn7x2stvmunske", "status": "Pending", "source": { "type": "bancontact", "id": "src_nwd3m4in3hkuddfpjsaevunhdy" }, "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_jwvjl5tin54ubn7x2stvmunske" }, "redirect": { "href": "https://trusted.girogate.de/ti/dumbdummy?tx=455332564&rs=O34Tn460YM76zZzI7yfXXPIsVnnWAhaV&cs=bb716499d072a5adfb314437c5965e1150b15550aac7a298b5d9d317653427a1" } } } ``` The response returns the payment instrument ID in the `source.id` field. You cannot use the payment instrument until you authenticate the initial payment. ### Authenticate the initial payment Redirect your customer to the URL returned in the response's `_links.redirect.href` field. The customer is asked to authenticate and pay, and redirected to your predefined success or failure URL depending on the authentication outcome. If the payment is successful, you receive a `payment_captured` webhook, which also indicates that the payment instrument ID is ready for use in subsequent payments. Store the instrument ID and use it for subsequent payments. ### Request a subsequent payment Once the agreement is active, you can use the payment instrument ID in subsequent merchant-initiated transactions (MITs) without the cardholder present. Call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint. Set the following fields, depending on the payment type: For a one-click payment (CIT) – Set: - `payment_type` to `Recurring` - `merchant_initiated` to `false` For a recurring payment (MIT) – Set: - `payment_type` to `Recurring` - `merchant_initiated` to `true` #### Request example > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Production** `POST` `https://{prefix}.api.checkout.com/payments` **Sandbox** `POST` `https://{prefix}.api.sandbox.checkout.com/payments` ```json { "amount": 500, "currency": "EUR", "source": { "type": "id", "id": "src_nwd3m4in3hkuddfpjsaevunhdy" }, "payment_type": "Recurring", "merchant_initiated": true, "billing_descriptor": { "name": "Test payment" } } ``` #### Response example If you receive a `202 Accepted` response with a `status` field set to `Pending`, your request was successful. Checkout.com confirms the outcome with a `payment_captured` or `payment_declined` webhook. ```json { "id": "pay_4prafl3phiyejkfrjtgzlh4kye", "status": "Pending", "source": { "type": "bancontact", "id": "src_nwd3m4in3hkuddfpjsaevunhdy" }, "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_4prafl3phiyejkfrjtgzlh4kye" } } } ``` --- ## Get details about a payment You can retrieve details about an existing Bancontact payment with the following endpoint. Use the following details to set up your request. ### Endpoints For the full API specification, see the [API reference](https://api-reference.checkout.com/). > **Information** > > Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md). **Live** `GET` `https://{prefix}.api.checkout.com/payments/{id}` **Sandbox** `GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}` ### Response example ```json { "id": "pay_zvamjy6rl3pehdeufoqaygbjzm", "requested_on": "2024-05-17T15:17:06Z", "source": { "type": "bancontact" }, "amount": 100, "currency": "EUR", "payment_type": "Regular", "status": "Captured", "approved": true, "risk": { "flagged": false }, "customer": { "id": "cus_t4rcgkbd2keuzeoo3p36u2xqcu" }, "_links": { "self": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_zvamjy6rl3pehdeufoqaygbjzm" }, "actions": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_zvamjy6rl3pehdeufoqaygbjzm/actions" }, "refund": { "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_zvamjy6rl3pehdeufoqaygbjzm/refunds" } } } ``` --- ## Refund a payment Bancontact supports both partial and full refunds. You can refund a payment through the [Dashboard](https://dashboard.checkout.com) or by using the [Refund API](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment.md). --- ## Cancel a payment If the customer fails to complete their payment within one hour of payment creation, Checkout.com automatically voids the payment and sends a `payment_expired` webhook. If the customer cancels their payment, we send a `payment_canceled` webhook. --- ## Testing Bancontact > **Note** > > To start testing, contact your account manager or integrations engineer to activate Bancontact payments in the sandbox environment. 1. Create a Bancontact transaction following the steps on this page, and open the redirect link in the response to Bancontact's website. 2. Set the payment response and payment delay as necessary. 3. Select _Submit_. You should then be redirected to your predefined success URL.