Skip to content
Last updated

Refunds

Introduction

The Refund API enables merchants to issue full or partial refunds linked to SUCCEEDED payments. Refunds are triggered from the merchant’s backend and are tracked using a merchant-generated reference. To ensure a payment is not refunded multiple times Bancontact Payconiq uses indempotency checks. It is important to:

  • Keep the same indempotency key for refund retrys (failure code 4XX or 5XX)
  • Change the indempotency key if you are deliberately issuing multiple refunds for a payment.

Refunds can be initiated, monitored, and supported through the set of endpoints defined below.

Succesfull refunds will be deducted from your ongoing settlement payout (bulk payout). If you have insufficient funds the refund will be refused.

Important Note: the getRefundIbanendpoint should be called unsing an API Key and does not require activation in Bancontact Payconiq's backend. However, the createRefund endpoint requires a JSON Web Signature (JWS) and must be activated by our Support Team in our backend. To activate this endpoint, please reach out to your Account Manager or to our Support Team at devsupport@payconiq.be

For the full endpoint documentation, please refer to the Merchant Payment API. for GET Refund Endpoint and to Refund API for CREATE Refund and GET Refund by ID endpoints.

For more information on Payouts and Remittance Information, please refer to this guide.

Get Refund IBAN

Retrieve the IBAN of the consumer who made the original payment. This endpoint is useful for refund processing, validation, or audit logging purposes.

This request dos not handle any money flow, but will simply provide the debtor's data.

Path Parameters

NameTypeRequiredDescription
paymentIdstringYesThe ID of the original Payconiq payment.

Response

ibanstringrequired

Debtor's IBAN

Error Codes

HTTP StatusCodeMeaning
401UNAUTHORIZEDAPI key is invalid or missing.
403ACCESS_DENIEDAccess token is invalid.
422REFUND_NOT_FOUND or REFUND_NOT_AVAILABLEThe Payment is P2P or Debtor Details are not Available
404PAYMENT_NOT_FOUNDNo payment found for the specified ID.
500TECHNICAL_ERRORInternal error in the payment service.

Sample Request – getRefundIban

curl -i -X GET \
  'https://merchant.api.preprod.bancontact.net/v3/payments/{id}/debtor/refundIban' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Create Refund

Use this endpoint to initiate a refund linked to a completed Payconiq payment.

⚠️ The payment must be in SUCCEEDED status to be eligible for refund.

📦 Request Body

amountinteger(int64)(Amount)( 1 .. 999999999999 ]required

Amount in cents

currencystring(Currency)required

currency code. Only EUR is supported ISO 4217

Default "EUR"
Value"EUR"
descriptionstring

refund description

📥 Response

refundIdstring(RefundId)= 24 charactersrequired

refund identifier

paymentIdstring(PaymentId)= 24 charactersrequired

payment identifier

statusstringrequired

Refund status after creation. Always has value 'PENDING', because refund processing is asynchronous. Current status can be checked using GET '/v3/payments/{payment-id}/refunds/{refund-id}' endpoint.

Value"PENDING"
amountinteger(int64)(Amount)( 1 .. 999999999999 ]required

Amount in cents

currencystring(Currency)required

currency code. Only EUR is supported ISO 4217

Default "EUR"
Value"EUR"
descriptionstring(RefundDescription)

refund description

creationDatestring(date-time)(RefundCreationDate)required

timestamp, when refund was created

🔧 Error Codes for createRefund

codestringrequired

Error code

messagestringrequired

Error message

🔍 Sample Request – createRefund

curl -i -X POST \
  'https://merchant.api.preprod.bancontact.net/payments/{payment-id}/refunds' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'Signature: YOUR_API_KEY_HERE' \
  -d '{
    "amount": 1,
    "currency": "EUR",
    "description": "string"
  }'
Previous page
Next page