Skip to content
Merchant Endpoints
/
create a payment

Payment V3 API (3.6.3)

APIs intended to support the merchant/partner's payment flow on creation, cancellation, search and refunds.

History

3.6.3 (2025-08-26)

  • Added JWS-Request-Signature-Payment for all payment call.

3.6.2 (2025-08-22)

  • Modified description by adding the SEPA requirements allowed character sets.
  • Modified reference by adding the SEPA requirements allowed character sets.
Download OpenAPI description
merchant-payment.openapi.json
merchant-payment.openapi.yaml
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/

Merchant Endpoints

Operations

get a payment by id

Request

This API is intended for merchants requiring information on a specific payment. Onboarded merchants should have api keys for each profile, the api key will carry the profileId information required to find the correct creditor in the merchant-service

The token/api-key necessary to call this endpoint must contain:

  • subjectType : INTEGRATOR:{CCV_ID} or MERCHANT:{ID}
  • resource: PAYMENTPROFILE:{profileId},
  • authority: MERCHANT_PAYMENT
Security
api_key_payment_profile or JWS-Request-Signature-Payment
Path
idstring= 24 charactersrequired
curl -i -X GET \
  'https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/v3/payments/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Payment details

Bodyapplication/json
paymentIdstring= 24 charactersrequired

id of the payment

createdAtstring(date-time)required

the creation time of the payment

expireAtstring(date-time)required

the time from which the payment will be expired

succeededAtstring(date-time)

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

currencystring(currency)required

Currency code. Only EUR is supported ISO 4217

Value"EUR"
statusstring(merchant-payment-status)required
StatusDescription
PENDINGThe merchant has created the payment and and is pending to proceed with identify step.
IDENTIFIEDThe user has scanned the payment's QR code with the Payconiq By Bancontact APP.
AUTHORIZEDThe user has confirmed the payment and the bank authorized it.
AUTHORIZATION_FAILEDThe authorization with the bank failed.
FAILEDSomething went wrong during the payment process(e.g authorization failed).
SUCCEEDEDThe payment has succeeded.
CANCELLEDWhen the payment has been canceled after the user has scanned it, or the merchant has cancelled the payment.
EXPIREDThe payment has expired.
PENDING_MERCHANT_ACKNOWLEDGEMENTThe payment is waiting for the merchant to acknowledge.
VOIDEDThe payment has been voided
Enum"PENDING""IDENTIFIED""AUTHORIZED""AUTHORIZATION_FAILED""SUCCEEDED""FAILED""CANCELLED""EXPIRED""PENDING_MERCHANT_ACKNOWLEDGEMENT""VOIDED"
creditorobject(payment_creditor_response)required

Creditor account set to receive the payment

creditor.​profileIdstring

The configuration ID of the Merchant

creditor.​merchantIdstring

the Id of the merchant

creditor.​namestring

Merchant's company name that will be shown to the debtor

creditor.​ibanstring

Creditor's Bank Account Iban to where the money will be sent to for this current payment

creditor.​identifyCallbackUrlstring

callbackUrl to which the merchant will be notified about the payment identification

creditor.​callbackUrlstring

callbackUrl to which the merchant will be notified about the payment payout

debtorobject
amountinteger(int64)required

Amount in cents originally requested. If no amount was requested by creditor, this will be 0

descriptionstring

merchant's description of the payment

messagestring

debtor's message of the payment

referencestring

Merchant payment reference, used to reference the Bancontact Payconiq Company payment. The characters used must comply with the SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices | European Payments Council. in the merchant's system

bulkIdstring

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.

_linksobject(links)

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)

