# Payment V3 API

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.


Version: 3.6.3

## Servers

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

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

## Security

### api_key_payment_profile

Bearer authentication with API Key generated by API Manager. Used to get/create payments for a specific Merchant Profile or create refunds for a specific payment.

Type: apiKey
In: header
Name: Authorization

### JWS-Request-Signature-Payment

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

Bancontact Payconiq Company hosts the certificates in [JWK format](https://tools.ietf.org/html/rfc7517) as [JWKS](https://tools.ietf.org/html/rfc7517#appendix-B) at :
- https://jwks.bancontact.net/
- https://jwks.preprod.bancontact.net/
for PROD and PREPROD environments respectively.

The merchant system should download the certificate in JWK format from the URL specified above.

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 V3 API](https://docs.payconiq.be/_spec/apis/merchant-payment.openapi.yaml)

## Merchant Endpoints

### get a payment by id

 - [GET /v3/payments/{id}](https://docs.payconiq.be/apis/merchant-payment.openapi/merchant-endpoints/merchant-get-payment.md): 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:

*  :  or 
* : ,
* : 

### cancel a payment

 - [DELETE /v3/payments/{id}](https://docs.payconiq.be/apis/merchant-payment.openapi/merchant-endpoints/cancel_payment.md): 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  has to have:
-  :  or 
- : 
-  : 

### search payments

 - [POST /v3/payments/search](https://docs.payconiq.be/apis/merchant-payment.openapi/merchant-endpoints/search.md): 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


### create a payment

 - [POST /v3/payments](https://docs.payconiq.be/apis/merchant-payment.openapi/merchant-endpoints/create.md): 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:
*  : "" or ""
* : "",
* : 

### create static qr payment

 - [POST /v3/payments/pos](https://docs.payconiq.be/apis/merchant-payment.openapi/merchant-endpoints/create_static_qr_payment.md): 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:
*  : "" or ""
* : "",
* : 

## Callback to Merchants

### notify merchants about statuses changes

 - [POST /callback](https://docs.payconiq.be/apis/merchant-payment.openapi/callback-to-merchants/callback.md): Each merchant needs to define a specific endpoint to their backend (e.g., https://checkout.company.com/webhook/91FA6EEC30844FAAB5). This endpoint will be called by Bancontact Payconiq Company with details about the payment. This allows the merchant’s backend to process the data (mark the transaction in database, update the product count number, send email to the customer, etc.). Since webhooks are asynchronous, their order is not guaranteed.

The JSON-formatted POST request contains payment details. Bancontact Payconiq Company will sign the callback request using a JWS signature (see the specification of the Signature header for more details). In case of no response from the callback endpoint, Bancontact Payconiq Company will call the endpoint again up to three times per payment. The app must verify that:

* Notification messages originated from Bancontact Payconiq Company
* Were not altered or corrupted during transmission
* Are targeted for you
* Contain a valid signature.

## Merchant Acknowledge

### Merchant acknowledges payment status callback was received

 - [POST /v3/payments/{id}/acknowledge](https://docs.payconiq.be/apis/merchant-payment.openapi/merchant-acknowledge/merchant-acknowledge.md)

## Refunds

### get debtor's refund IBAN

 - [GET /v3/payments/{id}/debtor/refundIban](https://docs.payconiq.be/apis/merchant-payment.openapi/refunds/create-refund.md): This endpoint returns the debtor IBAN that the merchant can use to transfer the money directly. This process does not handle any money flow with the debtor.

The token/api-key necessary to call this endpoint must contain:
*  : "" or ""
* : "",
* : 

- Refunds are not allowed for P2P and PAYMENT_REQUEST
- The payment specified should be in the SUCCEEDED state
- The endpoint can be called multiple times by the Merchant, there's no restriction for that