Merchant Endpoints

Merchant Endpoints
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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

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"

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
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Operations

Merchant Acknowledge
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Operations

Refunds
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Operations

Payment V3 API (3.6.3)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

History

3.6.3 (2025-08-26)

3.6.2 (2025-08-22)