Response
application/json
{
  "paymentId": "5f91483d-78a7-4914-bc6f=",
  "createdAt": "2019-08-24T14:15:22Z",
  "expireAt": "2019-08-24T14:15:22Z",
  "succeededAt": "2019-08-24T14:15:22Z",
  "currency": "EUR",
  "status": "PENDING",
  "creditor": {
    "profileId": "07e998f9-d932-4848-8b60-d5b5ae94b1b2",
    "merchantId": "dee718bb-3b6d-4312-9404-3d63d14529cc",
    "name": "John",
    "iban": "BE12 3456 7890 1234",
    "identifyCallbackUrl": "https://api.merchant.bancontact.net/identify",
    "callbackUrl": "https://api.merchant.bancontact.net/payment"
  },
  "debtor": {
    "name": "John",
    "iban": "*************12636"
  },
  "amount": 0,
  "description": "5 coke.",
  "message": "Money send.",
  "reference": "19848995",
  "bulkId": "Bulk-1-200",
  "_links": {
    "self": { … },
    "deeplink": { … },
    "qrcode": { … },
    "cancel": { … },
    "refund": { … },
    "checkout": { … }
  }
}

cancel a payment

Request

Endpoint responsible for canceling a payment on the request of a merchant. The caller has to be one of the participants of the payment. A payment can be cancelled only if has the status in PENDING or IDENTIFIED. When a payment is cancelled the status will be set to CANCELLED.

The token neccessary to call this endpoint as a merchant has to have:

  • subjectType : INTEGRATOR or MERCHANT
  • authority: MERCHANT_PAYMENT
  • resourceType : PAYMENTPROFILE
Security
api_key_payment_profile or JWS-Request-Signature-Payment
Path
idstring= 24 charactersrequired
curl -i -X DELETE \
  'https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/v3/payments/{id}' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Payment is successfully cancelled

Response
No content

search payments

Request

Endpoint responsible for searching payments by PaymentWebQuery model and returning the latest n(number set on the 'limit' parameter) payments, starting from the 'offset' payment(set in 'offset' parameter). By default the latest 10 payments (sorted by creation date descending) are returned per request

Security
api_key_payment_profile or JWS-Request-Signature-Payment
Query
pageinteger>= 0

zero-based page index in list requests.

Default 0
sizeinteger[ 0 .. 100 ]

the size of the page to be returned in list requests.

Default 10
Bodyapplication/json
fromstring(date-time)

default is today - 1day (yesterday)

tostring(date-time)
paymentStatusesArray of strings(merchant-payment-status)
Items Enum"PENDING""IDENTIFIED""AUTHORIZED""AUTHORIZATION_FAILED""SUCCEEDED""FAILED""CANCELLED""EXPIRED""PENDING_MERCHANT_ACKNOWLEDGEMENT""VOIDED"
referencestring

Merchant payment reference, used to reference Bancontact Payconiq 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.

curl -i -X POST \
  'https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/v3/payments/search?page=0&size=10' \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "from": "2019-08-24T14:15:22Z",
    "to": "2019-08-24T14:15:22Z",
    "paymentStatuses": [
      "PENDING"
    ],
    "reference": "19848995"
  }'

Responses

List of payments

Bodyapplication/json
sizeinteger>= 0required

Size of the elements returned in current page

totalPagesintegerrequired

Total number of pages in the backend for the list requested

totalElementsintegerrequired

Total number of elements in the list requested

numberintegerrequired

Current page number

detailsArray of objects(get_payment_response)
Response
application/json
{
  "size": 0,
  "totalPages": 0,
  "totalElements": 0,
  "number": 0,
  "details": [
    { … }
  ]
}

create a payment

Request

This API is intended for merchants initiating payments for specific profiles. Onboarded merchants should have api keys for each profile, the api key will carry the profileId information required to find the correct creditor in the merchant-service

The token/api-key necessary to call this endpoint must contain:

  • subjectType : "INTEGRATOR:{CCV_ID}" or "MERCHANT:{ID}"
  • resource: "PAYMENTPROFILE:{profileId}",
  • authority: MERCHANT_PAYMENT
Security
api_key_payment_profile or JWS-Request-Signature-Payment
Bodyapplication/json
referencestring<= 35 characters

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.

bulkIdstring<= 35 characters

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.

amountinteger(int64)( 1 .. 999999999999 ]required

Amount in cents requested

currencystring(currency)

Currency code. Only EUR is supported ISO 4217

Value"EUR"
descriptionstring<= 140 characters

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.

