# Payment Refund Service API

API allows merchant/integrator to create/get/search payment refunds.

## History

### 3.0.3 (2025-10-01)

* Removed DEV and ACC environment.
* Added description for PREPROD and PROD environments
* Added `/v3` prefixes to operation paths.

### 3.0.2 (2025-07-28)

* Removed `PROCESSING` status from the refund status.
* Removed `DEBTOR_IBAN_NOT_AVAILABLE` error code from the refund creation endpoint.


Version: 3.0.3

## Servers

PREPROD merchant API
```
https://merchant.api.preprod.bancontact.net
```

PROD merchant API
```
https://merchant.api.bancontact.net
```

## Security

### JWS-Request-Signature-Refund

[Detached JWS signature of request payload](https://tools.ietf.org/html/rfc7797).

Merchant/Partner MUST host the public key in [JWK format](https://tools.ietf.org/html/rfc7517) as [JWKS](https://tools.ietf.org/html/rfc7517#section-3)
and share the URL with Bancontact Company during integration.

The signature must be computed as per following instructions:

    jws = base64URLEncode(JOSE Header)..alg(base64URLEncode(JOSE Header).base64URLEncode(Request Body))

    [JOSE Header](https://tools.ietf.org/html/rfc7515#section-4) =

    {
      "typ": "jose+json",
      "kid": "JWK kid",
      "alg": "ES256",
      "https://payconiq.com/sub" : "{merchantProfileId}",
      "https://payconiq.com/iss" : "Payconiq",
      "https://payconiq.com/iat" : "{Current creation date time in [ISODateTime format](https://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/datatypes/_YW1tKtp-Ed-ak6NoX_4Aeg_-1624336183), 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/sub", "https://payconiq.com/iss", "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path"]
    }

JWS Payload MUST be the same as response body as base64url encoded JSON data.

Type: apiKey
In: header
Name: Signature

## Download OpenAPI description

[Payment Refund Service API](https://docs.bancontactpro.com/_bundle/apis/refund-public.openapi.yaml)

## Other

### Create refund for payment

 - [POST /v3/payments/{payment-id}/refunds](https://docs.bancontactpro.com/apis/refund-public.openapi/other/createrefund.md): Endpoint to initiate refund of Bancontact Company payment to the debtor.
This endpoint is idempotent based on 'Idempotency-Key' header. So the same request can be safely retried in case of timeout/network issue.

### get refund by id

 - [GET /v3/payments/{payment-id}/refunds/{refund-id}](https://docs.bancontactpro.com/apis/refund-public.openapi/other/getrefundbyid.md): Endpoint to get refund details by id.