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.
Payment V3 API (3.6.3)
APIs intended to support the merchant/partner's payment flow on creation, cancellation, search and refunds.
Download OpenAPI description
Languages
Servers
Mock server
https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/
PREPROD merchant API
https://merchant.api.preprod.bancontact.net/
PROD merchant API
https://merchant.api.bancontact.net/
Request
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 Payconiq 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 Payconiq 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 Payconiq Company
- Were not altered or corrupted during transmission
- Are targeted for you
- Contain a valid signature.
Security
JWS-Request-Signature-Payment
Headers
Bodyapplication/jsonDetached JWS signature of response payload.
Bancontact Payconiq Company hosts the certificates in JWK format at Bancontact Payconiq 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))
{ "typ": "jose+json", "kid": "JWK kid", "alg": "ES256", "sub" : "{merchantProfileId}", "x5t#S256" : "X.509 certificate SHA-256 thumbprint.", "https://payconiq.com/iss" : "Payconiq", "https://payconiq.com/iat" : "{Current creation date time in ISODateTime format, 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.
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.
Merchant payment reference, used to reference the Bancontact Payconiq 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.
When the payment is going to expire. After that date the payment can't be confirmed anymore
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 Payconiq By Bancontact APP. |
| 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 |
Enum"PENDING""IDENTIFIED""AUTHORIZED""AUTHORIZATION_FAILED""SUCCEEDED""FAILED""CANCELLED""EXPIRED""PENDING_MERCHANT_ACKNOWLEDGEMENT""VOIDED"
- Mock server
https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/callback
- PREPROD merchant API
https://merchant.api.preprod.bancontact.net/callback
- PROD merchant API
https://merchant.api.bancontact.net/callback
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/callback \
-H 'Content-Type: application/json' \
-H 'Signature: YOUR_API_KEY_HERE' \
-H 'User-Agent: Payconiq' \
-d '{
"paymentId": "5f91483d-78a7-4914-bc6f=",
"currency": "EUR",
"amount": 0,
"description": "string",
"reference": "19848995",
"createdAt": "2019-08-24T14:15:22Z",
"expireAt": "2019-08-24T14:15:22Z",
"succeededAt": "2019-08-24T14:15:22Z",
"status": "PENDING",
"debtor": {
"iban": "*************12636",
"name": "John"
}
}'Response
application/json
{}