# Create Transaction You can use this call to create a new Bancontact transaction. ## Prerequisite Get an `access_token` and use it as 'Bearer' token in your request. Find more details [here](authorization-3). ## Request ```text POST https://api.pay.cm.com/api/v1/paymentmethods/bancontact/v1/transactions ``` ### Request body examples These are only some examples of the request body to create a transaction: ```json Full Request with ReturnURLs { "reference": "98494949", "description": "Order at yourdomain.tld", "amount": 1200, "currency": "EUR", "expiresAt": "2024-06-14T15:04:05Z", "language": "en", "consumer": { "name": { "firstName": "John", "lastName": "Lopez", "middleName": "A" }, "address": { "street": "Rustenburgerlaan", "houseNumber": "25", "postalCode": "2012AL", "city": "Haarlem", "countryCode": "BE", "state": "Noord-Holland", "additionalData": "Right-hand portal" }, "email": "john.doe@email.tld", "businessName": "CM", "phone": "06-95613259", "gender": null, "dateOfBirth": "1996-12-01" }, "webhooks": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "REFUND_STATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "STATUS_CHANGE" ] } ], "returnUrls": { "success": "https://yourdomain.tld/order/payment-success.html", "cancelled": "https://yourdomain.tld/order/payment-cancelled.html", "expired": "https://yourdomain.tld/order/payment-expired.html", "failed": "https://yourdomain.tld/order/payment-failed.html" } } ``` ```json Full Request with ReturnURL { "reference": "98494949", "description": "Order at yourdomain.tld", "amount": 1200, "currency": "EUR", "expiresAt": "2024-06-14T15:04:05Z", "language": "en", "consumer": { "name": { "firstName": "John", "lastName": "Lopez", "middleName": "A" }, "address": { "street": "Rustenburgerlaan", "houseNumber": "25", "postalCode": "2012AL", "city": "Haarlem", "countryCode": "BE", "state": "Noord-Holland", "additionalData": "Right-hand portal" }, "email": "john.doe@email.tld", "businessName": "CM", "phone": "06-95613259", "gender": null, "dateOfBirth": "1996-12-01" }, "webhooks": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "REFUND_STATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "STATUS_CHANGE" ] } ], "returnUrl": "https://yourdomain.tld/order/payment-completed.html" } ``` ```json Minimal Request with ReturnURL { "reference": "98494949", "description": "Order at yourdomain.tld", "amount": 1200, "expiresAt": "2024-06-14T15:04:05Z", "language": "en", "returnUrl": "https://yourdomain.tld/order/payment-completed.html" } ``` "**Full Request with ReturnURLs**" and "**Full Request with ReturnURL**" are examples where all the request parameters are provided. If `returnUrls` is defined then customers will be redirected to a different URL depending on the status of the transaction when the payment process is completed. If `returnUrl` is defined then customers will be redirected to the same URL no matter the status of the transaction when the payment process is completed. "**Minimal Request with ReturnURLs**" is an example of the minimal request to create a transaction. This example, is using `returnUrls`, but you can replace it for `returnUrl` depending on what is better for your use case. ## Parameters | Parameter | Type | Description | Constraints | | :---------- | :------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | reference | String(1...255) | An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload. | | | amount | Int(1...99999999) | Integer representing the amount of the transaction. Denomination in the smallest currency subunit (e.g. eurocents). | Certain payment methods require a minimum amount of 2 cents because of legacy. These include \[creditcard, ideal\*, bancontact, apple-pay, google-pay, paypal, klarna].\*ideal -> depending our the configuration of your account 1 cent transactions are possible. | | description | String(1...255) | Description of the transaction. | | | language | String(ISO 639-1) | Preferred language of the user interface. | ISO 639-1 language. | | returnUrl | String(2000) | Specifies the URL where your customers will be redirected to when the payment process is completed. | Either `returnUrl` or `returnUrls` must be specified, but not both. | | returnUrls | [returnUrls](schemas-4#returnurls) Object | Specifies a URL where your customers will be redirected to (per transaction status) when the payment process is completed. For example, your customers will be redirected to `returnUrls.success` when the status of the transaction changes to `SUCCESS`. | Either `returnUrl` or `returnUrls` must be specified, but not both. | ## Optional parameters | Parameter | Type | Description | Constraints | | :-------- | :--------------------------------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | expiresAt | String(RFC3339) | Expiration time. | ISO 8601 date and time. If left empty, a default value will be set. Find more details [here](expiration) . | | currency | String (ISO 4217) | Currency code. | ISO 4217 currency code. | | consumer | [consumer](schemas-4#consumer) Object | Customer details. | The following fields are mandatory: `name.firstName`, `name.lastName`, `address.street`, `address.houseNumber`, `address.postalCode`, `address.city`, `address.countryCode`, `email`. Besides that, Bancontact is usually enabled for `BE` as the value of the `address.countryCode`. | | webhooks | Array of objects | Webhooks enable receiving a web request once a given event occurs. | Find more details [here](webhooks-1). | ## Response ```json { "id": "8db1e7fa-ba8a-4189-92fd-67a20217443d", "orderId": "8db1e7fa-ba8a-4189-92fd-67a20217443d", "reference": "20210623130413", "amount": 1200, "currency": "EUR", "description": "Order at yourdomain.tld", "expiresAt": "2006-01-02T15:04:05Z", "language": "nl", "country": "BE", "webhooks": [ { "url": "https://yourdomain.tld/order-webhooks?purchaseId=order123", "events": [ "FINALSTATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "REFUND_STATUS" ] }, { "url": "https://yourdomain.tld/payment-webhooks?purchaseId=order123", "events": [ "STATUS_CHANGE" ] } ], "status": "OPEN", "action": { "qrcode": { "url": "https://qrbackend.tld/images/213981209381209390821.png" }, "intent": { "url": "https://docdata.tld/pay?order=123" }, "redirect": { "url": "https://checkout.tld/3ds/bancontact/v1/123" } }, "createdAt": "2006-01-02T15:04:05Z", "refunds": { "refundedAmount": 300, "refundedPendingAmount": 100 }, "returnUrls": { "success": "https://yourdomain.tld/order/payment-success.html", "cancelled": "https://yourdomain.tld/order/payment-cancelled.html", "expired": "https://yourdomain.tld/order/payment-expired.html", "failed": "https://yourdomain.tld/order/payment-failed.html" } } ``` ## Parameters [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Type", "h-2": "Description", "h-3": "Constraints", "0-0": "id", "0-1": "String(36)", "0-2": "Transaction unique identifier.", "0-3": "", "1-0": "orderId", "1-1": "String(36)", "1-2": "Unique identifier.", "1-3": "", "2-0": "reference", "2-1": "String(1...255)", "2-2": "An identifier specified by you. If webhooks were specified in the request this identifier is added to the webhook request payload.", "2-3": "Specified in the request.", "3-0": "amount", "3-1": "Int(1...99999999)", "3-2": "Integer representing the amount of the checkout. Denomination in the smallest currency subunit (e.g. eurocents).", "3-3": "Specified in the request.", "4-0": "currency", "4-1": "String (ISO 4217)", "4-2": "Currency code.", "4-3": "Specified in the request.", "5-0": "description", "5-1": "String(1...255)", "5-2": "Description of the transaction.", "5-3": "Specified in the request.", "6-0": "expiresAt", "6-1": "String(RFC3339)", "6-2": "Expiration time.", "6-3": "Specified in the request.", "7-0": "language", "7-1": "String(ISO 639-1)", "7-2": "Preferred language of the user interface.", "7-3": "Specified in the request.", "8-0": "country", "8-1": "String", "8-2": "Country of the Customer.", "8-3": "", "9-0": "status", "9-1": "String", "9-2": "`OPEN` - Transaction has been created. This is the initial status. \n`SUCCESS` - Transaction successfully paid. \n`CANCELLED` - Transaction has been cancelled by your customers. \n`EXPIRED` - Transaction has not succeeded; expired. \n`FAILURE` - Transaction has not succeeded; unknown reason.", "9-3": "", "10-0": "action", "10-1": "[action](schemas-4#action) Object", "10-2": "The next action to be performed by you for this transaction. This includes the `qrcode` action (which includes the URL of the Bancontact QR code image to be shown to your customer), and the `intent` action (which includes the intent URL to be shared with your customer).", "10-3": "This parameter is nullable, and it is only available while the transaction is `OPEN`.", "11-0": "createdAt", "11-1": "String(RFC3339)", "11-2": "Creation time.", "11-3": "ISO 8601 date and time.", "12-0": "returnUrl", "12-1": "String(2000)", "12-2": "Specifies the URL where your customers will be redirected to when the payment process is completed.", "12-3": "Specified in the request.", "13-0": "returnUrls", "13-1": "Object", "13-2": "Specifies a URL where your customers will be redirected to (per transaction status) when the payment process is completed. For example, your customers will be redirected to `returnUrls.success` when the status of the transaction changes to `SUCCESS`.", "13-3": "Specified in the request." }, "cols": 4, "rows": 14, "align": [ "left", "left", "left", "left" ] } [/block] ## Optional parameters | Parameter | | Description | Constraints | | :-------- | :---------------------------------- | :----------------------------------------------------------------- | :------------------------ | | webhooks | Array of objects | Webhooks enable receiving a web request once a given event occurs. | Specified in the request. | | refunds | [refund](schemas-4#refund) Object | Indicates refundedAmount and refundedPendingAmount. | | ## Response codes | HTTP status | Description | | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 201 | Successful transaction. | | 4XX | Client error response (See message for details). This response is given when the user input was incorrect or something illegal was attempted (eg. using a service without having that service configured for the user, or not being authorized). | | 5XX | Server error response (See message for details). |