---
title: "notify merchants about statuses changes"
method: POST
path: "/callback"
tags: ["Callback to Merchants"]
---

# notify merchants about statuses changes

`POST /callback`

Each merchant needs to define a specific endpoint to their backend (e.g., https://checkout.company.com/webhook/91FA6EEC30844FAAB5). This endpoint will be called by Bancontact Company with details about the payment. This allows the merchant’s backend to process the data (mark the transaction in database, update the product count number, send email to the customer, etc.). Since webhooks are asynchronous, their order is not guaranteed.

The JSON-formatted POST request contains payment details. Bancontact Company will sign the callback request using a JWS signature (see the specification of the Signature header for more details). In case of no response from the callback endpoint, Bancontact Payconiq Company will call the endpoint again up to three times per payment. The app must verify that:

* Notification messages originated from Bancontact  Company
* Were not altered or corrupted during transmission
* Are targeted for you
* Contain a valid signature.

## Headers

- `Signature` string, required
- `User-Agent` string, required
- `Content-Type` string, required

## Request body

- MerchantCallback
  - `paymentId` string, required — Bancontact Company Payment ID
  - `currency` string, required — Only EUR is supported currently
  - `amount` integer, required — Requested amount in cents
  - `description` string — 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).
  - `reference` string — 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).
  - `createdAt` string, date-time, required — When the payment was created
  - `expireAt` string, date-time — When the payment is going to expire. After that date the payment can't be confirmed anymore
  - `succeededAt` string, date-time — if the payment is SUCCEEDED, then this field represents the date-time on which the payment was SUCCEEDED
  - `status` 'PENDING' | 'IDENTIFIED' | 'AUTHORIZED' | 'AUTHORIZATION_FAILED' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED' | 'EXPIRED' | 'PENDING_MERCHANT_ACKNOWLEDGEMENT' | 'VOIDED', required — | Status | Description | |--------|-------------| | PENDING | The merchant has created the payment and and is pending to proceed with identify step. | | IDENTIFIED | The user has scanned the payment's QR code with the Bancontact Pay. | | AUTHORIZED | The user has confirmed the payment and the bank authorized it. | | AUTHORIZATION_FAILED | The authorization with the bank failed. | | FAILED | Something went wrong during the payment process(e.g authorization failed). | | SUCCEEDED | The payment has succeeded. | | CANCELLED | When the payment has been canceled after the user has scanned it, or the merchant has cancelled the payment.| | EXPIRED | The payment has expired. | | PENDING_MERCHANT_ACKNOWLEDGEMENT | The payment is waiting for the merchant to acknowledge. | | VOIDED | The payment has been voided |
  - `debtor` object, required — Customer that paid
    - `iban` string, required — Debtor's IBAN masked
    - `name` string — Debtor's first name

## Response `200`

If sync callback is configured (in the merchant profile), Bancontact Company waits a response from the callback endpoint and a return code of 200 informs Bancontact  Company that the merchant accepts this payment

- object

## Other responses

- `422` — If sync callback is configured (in the merchant profile), Bancontact Company waits a response from the callback endpoint and an error code of 4xx or 5xx informs Bancontact Company that the merchant rejects this payment and the status of the payment will be set to FAILED. This behavior also applies if the merchant callback times out (5 seconds). Bancontact Company has a retry mechanism so in total Bancontact Company will make 3 calls to confirm the payment with the merchant, in case they time out the payment will be marked as FAILED

---

[API](https://skmtc.net/bancontactpro/apis/payment-v3-api.md) · [All operations](https://skmtc.net/bancontactpro/apis/payment-v3-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bancontactpro/payment-v3-api/versions/4093d799b771/schema)