Skip to content
/
cancel a payment

Payment V3 API (3.6.5)

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

History

3.6.5 (2025-08-29)

  • No longer returning REFUND_NOT_ALLOWED error for products with refundAllowed=false in getDebtorIban operation.

3.6.4 (2025-08-26)

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

3.6.3 (2025-08-22)

  • Modified description by adding the SEPA requirements allowed character sets.
  • Modified reference by adding the SEPA requirements allowed character sets.

3.6.2 (2025-07-17)

  • Removed totalAmount, tippingAmount, and transferAmount from the Open API, as they are no longer in use.
  • Added examples to provide additional context.
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
Value"EUR"
statusstring(merchant-payment-status)required
Enum"PENDING""IDENTIFIED""AUTHORIZED""AUTHORIZATION_FAILED""SUCCEEDED""FAILED""CANCELLED""EXPIRED""PENDING_MERCHANT_ACKNOWLEDGEMENT""VOIDED"
creditorobject(payment_creditor_response)required
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)
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)
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[ 1 .. 2048 ] characters^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[ 1 .. 2048 ] characters^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
Value"EUR"
creditorobject(payment_creditor_response)required
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
_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
bulkIdstring(bulkId)<= 35 characters
amountinteger(int64)( 1 .. 999999999999 ]required

Amount in cents requested

currencystring(currency)
Value"EUR"
descriptionstring(payment_description)<= 140 characters
posIdstring(posId)<= 36 characters^[A-Za-z0-9]+$required
shopIdstring(shopId)<= 36 characters
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[ 1 .. 2048 ] characters

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[ 1 .. 2048 ] characters

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
Value"EUR"
creditorobject(payment_creditor_response)required
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
_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