identifyCallbackUrlstring^https:\/\/([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(:\d...

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

callbackUrlstring^https:\/\/([a-zA-Z0-9-:]+\.)+[a-zA-Z]{2,}(:\...

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

returnUrlstring[ 1 .. 2048 ] characters^https:\/\/([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(:\d...

Merchant return url to which the dynamic payment page will redirect after the payment is completed

voucherEligibilityArray of objects(VoucherEligibleAmount)Deprecated

List of Value Added Services (vouchers) eligible amounts within the payment

curl -i -X POST \
  https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/v3/payments \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "19848995",
    "bulkId": "Bulk-1-200",
    "amount": 1,
    "currency": "EUR",
    "description": "string",
    "identifyCallbackUrl": "https://api.merchant.bancontact.net/identify",
    "callbackUrl": "https://api.merchant.bancontact.net/payment",
    "returnUrl": "https://api.merchant.bancontact.net/payment",
    "voucherEligibility": [
      {
        "voucherSchemes": [
          "BEL_MEAL_VOUCHER"
        ],
        "amount": 1013
      }
    ]
  }'

Responses

Payment has been created successfully

Bodyapplication/json
paymentIdstring= 24 charactersrequired

Payment ID

statusstringrequired

the status of the payment created

Value"PENDING"
createdAtstring(date-time)required

the creation time of the payment

expiresAtstring(date-time)required

the time from which the payment will be expired

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. Only first 35 characters will be used for the remittance info

referencestring

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.

amountinteger(int64)( 1 .. 999999999999 ]required

Amount in cents requested

currencystring(currency)required

Currency code. Only EUR is supported ISO 4217

Value"EUR"
creditorobject(payment_creditor_response)required

Creditor account set to receive the payment

creditor.​profileIdstring

The configuration ID of the Merchant

creditor.​merchantIdstring

the Id of the merchant

creditor.​namestring

Merchant's company name that will be shown to the debtor

creditor.​ibanstring

Creditor's Bank Account Iban to where the money will be sent to for this current payment

creditor.​identifyCallbackUrlstring

callbackUrl to which the merchant will be notified about the payment identification

creditor.​callbackUrlstring

callbackUrl to which the merchant will be notified about the payment payout

_linksobject(links)required

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)

_links.​selfobject(link)required
_links.​self.​hrefstringrequired
_links.​deeplinkobject(link)required
_links.​deeplink.​hrefstringrequired
_links.​qrcodeobject(link)required
_links.​qrcode.​hrefstringrequired
_links.​cancelobject(link)
_links.​refundobject(link)
_links.​checkoutobject(link)
Response
application/json
{
  "paymentId": "5f91483d-78a7-4914-bc6f=",
  "status": "PENDING",
  "createdAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z",
  "description": "string",
  "reference": "19848995",
  "amount": 1,
  "currency": "EUR",
  "creditor": {
    "profileId": "07e998f9-d932-4848-8b60-d5b5ae94b1b2",
    "merchantId": "dee718bb-3b6d-4312-9404-3d63d14529cc",
    "name": "John",
    "iban": "BE12 3456 7890 1234",
    "identifyCallbackUrl": "https://api.merchant.bancontact.net/identify",
    "callbackUrl": "https://api.merchant.bancontact.net/payment"
  },
  "_links": {
    "self": { … },
    "deeplink": { … },
    "qrcode": { … },
    "cancel": { … },
    "refund": { … },
    "checkout": { … }
  }
}

create static qr payment

Request

This API is intended for merchants initiating staticQR payments for specific POS(point of sale). If active payment already exists for provided combination of profileId and posId, then existing payment will be invalidated and new one created. Onboarded merchants should have api keys for each profile, the api key will carry the profileId information required to find the correct creditor in the merchant-service

The token/api-key necessary to call this endpoint must contain:

  • subjectType : "INTEGRATOR:{CCV_ID}" or "MERCHANT:{ID}"
  • resource: "PAYMENTPROFILE:{profileId}",
  • authority: MERCHANT_PAYMENT
Security
api_key_payment_profile or JWS-Request-Signature-Payment
Bodyapplication/json
referencestring(payment_reference)<= 35 characters

Partner payment reference, used to reference the Bancontact Payconiq Company payment in the partner's system

bulkIdstring(bulkId)<= 35 characters

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.

amountinteger(int64)( 1 .. 999999999999 ]required

Amount in cents requested

currencystring(currency)

Currency code. Only EUR is supported ISO 4217

Value"EUR"
descriptionstring(payment_description)<= 140 characters

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.

posIdstring(posId)<= 36 characters^[A-Za-z0-9]+$required

Merchant's point of sale identifier

shopIdstring(shopId)<= 36 characters

Id of the shop, where payment is created

shopNamestring<= 36 characters

Name of the shop, where payment is created. This name will be shown to the user during payment, but will be truncated in the remittance info, if longer than 23 characters.

identifyCallbackUrlstring

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

callbackUrlstring

Callback url to which the merchant will be notified about the payment payout/cancel. If it's not set here it will default to the one set in the profile

voucherEligibilityArray of objects(VoucherEligibleAmount)Deprecated

List of Value Added Services (vouchers) eligible amounts within the payment

curl -i -X POST \
  https://docs.payconiq.be/_mock/apis/merchant-payment.openapi/v3/payments/pos \
  -H 'Authorization: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "19848995",
    "bulkId": "Bulk-1-200",
    "amount": 1,
    "currency": "EUR",
    "description": "string",
    "posId": "POS00001",
    "shopId": "3418e946-ef71-41ef-ad56-c41421c1e079",
    "shopName": "Bun café",
    "identifyCallbackUrl": "https://api.merchant.bancontact.net/identify",
    "callbackUrl": "https://api.merchant.bancontact.net/payment",
    "voucherEligibility": [
      {
        "voucherSchemes": [
          "BEL_MEAL_VOUCHER"
        ],
        "amount": 1013
      }
    ]
  }'

Responses

Payment successfully created

Bodyapplication/json
paymentIdstring= 24 charactersrequired

Payment ID

statusstringrequired

the status of the payment created

Value"PENDING"
createdAtstring(date-time)required

the creation time of the payment

expiresAtstring(date-time)required

the time from which the payment will be expired

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. Only first 35 characters will be used for the remittance info

referencestring

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.

amountinteger(int64)( 1 .. 999999999999 ]required

Amount in cents requested

currencystring(currency)required

Currency code. Only EUR is supported ISO 4217

Value"EUR"
creditorobject(payment_creditor_response)required

Creditor account set to receive the payment

creditor.​profileIdstring

The configuration ID of the Merchant

creditor.​merchantIdstring

the Id of the merchant

creditor.​namestring

Merchant's company name that will be shown to the debtor

creditor.​ibanstring

Creditor's Bank Account Iban to where the money will be sent to for this current payment

creditor.​identifyCallbackUrlstring

callbackUrl to which the merchant will be notified about the payment identification

creditor.​callbackUrlstring

callbackUrl to which the merchant will be notified about the payment payout

_linksobject(links)required

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)

_links.​selfobject(link)required
_links.​self.​hrefstringrequired
_links.​deeplinkobject(link)required
_links.​deeplink.​hrefstringrequired
_links.​qrcodeobject(link)required
_links.​qrcode.​hrefstringrequired
_links.​cancelobject(link)
_links.​refundobject(link)
_links.​checkoutobject(link)
Response
application/json
{
  "paymentId": "5f91483d-78a7-4914-bc6f=",
  "status": "PENDING",
  "createdAt": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z",
  "description": "string",
  "reference": "19848995",
  "amount": 1,
  "currency": "EUR",
  "creditor": {
    "profileId": "07e998f9-d932-4848-8b60-d5b5ae94b1b2",
    "merchantId": "dee718bb-3b6d-4312-9404-3d63d14529cc",
    "name": "John",
    "iban": "BE12 3456 7890 1234",
    "identifyCallbackUrl": "https://api.merchant.bancontact.net/identify",
    "callbackUrl": "https://api.merchant.bancontact.net/payment"
  },
  "_links": {
    "self": { … },
    "deeplink": { … },
    "qrcode": { … },
    "cancel": { … },
    "refund": { … },
    "checkout": { … }
  }
}

Callback to Merchants

Operations

Merchant Acknowledge

Operations

Refunds

Operations