v1

latestOpenAPI 3.1.02026-08-0683254.8 KB

Callback to Merchants

notify merchants about statuses changes

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.

post/callback

Headers

Signaturestring required

Detached JWS signature of response payload.

Bancontact Company hosts the certificates in JWK format at Bancontact Company hosts the Public Key in JWK format as JWKS at:

https://jwks.bancontact.net/
https://jwks.preprod.bancontact.net/ for PROD and PREPROD environments respectively. The merchant system should download the certificate in JWK format from the URL specified above and verify the certificate thumbprint present in x5t#S256 JOSE header against the downloaded certificate.

The signature must be computed as per following instructions:

jws = base64URLEncode(JOSE Header)..alg(base64URLEncode(JOSE Header).base64URLEncode(Request Body))

[JOSE Header](https://tools.ietf.org/html/rfc7515#section-4) =

{
  "typ": "jose+json",
  "kid": "JWK kid",
  "alg": "ES256",
  "sub" : "{merchantProfileId}",
  "x5t#S256" : "[X.509 certificate SHA-256 thumbprint](https://tools.ietf.org/html/rfc7515#section-4.1.8).",
  "https://payconiq.com/iss" : "Payconiq",
  "https://payconiq.com/iat" : "{Current creation date time in [ISODateTime format](https://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/datatypes/_YW1tKtp-Ed-ak6NoX_4Aeg_-1624336183), expressed in UTC time format(YYYY-MM-DDThh:mm:ss.sssZ)},
  "https://payconiq.com/jti" : "{Unique-request-identifier}",
  "https://payconiq.com/path": "request path ex. /v3/payments/{payment-id}/confirm"
  "crit": ["https://payconiq.com/iss", "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path"]
}

JWS Payload will be the same as the request body.

User-Agentstring required

The User-Agent request header contains a characteristic string that allows the network protocol peers to identify the application type, operating system, software vendor or software version of the requesting software user agent.

Content-Typestring required

The Content-Type entity header is used to indicate the media type of the resource.

Request body

paymentIdstring required

Bancontact Company Payment ID

currencystring required

Only EUR is supported currently

amountinteger required

Requested amount in cents

descriptionstring

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.

referencestring

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.

createdAtstring date-time required

When the payment was created

expireAtstring date-time

When the payment is going to expire. After that date the payment can't be confirmed anymore

succeededAtstring date-time

if the payment is SUCCEEDED, then this field represents the date-time on which the payment was SUCCEEDED

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

Example request

{
  "paymentId": "5f91483d-78a7-4914-bc6f=",
  "reference": "19848995",
  "debtor": {
    "iban": "*************12636",
    "name": "John"
  }
}

Response

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 required