{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-guides/sidebars.yaml","oas-apis/merchant-payment.openapi.yaml":"oas-apis/merchant-payment.openapi.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","json-schema","openapi-code-sample"]},"type":"markdown"},"seo":{"title":"Online Sales","description":"Discover the API documentation to start developing your Bancontact Pro application","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":["openapi"],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"danger","name":"New payment URLs"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Following the decommissioning of the Payconiq brand in Belgium, these URL changes are essential to ensure compliance and"," ","mark the final phase in aligning our branding with the new Bancontact Pro identity."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please implement adaptations ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/general/payloadurlupdate"},"children":["described here"]}," promptly to avoid service interruptions and guarantee the continued acceptance of mobile payments via Bancontact Pay and Wero."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Changes are already available in our pre-production environement and will be rolled out in production starting ",{"$$mdtype":"Tag","name":"b","attributes":{},"children":["11/05/2026"]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important update"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please note that this payment solution is no longer offered directly by Bancontact Payconiq Company."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you would you still like to use a similar solution in your business please contact one of the partners"," ","listed ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://www.bancontact.com/en/partners","target":"_blank","rel":"noopener noreferrer"},"children":["here"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"online-sales","__idx":0},"children":["Online Sales"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"introduction","__idx":1},"children":["Introduction"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Online Sales (previously Custome on the Website Chekcout Page and App-to-App) allows you to:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Generate a one-time usage digital QR code  and show it on your website’s check out page. Your consumers scan the QR code with their preferred payment application and confirm the transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Initiate a one-time-use payment request directly within your mobile checkout experience."," ","When consumers confirm their purchase, they are seamlessly redirected via a universal deeplink to their preferred mobile payment application to authorize the transaction. After completing the payment, users are automatically redirected back to your app or mobile site to view the payment confirmation and finalize the purchase journey."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Online Sales can be used with Bancontact's checkout page or your own. Online Sales payment requests are valid for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["twenty minutes"]}," (1200 seconds)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"process-flow","__idx":2},"children":["Process Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following section outlines the key steps involved in a Online Sales online payment with Bancontact . The process involves several key parties, each playing a specific role in completing the transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"prerequisites","__idx":3},"children":["Prerequisites"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["API Key"]}," – This is used to secure the request between the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant’s backend"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact's backend"]},". Do not share your API keys in public areas such as online sites or client-side code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant CallbackUrl"]},"  – This URL will be called by Bancontact's backend servers in order to send the status of the payment to the merchant."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant ReturnUrl"]},"  – This is the URL to which your consumers will be redirected after payment completion."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"involved-parties","__idx":4},"children":["Involved Parties"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following parties participate in a display-based in-store payment with Bancontact:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer Application"]},": The consumer's preferred payment app used to complete the transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant Frontend"]},": Your website's checkout page or your Merchant App or your mobile website's checkout page."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Merchant Backend"]},": The merchant’s server-side system that integrates with Bancontact ."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact Backend"]},": The backend system responsible for handling payment processing and integration services."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"step-by-step-payment-flow","__idx":5},"children":["Step-by-Step Payment Flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Online Sales product can be used either for E-Commerce or M-Commerce (Previously \"Custom on the Website Checkout Page\" and \"App to App\")"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"e-commerce","__idx":6},"children":["E-Commerce"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section outlines a typical ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["“E-Commerce”"]}," in-store payment flow using Bancontact. The process begins when the transaction is initiated at the merchant’s location and ends when both the merchant and the consumer receive the final confirmation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This product contains two distinct flows: one with your own checkout page, one with Bancontact's checkout page."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"merchants-checkout-page","__idx":7},"children":["Merchant's Checkout Page"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]}," sends payment creation details to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]},". Request should at least contain the payment amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," issues a REST request to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," to create the payment, providing parameters like amount, currency, description, and other relevant parameters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," responds with the created payment ID and other relevant details, including a unique ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["QR code URL"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," forwards the QR code URL to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]},", which displays it for the consumer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," sends the QR Code url to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]}," to render the payment as a QR Code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer app"]}," scans the QR code and sends a request to retrieve payment details from the backend."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," sends payment details to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer App"]},", including merchant name and amount to pay."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The consumer confirms the payment using PIN, fingerprint, or face ID. The app then submits the payment request to the backend for authorization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A payment response is sent back to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer App"]},", indicating whether the payment was successful or failed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," sends a payment notification with the payment status to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," via the configured callback URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]}," displays the payment confirmation status."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important Note:"]}," The order in which the merchant and consumer receive payment status notifications is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not guaranteed"]},". Network and connectivity differences may cause one party to receive the update before the other."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"bancontacts-checkout-page","__idx":8},"children":["Bancontacts Checkout Page"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]}," sends payment creation details to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]},". Request should at least contain the payment amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," issues a REST request to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," to create the payment, providing parameters like amount, currency, description, and other relevant parameters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," responds with the created payment ID and other relevant details, including a  ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["checkout URL link"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," redirects the consumer to Bancontact's checkout page using checkout url provided in response from the previous step."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," forwards the QR code URL to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]},", which displays it for the consumer."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," sends the QR Code url to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]}," to render the payment as a QR Code."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer app"]}," scans the QR code and sends a request to retrieve payment details from the backend."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," sends payment details to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer App"]},", including merchant name and amount to pay."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The consumer confirms the payment using PIN, fingerprint, or face ID. The app then submits the payment request to the backend for authorization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A payment response is sent back to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer App"]},", indicating whether the payment was successful or failed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The Bancontact checkout page e redirects the consumer back to returnURL provided by the merchant during payment creation."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," sends a payment notification with the payment status to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," via the configured callback URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant frontend"]}," displays the payment confirmation status."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important Note:"]}," The order in which the merchant and consumer receive payment status notifications is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not guaranteed"]},". Network and connectivity differences may cause one party to receive the update before the other."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"m-commerce","__idx":9},"children":["M-Commerce"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This section outlines a typical ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["“M-Commerce”"]}," in-store payment flow using Bancontact."," ","The process begins when the transaction is initiated at the merchant’s location and ends when both the merchant and the consumer receive the final confirmation."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To achieve this, you will have to use the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_links.deeplink.href"]}," received in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Create Payment"]}," response."," ","Simply append your returnURL to create a universal link."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant app"]}," or mobile website sends payment creation details to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]},". Request should at least contain the payment amount."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," issues a REST request to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," to create the payment, providing parameters like amount, currency, description, and other relevant parameters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," responds with the created payment ID and other relevant details, including ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["several links"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," forwards the payment ID and the deeplink link to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant app"]}," or mobile website."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant app"]}," or mobile website adds a returnURL to the deeplink to create a universal link."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant app"]}," or mobile website executes the universal link to invoke the payer app."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["payer app"]},"  sends a request to retrieve payment details from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["the Bancontact backend"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," sends payment details to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer App"]},", including merchant name and amount to pay."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The consumer confirms the payment using PIN, fingerprint, or face ID. The app then submits the payment request to the backend for authorization."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A payment response is sent back to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer App"]},", indicating whether the payment was successful or failed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," sends a payment notification with the payment status to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," via the configured callback URL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Payer app"]}," returns the consumer to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant app"]}," by invoking the specified returnURL."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant app"]}," or mobile website displays the payment confirmation status."]}]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important Note:"]}," The order in which the merchant and consumer receive payment status notifications is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not guaranteed"]},". Network and connectivity differences may cause one party to receive the update before the other."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The Bancontact Fallback"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In certain instances, consumers may be redirected to a Bancontact page asking them to dowload a payer app, even if the user already has one."," ","If this happens your consumers may be blocked in the flow and be unable to procede to payment."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To circunvent this, you can use the checkout URL (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_links.checkout.href"]},") received in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create payment"]}," response instead of creating your own universal link."," ","By doing so, your consumers will either be redirected to the payer app to complete the payment, or to the Bancontactfallback page, from where they'll be"," ","able to select one of their installed apps to complete the payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"payment-flow-diagrams","__idx":10},"children":["Payment Flow Diagrams"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the following diagrams you will find a visual overview of the process flows presented above:"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"e-commerce-merchants-checkout-page","__idx":11},"children":["E-Commerce, Merchant's Checkout Page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/onlinesalesecommerce2x.acce7b8c657872e739700f9ee1a728b429e27bfad05aff3b9285de9645e560e0.85e0cfdd.jpg","alt":"Visualized diagram of the Online Sales, E-Commerece flow"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"e-commerce-bancontacts-checkout-page","__idx":12},"children":["E-Commerce, Bancontact's Checkout Page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/checkoutpagepaymentflow2x.bb595627b72ece14e2d0c35615ab8c301dcac5c2d14cae9a01ac21112197315c.85e0cfdd.jpg","alt":"Visualized diagram of the CheckOut Page Paymentflow"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"m-commerce-1","__idx":13},"children":["M-Commerce"]},{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/onlinesalesmcommerce2x.7b95774ddad2f4d2f4ca8dc9730aaae4c004158fe0a70b01f0c0dd3bfeb3fe53.85e0cfdd.jpg","alt":"Visualized diagram of the M-Commerce payment flow","loading":"lazy"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"m-commerce-bancontact-fallback","__idx":14},"children":["M-Commerce, Bancontact Fallback"]},{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/checkoutpagepaymentflow2x.bb595627b72ece14e2d0c35615ab8c301dcac5c2d14cae9a01ac21112197315c.85e0cfdd.jpg","alt":"Visualized diagram of the fallback flow","loading":"lazy"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"implementation-guide","__idx":15},"children":["Implementation Guide"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Please follow the below steps to successfully implement the API on your website."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-create-payment","__idx":16},"children":["1. Create Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In order to initiate a payment, you will first have to create it through Bancontact via a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["POST"]}," request.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Each request will result in a unique payment identifier which will be valid for ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["twenty minutes (1200 seconds)"]},".",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"If the payment does not take place within these two minutes, a new payment must be created."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-request-body","__idx":17},"children":["📦 Request Body"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../apis/merchant-payment.openapi.yaml#/components/schemas/payment_create_request"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/payment_create_request"},"currency":{"type":"string","title":"Currency","description":"Currency code. Only EUR is supported [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217)","enum":["EUR"],"default":"EUR"},"VoucherScheme":{"type":"string","description":"Voucher scheme (voucher type), has the form [alpha-3-country-code]_[identifier]\ncurrently known values:\n  - BEL_MEAL_VOUCHER\n  - BEL_ECO_VOUCHER\n  - BEL_GIFT_VOUCHER\n  - BEL_COVID_VOUCHER\n  - BEL_SPORT_VOUCHER\n  - BEL_CONSUMPTION_VOUCHER\n\nThe api should allow for new schemes, providers and categories without having to upgrade all the services/apps\nusing this API. Because most services will use the java api artifact for this (which will 'close' any enums\ndefined in an openapi spec), the values above are not encoded explicitly as enums.\nThe 400 error response will report any invalid values for the scheme and providers.\n","examples":["BEL_MEAL_VOUCHER"],"minLength":1,"maxLength":36,"pattern":"^[A-Z]{3}_[A-Z_]+$"},"VoucherEligibleAmount":{"type":"object","description":"Defines an amount could be payed with proper voucher schemes","required":["voucherSchemes","amount"],"properties":{"voucherSchemes":{"type":"array","description":"List of voucher schemes could be used to pay the amount","minItems":1,"items":{"$ref":"#/components/schemas/VoucherScheme"}},"amount":{"type":"integer","description":"Amount in cents eligible for payment with voucher. EUR 10.13 will be 1013","format":"int64","minimum":1,"exclusiveMinimum":1,"maximum":999999999999,"examples":[1013]}}},"payment_create_request":{"type":"object","title":"PaymentCreateRequest","description":"Request to initiate/create a payment as a Merchant","properties":{"reference":{"type":"string","description":"Merchant payment reference, used to reference the Bancontact Company payment in the merchant's system. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n","maxLength":35,"examples":["19848995"]},"bulkId":{"type":"string","maxLength":35,"description":"Field used to reference a bulk batch, so the merchant can inform how the payments should be bulked. If it's not set here it will default to the one configured in the profile.","examples":["Bulk-1-200"]},"amount":{"type":"integer","description":"Amount in cents requested","format":"int64","minimum":1,"exclusiveMinimum":1,"maximum":999999999999},"currency":{"$ref":"#/components/schemas/currency"},"description":{"type":"string","description":"Description of the payment that will be shown to the debtor, also used in the bank statement for reconciliation purposes. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n","maxLength":140},"identifyCallbackUrl":{"type":"string","description":"Callback url to which merchants will be notified about the payment identification. If it's not set here it will default to the one configured in the profile","pattern":"^https:\\/\\/([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(:\\d+)?(\\/[^\\s]*)?$","minLength":1,"maxLength":2048,"examples":["https://api.merchant.bancontact.net/identify"]},"callbackUrl":{"type":"string","description":"callbackUrl to which the merchant will be notified about the payment payout. If it's not set here it will default to the one set in the profile","pattern":"^https:\\/\\/([a-zA-Z0-9-:]+\\.)+[a-zA-Z]{2,}(:\\d+)?(\\/[^\\s]*)?$","minLength":1,"maxLength":2048,"examples":["https://api.merchant.bancontact.net/payment"]},"returnUrl":{"type":"string","description":"Merchant return url to which the dynamic payment page will redirect after the payment is completed","minLength":1,"maxLength":2048,"pattern":"^https:\\/\\/([a-zA-Z0-9-]+\\.)+[a-zA-Z]{2,}(:\\d+)?(\\/[^\\s]*)?$","examples":["https://api.merchant.bancontact.net/payment"]},"voucherEligibility":{"deprecated":true,"type":"array","description":"List of Value Added Services (vouchers) eligible amounts within the payment","items":{"$ref":"#/components/schemas/VoucherEligibleAmount"}}},"required":["amount"]}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-response","__idx":18},"children":["📥 Response"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../apis/merchant-payment.openapi.yaml#/components/schemas/payment_create_response"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/payment_create_response"},"currency":{"type":"string","title":"Currency","description":"Currency code. Only EUR is supported [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217)","enum":["EUR"],"default":"EUR"},"payment_creditor_response":{"type":"object","title":"PaymentCreditorResponse","description":"Creditor account set to receive the payment","properties":{"profileId":{"type":"string","description":"The configuration ID of the Merchant","examples":["07e998f9-d932-4848-8b60-d5b5ae94b1b2"]},"merchantId":{"type":"string","description":"the Id of the merchant","examples":["dee718bb-3b6d-4312-9404-3d63d14529cc"]},"name":{"type":"string","description":"Merchant's company name that will be shown to the debtor","examples":["John"]},"iban":{"type":"string","description":"Creditor's Bank Account Iban to where the money will be sent to for this current payment","examples":["BE12 3456 7890 1234"]},"identifyCallbackUrl":{"type":"string","description":"callbackUrl to which the merchant will be notified about the payment identification","examples":["https://api.merchant.bancontact.net/identify"]},"callbackUrl":{"type":"string","description":"callbackUrl to which the merchant will be notified about the payment payout","examples":["https://api.merchant.bancontact.net/payment"]}}},"link":{"type":"object","title":"Link","properties":{"href":{"type":"string"}},"required":["href"]},"links":{"type":"object","title":"Links","description":"Provides information to navigate to our REST interfaces dynamically, by including hypermedia links to them. Note that for some links inclusion depends on the status of the payment (e.g. cancel link will be available on PENDING and refund on SUCCEEDED)","properties":{"self":{"$ref":"#/components/schemas/link","examples":["https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f="]},"deeplink":{"$ref":"#/components/schemas/link","examples":["https://payconiq.com/pay/2/5f91483d-78a7-4914-bc6f="]},"qrcode":{"$ref":"#/components/schemas/link","examples":["https://qrcodegenerator.api.bancontact.net/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5f91483d-78a7-4914-bc6f="]},"cancel":{"$ref":"#/components/schemas/link","examples":["https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f="]},"refund":{"$ref":"#/components/schemas/link","examples":["https://merchant.api.bancontact.net/payments/5f91483d-78a7-4914-bc6f=/refunds"]},"checkout":{"$ref":"#/components/schemas/link","examples":["https://checkout.example.com?paymentId=12345&timestamp=1700000000000&token=abcdef1234567890"]}},"required":["self","deeplink","qrcode"]},"payment_create_response":{"type":"object","title":"PaymentCreateResponse","description":"Object returned if the payment gets successfully created","properties":{"paymentId":{"type":"string","description":"Payment ID","minLength":24,"maxLength":24,"examples":["5f91483d-78a7-4914-bc6f="]},"status":{"type":"string","enum":["PENDING"],"description":"the status of the payment created"},"createdAt":{"type":"string","format":"date-time","description":"the creation time of the payment"},"expiresAt":{"type":"string","format":"date-time","description":"the time from which the payment will be expired"},"description":{"type":"string","description":"Description of the payment that will be shown to the debtor, also used in the bank statement for reconciliation purposes. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). Only first 35 characters will be used for the remittance info\n"},"reference":{"type":"string","description":"Merchant payment reference, used to reference the Bancontact Company payment in the merchant's system. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n","examples":["19848995"]},"amount":{"type":"integer","format":"int64","minimum":1,"exclusiveMinimum":1,"maximum":999999999999,"description":"Amount in cents requested"},"currency":{"$ref":"#/components/schemas/currency"},"creditor":{"$ref":"#/components/schemas/payment_creditor_response"},"_links":{"$ref":"#/components/schemas/links"}},"required":["paymentId","status","createdAt","expiresAt","amount","currency","creditor","_links"]}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-error-codes-for-create","__idx":19},"children":["🔧 Error Codes for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["BODY_MISSING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A json needs to be provided"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FIELD_IS_REQUIRED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field X is mandatory"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["400"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["FIELD_IS_INVALID"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Field X is invalid"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["user doesn’t have an access token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCESS_DENIED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The JWT could not be verified (different format) - The JWT doesn’t contain the required authority to access the resource requested"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MERCHANT_PROFILE_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The merchant profile does not exist"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["422"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNABLE_TO_PAY_CREDITOR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Variable reason(Depends on automatic processing)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TECHNICAL_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Technical error in Payment service"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["503"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRY_AGAIN_LATER"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["one of the internal services is unavailable"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-sample-request--create-payment","__idx":20},"children":["🔍 Sample Request – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["create payment"]}]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/merchant-payment.openapi.yaml","operationId":"create","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"21-the-bancontact-qr-code-e-commerce","__idx":21},"children":["2.1 The Bancontact QR Code (E-Commerce)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To display the Bancontact  QR code, you can render the URL from the attribute ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_links.self.href"]}," received in the Create Payment reponse in a web view. By doing so, you'll make use of Bancontact's QR code generation service and will generate by default a small QR code (cf. Brand Guidelines)."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Important:"]}," the format, size and colour of the QR code can be modified if necessary using the parameters below. Please make sure to read our Brand Guidelines for more guidance on the minimum sizes and scanning distances."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Attribute"]}]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":""},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Description"]}]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["f"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"[String :: Enum] ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," Allowed Values: SVG, PNG"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Image format"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["s"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"[String :: Enum] ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," Allowed Values: S, M, L, XL",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Image size of the QR code to generate. ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Small (S) = 180x180 ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Medium (M) = 250x250",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Large (L) = 400x400 ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Extra Large (XL) = 800x800 ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," The sizes only applies to PNG format."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"22-invoking-the-bancontact-universal-link-m-commerce","__idx":22},"children":["2.2 Invoking the Bancontact Universal Link (M-Commerce)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["M-Commerce can be set-up either for App-to-App payments or Mobile Browser to App payments."," ","Please follow the intructions bellow accordingly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"app-to-app","__idx":23},"children":["App-to-App"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The following parameters are used to invoke the ."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Attribute"},"children":["Attribute"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["_links.deeplink.href"]}," ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," [String :: URI]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["URL String used to perform App2App linking"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Return Url ",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]}," [String:: URI]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A url to which the Merchant will be notified of a payment. Must be Https for production."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["\n  For further information on implementing universal links on\n  ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.apple.com/documentation/xcode/allowing-apps-and-websites-to-link-to-your-content?preferredLanguage=occ","target":"_blank"},"children":["iOS"]},"\n  and/or\n  ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://developer.android.com/training/app-links/deep-linking","target":"_blank"},"children":["Android"]},",\n  please follow the attached links.\n"]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"ios","__idx":24},"children":["iOS"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"swift","header":{"controls":{"copy":{}}},"source":"/* Create Payconiq payment */\nlet createdPayment = createPayconiqPayment(amount: paymentAmount, \"description\": paymentDescription, \"reference\": paymentReference, \"currency\": paymentCurrency, \"callbackUrl\": paymentCallbackUrl)\n\n//Get deeplink url from created payment\nlet deeplinkUrl = createdPayment.deeplinkUrl\n\n//Specify return url\nlet returnUrl = \"?returnUrl=https://example.com\"\n\n//Start the Payconiq Application\nif let url = URL(deeplinkUrl + returnUrl) {\n    if #available(iOS 10.0, *) {\n        // Pass custom options if needed\n        UIApplication.shared.open(url, options: [:], completionHandler: { result in\n            //Handle result\n        })\n    }else {\n        let result = UIApplication.shared.openURL(url)\n        //Handle result\n    }\n}\n","lang":"swift"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"android","__idx":25},"children":["Android"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"java","header":{"controls":{"copy":{}}},"source":"// Create a Payconiq Payment\nPayconiqPayment createdPayment = createPayconiqPayment(amount, description, reference, currency, callbackUrl);\n\n//Get the deeplink url from the created payment\nString deeplinkUrl = createdPayment.getDeeplinkUrl();\n\n// Construct the universal link\nString returnUrl = \"https://example.com/\";\nString universalLink = String.format(deeplinkUrl + \"?returnUrl=%s\", returnUrl);\n\n// Start the Payconiq application\nstartActivity(new Intent(Intent.ACTION_VIEW, Uri.parse(universalLink)));\n","lang":"java"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"mobile-browser-to-app","__idx":26},"children":["Mobile Browser to App"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The set-up for Mobile Browsers is almost the same as App-to-App. However, you will also"," ","have to introduce the following logic in your mobile website in order to determine the OS"," ","phone used for payment and either fire a Bancontact URL for iOS, or an intent for Android."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"ios-1","__idx":27},"children":["iOS"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Introduce this function to identify an iOS device"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"function isIOS() {\n  if (/iphone|XBLWP7/i.test(navigator.userAgent.toLowerCase())) {\n    return true;\n  } else {\n    return false;\n  }\n}\n\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trigger the payer app with the following code sample:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"<button onclick=\"createPayconiqUniversalLink()\">Pay with Payconiq iOS</button>\n\n<script>\n  function createPayconiqUniversalLink() {\n    var deeplinkUrl = getDeeplinkUrlFromPayconiqPayment(); // placeholder function\n    var returnUrl = \"?returnUrl=www.example.com\";\n    return deeplinkUrl.concat(returnUrl);\n  }\n</script>\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"android-1","__idx":28},"children":["Android"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Introduce this function to identify an Android device:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"function isAndroid() {\n if (/android|XBLWP7/i.test(navigator.userAgent.toLowerCase())) {\n   return true;\n } else {\n   return false;\n }\n}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Trigger the payer app with the following code sample:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"\n<button onclick=\"createPayconiqUniversalLink()\">Pay with Payconiq Android</button>\n\n<script>\n  function createPayconiqUniversalLink() {\n    var deeplinkUrl = getDeeplinkUrlFromPayconiqPayment(); // placeholder function\n    var returnUrl = \"?returnUrl=www.example.com\";\n    return deeplinkUrl.concat(returnUrl);\n  }\n</script>\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-the-bancontact--callback","__idx":29},"children":["3. The Bancontact  Callback"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can specify a callback URL where the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontactbackend"]}," will send notifications about the status of a payment. This will allow you to take appropriate action and process the payment data."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["merchant backend"]}," must verify that the notification message originated from ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Bancontact backend"]}," was not altered or corrupted during the tranmission. To do so, please ensure signature validation."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the full Callback documentation, please refer to the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/guides/general/callback052025"},"children":["Callback Guide"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-request-body-1","__idx":30},"children":["📦 Request Body"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../apis/merchant-payment.openapi.yaml#/components/schemas/merchant-callback"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/merchant-callback"},"merchant-payment-status":{"type":"string","title":"MerchantPaymentStatus","description":"| Status | Description |\n|--------|-------------|\n| PENDING | The merchant has created the payment and and is pending to proceed with identify step. |\n| IDENTIFIED | The user has scanned the payment's QR code with the Bancontact Pay. |\n| AUTHORIZED | The user has confirmed the payment and the bank authorized it. |\n| AUTHORIZATION_FAILED | The authorization with the bank failed. |\n| FAILED | Something went wrong during the payment process(e.g authorization failed). |\n| SUCCEEDED | The payment has succeeded. |\n| CANCELLED | When the payment has been canceled after the user has scanned it, or the merchant has cancelled the payment.|\n| EXPIRED | The payment has expired. |\n| PENDING_MERCHANT_ACKNOWLEDGEMENT | The payment is waiting for the merchant to acknowledge. |\n| VOIDED | The payment has been voided |\n","enum":["PENDING","IDENTIFIED","AUTHORIZED","AUTHORIZATION_FAILED","SUCCEEDED","FAILED","CANCELLED","EXPIRED","PENDING_MERCHANT_ACKNOWLEDGEMENT","VOIDED"]},"merchant-callback":{"type":"object","title":"MerchantCallback","properties":{"paymentId":{"type":"string","description":"Bancontact Company Payment ID","minLength":24,"maxLength":24,"examples":["5f91483d-78a7-4914-bc6f="]},"currency":{"type":"string","default":"EUR","description":"Only EUR is supported currently"},"amount":{"type":"integer","description":"Requested amount in cents","format":"int64"},"description":{"type":"string","description":"Description of the payment that will be shown to the debtor, also used in the bank statement for reconciliation purposes. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n"},"reference":{"type":"string","description":"Merchant payment reference, used to reference the Bancontact Company payment in the merchant’s system. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n","examples":["19848995"]},"createdAt":{"type":"string","format":"date-time","description":"When the payment was created"},"expireAt":{"type":"string","format":"date-time","description":"When the payment is going to expire. After that date the payment can't be confirmed anymore"},"succeededAt":{"type":"string","format":"date-time","description":"if the payment is SUCCEEDED, then this field represents the date-time on which the payment was SUCCEEDED"},"status":{"$ref":"#/components/schemas/merchant-payment-status"},"debtor":{"type":"object","description":"Customer that paid","required":["iban"],"properties":{"iban":{"type":"string","description":"Debtor's IBAN masked","examples":["*************12636"]},"name":{"type":"string","description":"Debtor's first name","examples":["John"]}}}},"required":["paymentId","totalAmount","currency","amount","createdAt","status","debtor"]}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-response-1","__idx":31},"children":["📥 Response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(No defined response schema)"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-sample-request--callback","__idx":32},"children":["🔍 Sample Request – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["callback"]}]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/merchant-payment.openapi.yaml","operationId":"callback","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"callback-failure","__idx":33},"children":["Callback Failure"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In the event you do not receive a callback or the callback validation fails, please refer to ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["\"4. Get Payment Details\""]},". This alternative will also allow you to confirm the status of a transaction in order to complete the payment."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"4-get-payment-details","__idx":34},"children":["4. Get Payment Details"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["By calling this endpoint you can obtain the details of an existing payment transaction by passing the unique payment ID."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Note:"]}," it is highly recommended to implement this call as a fallback option if callback fails."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-path-parameters","__idx":35},"children":["🧩 Path Parameters"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(string, required)"]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-response-2","__idx":36},"children":["📥 Response"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../apis/merchant-payment.openapi.yaml#/components/schemas/get_payment_response"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/get_payment_response"},"currency":{"type":"string","title":"Currency","description":"Currency code. Only EUR is supported [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217)","enum":["EUR"],"default":"EUR"},"merchant-payment-status":{"type":"string","title":"MerchantPaymentStatus","description":"| Status | Description |\n|--------|-------------|\n| PENDING | The merchant has created the payment and and is pending to proceed with identify step. |\n| IDENTIFIED | The user has scanned the payment's QR code with the Bancontact Pay. |\n| AUTHORIZED | The user has confirmed the payment and the bank authorized it. |\n| AUTHORIZATION_FAILED | The authorization with the bank failed. |\n| FAILED | Something went wrong during the payment process(e.g authorization failed). |\n| SUCCEEDED | The payment has succeeded. |\n| CANCELLED | When the payment has been canceled after the user has scanned it, or the merchant has cancelled the payment.|\n| EXPIRED | The payment has expired. |\n| PENDING_MERCHANT_ACKNOWLEDGEMENT | The payment is waiting for the merchant to acknowledge. |\n| VOIDED | The payment has been voided |\n","enum":["PENDING","IDENTIFIED","AUTHORIZED","AUTHORIZATION_FAILED","SUCCEEDED","FAILED","CANCELLED","EXPIRED","PENDING_MERCHANT_ACKNOWLEDGEMENT","VOIDED"]},"payment_creditor_response":{"type":"object","title":"PaymentCreditorResponse","description":"Creditor account set to receive the payment","properties":{"profileId":{"type":"string","description":"The configuration ID of the Merchant","examples":["07e998f9-d932-4848-8b60-d5b5ae94b1b2"]},"merchantId":{"type":"string","description":"the Id of the merchant","examples":["dee718bb-3b6d-4312-9404-3d63d14529cc"]},"name":{"type":"string","description":"Merchant's company name that will be shown to the debtor","examples":["John"]},"iban":{"type":"string","description":"Creditor's Bank Account Iban to where the money will be sent to for this current payment","examples":["BE12 3456 7890 1234"]},"identifyCallbackUrl":{"type":"string","description":"callbackUrl to which the merchant will be notified about the payment identification","examples":["https://api.merchant.bancontact.net/identify"]},"callbackUrl":{"type":"string","description":"callbackUrl to which the merchant will be notified about the payment payout","examples":["https://api.merchant.bancontact.net/payment"]}}},"link":{"type":"object","title":"Link","properties":{"href":{"type":"string"}},"required":["href"]},"links":{"type":"object","title":"Links","description":"Provides information to navigate to our REST interfaces dynamically, by including hypermedia links to them. Note that for some links inclusion depends on the status of the payment (e.g. cancel link will be available on PENDING and refund on SUCCEEDED)","properties":{"self":{"$ref":"#/components/schemas/link","examples":["https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f="]},"deeplink":{"$ref":"#/components/schemas/link","examples":["https://payconiq.com/pay/2/5f91483d-78a7-4914-bc6f="]},"qrcode":{"$ref":"#/components/schemas/link","examples":["https://qrcodegenerator.api.bancontact.net/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5f91483d-78a7-4914-bc6f="]},"cancel":{"$ref":"#/components/schemas/link","examples":["https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f="]},"refund":{"$ref":"#/components/schemas/link","examples":["https://merchant.api.bancontact.net/payments/5f91483d-78a7-4914-bc6f=/refunds"]},"checkout":{"$ref":"#/components/schemas/link","examples":["https://checkout.example.com?paymentId=12345&timestamp=1700000000000&token=abcdef1234567890"]}},"required":["self","deeplink","qrcode"]},"get_payment_response":{"type":"object","title":"GetPaymentResponse","description":"Response containing information on the requested payment.","properties":{"paymentId":{"type":"string","description":"id of the payment","minLength":24,"maxLength":24,"examples":["5f91483d-78a7-4914-bc6f="]},"createdAt":{"type":"string","format":"date-time","description":"the creation time of the payment"},"expireAt":{"type":"string","format":"date-time","description":"the time from which the payment will be expired"},"succeededAt":{"type":"string","format":"date-time","description":"if the payment is SUCCEEDED, then this field represents the date-time on which the payment was SUCCEEDED"},"currency":{"$ref":"#/components/schemas/currency"},"status":{"$ref":"#/components/schemas/merchant-payment-status"},"creditor":{"$ref":"#/components/schemas/payment_creditor_response"},"debtor":{"type":"object","properties":{"name":{"type":"string","description":"First name of Debtor","examples":["John"]},"iban":{"type":"string","description":"IBAN of Debtor masked","examples":["*************12636"]}}},"amount":{"type":"integer","format":"int64","description":"Amount in cents originally requested. If no amount was requested by creditor, this will be 0"},"description":{"type":"string","description":"merchant's description of the payment","examples":["5 coke."]},"message":{"type":"string","description":"debtor's message of the payment","examples":["Money send."]},"reference":{"type":"string","description":"Merchant payment reference, used to reference the Bancontact Company payment. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). in the merchant's system\n","examples":["19848995"]},"bulkId":{"type":"string","description":"Field used to reference a bulk batch, so the merchant can choose how to bulk the payments. Mandatory if  merchant profile does have bulking enabled, otherwise will miss from the response. If it's not set in the create call it will default to the value configured in the profile if it exists, otherwise its value will be defaulted by the application.","examples":["Bulk-1-200"]},"_links":{"$ref":"#/components/schemas/links"}},"required":["paymentId","createdAt","expireAt","currency","status","creditor","amount","totalAmount"]}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-error-codes-for-merchant-get-payment","__idx":37},"children":["🔧 Error Codes for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant-get-payment"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["caller doesn’t have an api-key access token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCESS_DENIED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["api-key access token is invalid, creditor it's not a participant of the requested payment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["no payment could be found"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TECHNICAL_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Technical error in Payment service"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-sample-request--merchant-get-payment","__idx":38},"children":["🔍 Sample Request – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchant-get-payment"]}]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/merchant-payment.openapi.yaml","operationId":"merchant-get-payment","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"5-get-payment-list","__idx":39},"children":["5. Get Payment List"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You can also retrieve a list of payments by specifying how many records to return, as well as a filter on the results for the total number of records returned per page."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-request-body-2","__idx":40},"children":["📦 Request Body"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../apis/merchant-payment.openapi.yaml#/components/schemas/payment-search-query"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/payment-search-query"},"merchant-payment-status":{"type":"string","title":"MerchantPaymentStatus","description":"| Status | Description |\n|--------|-------------|\n| PENDING | The merchant has created the payment and and is pending to proceed with identify step. |\n| IDENTIFIED | The user has scanned the payment's QR code with the Bancontact Pay. |\n| AUTHORIZED | The user has confirmed the payment and the bank authorized it. |\n| AUTHORIZATION_FAILED | The authorization with the bank failed. |\n| FAILED | Something went wrong during the payment process(e.g authorization failed). |\n| SUCCEEDED | The payment has succeeded. |\n| CANCELLED | When the payment has been canceled after the user has scanned it, or the merchant has cancelled the payment.|\n| EXPIRED | The payment has expired. |\n| PENDING_MERCHANT_ACKNOWLEDGEMENT | The payment is waiting for the merchant to acknowledge. |\n| VOIDED | The payment has been voided |\n","enum":["PENDING","IDENTIFIED","AUTHORIZED","AUTHORIZATION_FAILED","SUCCEEDED","FAILED","CANCELLED","EXPIRED","PENDING_MERCHANT_ACKNOWLEDGEMENT","VOIDED"]},"payment-search-query":{"type":"object","title":"PaymentSearchQuery","properties":{"from":{"type":"string","format":"date-time","description":"default is today - 1day (yesterday)"},"to":{"type":"string","format":"date-time"},"paymentStatuses":{"type":"array","items":{"$ref":"#/components/schemas/merchant-payment-status"}},"reference":{"type":"string","description":"Merchant payment reference, used to reference Bancontact Company payment in merchant system. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).\n","examples":["19848995"]}}}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-response-3","__idx":41},"children":["📥 Response"]},{"$$mdtype":"Tag","name":"JsonSchema","attributes":{"schema":{"$ref":"../../apis/merchant-payment.openapi.yaml#/components/schemas/PaymentSearchResponse"},"options":{},"schemaResolved":{"openapi":"3.1.0","components":{"schemas":{"__root":{"$ref":"#/components/schemas/PaymentSearchResponse"},"AbstractListResponsePayment":{"type":"object","properties":{"size":{"type":"integer","minimum":0,"description":"Size of the elements returned in current page"},"totalPages":{"type":"integer","description":"Total number of pages in the backend for the list requested"},"totalElements":{"type":"integer","description":"Total number of elements in the list requested\n"},"number":{"type":"integer","description":"Current page number"}},"required":["size","totalPages","totalElements","number"]},"currency":{"type":"string","title":"Currency","description":"Currency code. Only EUR is supported [ISO 4217](http://en.wikipedia.org/wiki/ISO_4217)","enum":["EUR"],"default":"EUR"},"merchant-payment-status":{"type":"string","title":"MerchantPaymentStatus","description":"| Status | Description |\n|--------|-------------|\n| PENDING | The merchant has created the payment and and is pending to proceed with identify step. |\n| IDENTIFIED | The user has scanned the payment's QR code with the Bancontact Pay. |\n| AUTHORIZED | The user has confirmed the payment and the bank authorized it. |\n| AUTHORIZATION_FAILED | The authorization with the bank failed. |\n| FAILED | Something went wrong during the payment process(e.g authorization failed). |\n| SUCCEEDED | The payment has succeeded. |\n| CANCELLED | When the payment has been canceled after the user has scanned it, or the merchant has cancelled the payment.|\n| EXPIRED | The payment has expired. |\n| PENDING_MERCHANT_ACKNOWLEDGEMENT | The payment is waiting for the merchant to acknowledge. |\n| VOIDED | The payment has been voided |\n","enum":["PENDING","IDENTIFIED","AUTHORIZED","AUTHORIZATION_FAILED","SUCCEEDED","FAILED","CANCELLED","EXPIRED","PENDING_MERCHANT_ACKNOWLEDGEMENT","VOIDED"]},"payment_creditor_response":{"type":"object","title":"PaymentCreditorResponse","description":"Creditor account set to receive the payment","properties":{"profileId":{"type":"string","description":"The configuration ID of the Merchant","examples":["07e998f9-d932-4848-8b60-d5b5ae94b1b2"]},"merchantId":{"type":"string","description":"the Id of the merchant","examples":["dee718bb-3b6d-4312-9404-3d63d14529cc"]},"name":{"type":"string","description":"Merchant's company name that will be shown to the debtor","examples":["John"]},"iban":{"type":"string","description":"Creditor's Bank Account Iban to where the money will be sent to for this current payment","examples":["BE12 3456 7890 1234"]},"identifyCallbackUrl":{"type":"string","description":"callbackUrl to which the merchant will be notified about the payment identification","examples":["https://api.merchant.bancontact.net/identify"]},"callbackUrl":{"type":"string","description":"callbackUrl to which the merchant will be notified about the payment payout","examples":["https://api.merchant.bancontact.net/payment"]}}},"link":{"type":"object","title":"Link","properties":{"href":{"type":"string"}},"required":["href"]},"links":{"type":"object","title":"Links","description":"Provides information to navigate to our REST interfaces dynamically, by including hypermedia links to them. Note that for some links inclusion depends on the status of the payment (e.g. cancel link will be available on PENDING and refund on SUCCEEDED)","properties":{"self":{"$ref":"#/components/schemas/link","examples":["https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f="]},"deeplink":{"$ref":"#/components/schemas/link","examples":["https://payconiq.com/pay/2/5f91483d-78a7-4914-bc6f="]},"qrcode":{"$ref":"#/components/schemas/link","examples":["https://qrcodegenerator.api.bancontact.net/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5f91483d-78a7-4914-bc6f="]},"cancel":{"$ref":"#/components/schemas/link","examples":["https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f="]},"refund":{"$ref":"#/components/schemas/link","examples":["https://merchant.api.bancontact.net/payments/5f91483d-78a7-4914-bc6f=/refunds"]},"checkout":{"$ref":"#/components/schemas/link","examples":["https://checkout.example.com?paymentId=12345&timestamp=1700000000000&token=abcdef1234567890"]}},"required":["self","deeplink","qrcode"]},"get_payment_response":{"type":"object","title":"GetPaymentResponse","description":"Response containing information on the requested payment.","properties":{"paymentId":{"type":"string","description":"id of the payment","minLength":24,"maxLength":24,"examples":["5f91483d-78a7-4914-bc6f="]},"createdAt":{"type":"string","format":"date-time","description":"the creation time of the payment"},"expireAt":{"type":"string","format":"date-time","description":"the time from which the payment will be expired"},"succeededAt":{"type":"string","format":"date-time","description":"if the payment is SUCCEEDED, then this field represents the date-time on which the payment was SUCCEEDED"},"currency":{"$ref":"#/components/schemas/currency"},"status":{"$ref":"#/components/schemas/merchant-payment-status"},"creditor":{"$ref":"#/components/schemas/payment_creditor_response"},"debtor":{"type":"object","properties":{"name":{"type":"string","description":"First name of Debtor","examples":["John"]},"iban":{"type":"string","description":"IBAN of Debtor masked","examples":["*************12636"]}}},"amount":{"type":"integer","format":"int64","description":"Amount in cents originally requested. If no amount was requested by creditor, this will be 0"},"description":{"type":"string","description":"merchant's description of the payment","examples":["5 coke."]},"message":{"type":"string","description":"debtor's message of the payment","examples":["Money send."]},"reference":{"type":"string","description":"Merchant payment reference, used to reference the Bancontact Company payment. The characters used must comply with the [SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best). in the merchant's system\n","examples":["19848995"]},"bulkId":{"type":"string","description":"Field used to reference a bulk batch, so the merchant can choose how to bulk the payments. Mandatory if  merchant profile does have bulking enabled, otherwise will miss from the response. If it's not set in the create call it will default to the value configured in the profile if it exists, otherwise its value will be defaulted by the application.","examples":["Bulk-1-200"]},"_links":{"$ref":"#/components/schemas/links"}},"required":["paymentId","createdAt","expireAt","currency","status","creditor","amount","totalAmount"]},"PaymentSearchResponse":{"allOf":[{"$ref":"#/components/schemas/AbstractListResponsePayment"},{"type":"object","properties":{"details":{"type":"array","items":{"$ref":"#/components/schemas/get_payment_response"}}}}]}}}},"schemaResolvedErrors":[]},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-error-codes-for-search","__idx":42},"children":["🔧 Error Codes for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["caller doesn’t have an api-key access token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCESS_DENIED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["api-key access token is invalid, creditor it's not a participant of the requested payment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TECHNICAL_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Technical error in Payment service"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"-sample-request--search","__idx":43},"children":["🔍 Sample Request – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["search"]}]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/merchant-payment.openapi.yaml","operationId":"search","parameters":{},"environments":{}},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"canceling-a-payment","__idx":44},"children":["Canceling a Payment"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete-payment"]}," can be used to cancel a created payment that is still in status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PENDING"]},"."," ","The endpoint can also be used to cancel a payment in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IDENTIFIED"]}," status, as long as the consumer has"," ","not initiated payment confirmation."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"-path-parameters-1","__idx":45},"children":["🧩 Path Parameters"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["(string, required)"]}," — Payment Id"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"-error-codes-for-delete-payment","__idx":46},"children":["🔧 Error Codes for ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete-payment"]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP Status"},"children":["HTTP Status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["401"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNAUTHORIZED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["user doesn't have an access token"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ACCESS_DENIED"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["access token is invalid"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["403"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CALLER_NOT_ALLOWED_TO_CANCEL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["if caller is not a participant of the payment"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["404"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_NOT_FOUND"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["payment is not found in the system"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["422"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PAYMENT_NOT_PENDING"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["payment is not in pending or identify state"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["500"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TECHNICAL_ERROR"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Technical error in Payment service"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"-sample-request--delete-payment","__idx":47},"children":["🔍 Sample Request – ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["delete-payment"]}]},{"$$mdtype":"Tag","name":"OpenApiCodeSample","attributes":{"descriptionFile":"oas-apis/merchant-payment.openapi.yaml","operationId":"cancel_payment","parameters":{},"environments":{}},"children":[]}]},"headings":[{"value":"Online Sales","id":"online-sales","depth":1},{"value":"Introduction","id":"introduction","depth":2},{"value":"Process Flow","id":"process-flow","depth":2},{"value":"Prerequisites","id":"prerequisites","depth":3},{"value":"Involved Parties","id":"involved-parties","depth":3},{"value":"Step-by-Step Payment Flow","id":"step-by-step-payment-flow","depth":2},{"value":"E-Commerce","id":"e-commerce","depth":3},{"value":"Merchant's Checkout Page","id":"merchants-checkout-page","depth":4},{"value":"Bancontacts Checkout Page","id":"bancontacts-checkout-page","depth":4},{"value":"M-Commerce","id":"m-commerce","depth":3},{"value":"Payment Flow Diagrams","id":"payment-flow-diagrams","depth":2},{"value":"E-Commerce, Merchant's Checkout Page","id":"e-commerce-merchants-checkout-page","depth":3},{"value":"E-Commerce, Bancontact's Checkout Page","id":"e-commerce-bancontacts-checkout-page","depth":3},{"value":"M-Commerce","id":"m-commerce-1","depth":3},{"value":"M-Commerce, Bancontact Fallback","id":"m-commerce-bancontact-fallback","depth":3},{"value":"Implementation Guide","id":"implementation-guide","depth":2},{"value":"1. Create Payment","id":"1-create-payment","depth":3},{"value":"📦 Request Body","id":"-request-body","depth":4},{"value":"📥 Response","id":"-response","depth":4},{"value":"🔧 Error Codes for create","id":"-error-codes-for-create","depth":4},{"value":"🔍 Sample Request – create payment","id":"-sample-request--create-payment","depth":4},{"value":"2.1 The Bancontact QR Code (E-Commerce)","id":"21-the-bancontact-qr-code-e-commerce","depth":3},{"value":"2.2 Invoking the Bancontact Universal Link (M-Commerce)","id":"22-invoking-the-bancontact-universal-link-m-commerce","depth":3},{"value":"App-to-App","id":"app-to-app","depth":4},{"value":"iOS","id":"ios","depth":5},{"value":"Android","id":"android","depth":5},{"value":"Mobile Browser to App","id":"mobile-browser-to-app","depth":4},{"value":"iOS","id":"ios-1","depth":5},{"value":"Android","id":"android-1","depth":5},{"value":"3. The Bancontact  Callback","id":"3-the-bancontact--callback","depth":3},{"value":"📦 Request Body","id":"-request-body-1","depth":4},{"value":"📥 Response","id":"-response-1","depth":4},{"value":"🔍 Sample Request – callback","id":"-sample-request--callback","depth":4},{"value":"Callback Failure","id":"callback-failure","depth":4},{"value":"4. Get Payment Details","id":"4-get-payment-details","depth":3},{"value":"🧩 Path Parameters","id":"-path-parameters","depth":4},{"value":"📥 Response","id":"-response-2","depth":4},{"value":"🔧 Error Codes for merchant-get-payment","id":"-error-codes-for-merchant-get-payment","depth":4},{"value":"🔍 Sample Request – merchant-get-payment","id":"-sample-request--merchant-get-payment","depth":4},{"value":"5. Get Payment List","id":"5-get-payment-list","depth":3},{"value":"📦 Request Body","id":"-request-body-2","depth":4},{"value":"📥 Response","id":"-response-3","depth":4},{"value":"🔧 Error Codes for search","id":"-error-codes-for-search","depth":4},{"value":"🔍 Sample Request – search","id":"-sample-request--search","depth":4},{"value":"Canceling a Payment","id":"canceling-a-payment","depth":2},{"value":"🧩 Path Parameters","id":"-path-parameters-1","depth":3},{"value":"🔧 Error Codes for delete-payment","id":"-error-codes-for-delete-payment","depth":3},{"value":"🔍 Sample Request – delete-payment","id":"-sample-request--delete-payment","depth":3}],"frontmatter":{"seo":{"title":"Online Sales"}},"lastModified":"2026-03-17T08:18:27.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/online/onlinesales","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}