Bancontact Pro Payment V3 API

openapi: 3.1.0
info:
  title: Payment V3 API
  version: 3.6.5
  description: '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.

    '
  x-source:
    url: https://docs.bancontactpro.com/_bundle/apis/merchant-payment.openapi.yaml
    docs: https://docs.bancontactpro.com/apis/merchant-payment.openapi
    fetched: '2026-09-17'
    method: searched
    note: Verbatim first-party bundle published by the Bancontact Pro developer portal (Redocly); untouched
      copy in openapi/_original/.
paths:
  /v3/payments/{id}:
    get:
      responses:
        '200':
          description: Payment details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/get_payment_response'
        '401':
          description: '**Error Codes**

            * `UNAUTHORIZED`: caller doesn’t have an api-key access token'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: '**Error Codes**

            * `ACCESS_DENIED`: api-key access token is invalid, creditor it''s not a participant of the
            requested payment'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: '**Error Codes**

            * `PAYMENT_NOT_FOUND`: no payment could be found

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: '**Error Codes**

            '
        '500':
          description: '**Error Codes**

            * `TECHNICAL_ERROR`: Technical error in Payment service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '503':
          description: '**Error Codes**'
      description: "This API is intended for merchants requiring information on a specific payment. \n\
        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\n\nThe token/api-key\
        \ necessary to call this endpoint must contain:\n\n* `subjectType` : `INTEGRATOR:{CCV_ID}` or\
        \ `MERCHANT:{ID}`\n* `resource`: `PAYMENTPROFILE:{profileId}`,\n* `authority`: `MERCHANT_PAYMENT`"
      operationId: merchant-get-payment
      tags:
      - Merchant Endpoints
      security:
      - api_key_payment_profile: []
      - JWS-Request-Signature-Payment: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          minLength: 24
          maxLength: 24
      summary: get a payment by id
    delete:
      responses:
        '204':
          description: Payment is successfully cancelled
        '401':
          description: '* `UNAUTHORIZED`: user doesn''t have an access token'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: '* `ACCESS_DENIED`: access token is invalid

            * `CALLER_NOT_ALLOWED_TO_CANCEL`: if caller is not a participant of the payment'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: '* `PAYMENT_NOT_FOUND`: payment is not found in the system'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: '* `PAYMENT_NOT_PENDING`: payment is not in pending or identify state'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: '**Error Codes**

            '
        '500':
          description: '* `TECHNICAL_ERROR`: Technical error in Payment service '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '503':
          description: ''
      description: '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`'
      tags:
      - Merchant Endpoints
      operationId: cancel_payment
      summary: cancel a payment
      security:
      - api_key_payment_profile: []
      - JWS-Request-Signature-Payment: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
          minLength: 24
          maxLength: 24
  /v3/payments/search:
    post:
      responses:
        '200':
          description: List of payments
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSearchResponse'
        '401':
          description: '**Error Codes**

            * `UNAUTHORIZED`: caller doesn’t have an api-key access token'
        '403':
          description: '**Error Codes**

            * `ACCESS_DENIED`: api-key access token is invalid, creditor it''s not a participant of the
            requested payment'
        '429':
          description: '**Error Codes**

            '
        '500':
          description: '**Error Codes**

            * `TECHNICAL_ERROR`: Technical error in Payment service'
        '503':
          description: ''
      description: '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

        '
      operationId: search
      tags:
      - Merchant Endpoints
      summary: search payments
      security:
      - api_key_payment_profile: []
      - JWS-Request-Signature-Payment: []
      parameters:
      - in: query
        name: page
        description: zero-based page index in list requests.
        schema:
          type: integer
          minimum: 0
          default: 0
      - in: query
        name: size
        description: the size of the page to be returned in list requests.
        schema:
          type: integer
          minimum: 0
          maximum: 100
          default: 10
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment-search-query'
  /v3/payments:
    post:
      responses:
        '201':
          description: Payment has been created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_create_response'
        '400':
          description: '**Error Codes**

            * `BODY_MISSING`: A json needs to be provided

            * `FIELD_IS_REQUIRED`: Field X is mandatory

            * `FIELD_IS_INVALID`: Field X is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: '**Error Codes**

            * `UNAUTHORIZED`: user doesn’t have an access token'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: '**Error Codes**

            * `ACCESS_DENIED`: The JWT could not be verified (different format) - The JWT doesn’t contain
            the required authority to access the resource requested'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: '**Error Codes**

            * `MERCHANT_PROFILE_NOT_FOUND`: The merchant profile does not exist'
        '422':
          description: '**Error Codes**

            * `UNABLE_TO_PAY_CREDITOR`: Variable reason(Depends on automatic processing).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: '**Error Codes**

            '
        '500':
          description: '**Error Codes**

            * `TECHNICAL_ERROR`: Technical error in Payment service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '503':
          description: '**Error Codes**

            * `TRY_AGAIN_LATER`: one of the internal services is unavailable'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      description: '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`'
      summary: create a payment
      security:
      - api_key_payment_profile: []
      - JWS-Request-Signature-Payment: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/payment_create_request'
      operationId: create
      tags:
      - Merchant Endpoints
  /callback:
    post:
      responses:
        '200':
          description: If sync callback is configured (in the merchant profile), Bancontact Company waits
            a response from the callback endpoint and a return code of 200 informs Bancontact  Company
            that the merchant accepts this payment
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '422':
          description: 'If sync callback is configured (in the merchant profile), Bancontact Company waits
            a response from the callback endpoint and an error code of 4xx or 5xx informs Bancontact Company
            that the merchant rejects this payment and the status of the payment will be set to FAILED.


            This behavior also applies if the merchant callback times out (5 seconds). Bancontact  Company
            has a retry mechanism so in total Bancontact Company will make 3 calls to confirm the payment
            with the merchant, in case they time out the payment will  be marked as FAILED'
      description: '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 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 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  Company

        * Were not altered or corrupted during transmission

        * Are targeted for you

        * Contain a valid signature.'
      operationId: callback
      tags:
      - Callback to Merchants
      parameters:
      - in: header
        name: Signature
        required: true
        description: "[Detached JWS signature of response payload](https://tools.ietf.org/html/rfc7797).\n\
          \nBancontact  Company hosts the certificates in [JWK format](https://tools.ietf.org/html/rfc7517)\
          \ at Bancontact  Company hosts the Public Key in JWK format as JWKS at:\n- https://jwks.bancontact.net/\n\
          - https://jwks.preprod.bancontact.net/\nfor PROD and PREPROD environments respectively.\nThe\
          \ merchant system should download the certificate in JWK format from the URL specified above\
          \ and verify the certificate thumbprint present in x5t#S256 JOSE header against the downloaded\
          \ certificate.\n\nThe signature must be computed as per following instructions:\n\n    jws =\
          \ base64URLEncode(JOSE Header)..alg(base64URLEncode(JOSE Header).base64URLEncode(Request Body))\n\
          \n    [JOSE Header](https://tools.ietf.org/html/rfc7515#section-4) =\n\n    {\n      \"typ\"\
          : \"jose+json\",\n      \"kid\": \"JWK kid\",\n      \"alg\": \"ES256\",\n      \"sub\" : \"\
          {merchantProfileId}\",\n      \"x5t#S256\" : \"[X.509 certificate SHA-256 thumbprint](https://tools.ietf.org/html/rfc7515#section-4.1.8).\"\
          ,\n      \"https://payconiq.com/iss\" : \"Payconiq\",\n      \"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)},\n      \"https://payconiq.com/jti\"\
          \ : \"{Unique-request-identifier}\",\n      \"https://payconiq.com/path\": \"request path ex.\
          \ /v3/payments/{payment-id}/confirm\"\n      \"crit\": [\"https://payconiq.com/iss\", \"https://payconiq.com/iat\"\
          , \"https://payconiq.com/jti\", \"https://payconiq.com/path\"]\n    }\n\nJWS Payload will be\
          \ the same as the request body."
        schema:
          type: string
      - in: header
        name: User-Agent
        required: true
        description: The User-Agent request header contains a characteristic string that allows the network
          protocol peers to identify the application type, operating system, software vendor or software
          version of the requesting software user agent.
        schema:
          type: string
          default: Payconiq
      - in: header
        name: Content-Type
        required: true
        description: The Content-Type entity header is used to indicate the media type of the resource.
        schema:
          type: string
          default: application/json
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/merchant-callback'
      summary: notify merchants about statuses changes
      security:
      - JWS-Request-Signature-Payment: []
  /v3/payments/{id}/acknowledge:
    post:
      summary: Merchant acknowledges payment status callback was received
      operationId: merchant-acknowledge
      security:
      - api_key_payment_profile: []
      - JWS-Request-Signature-Payment: []
      parameters:
      - in: path
        name: id
        description: Bancontact  Company Payment Id
        required: true
        schema:
          type: string
          minLength: 24
          maxLength: 24
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/merchant-acknowledge'
      tags:
      - Merchant Acknowledge
      responses:
        '202':
          description: The acknowledge request for the specified payment has been processed
        '400':
          description: '**Error Codes**

            * `FIELD_IS_REQUIRED`: Field X is mandatory

            * `FIELD_IS_INVALID`: Field X is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: '**Error Codes**

            * `UNAUTHORIZED`: caller doesn’t have an api-key access token'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: '**Error Codes**

            * `ACCESS_DENIED`: The JWT could not be verified or doesn’t contain the required authority
            to access the resource requested'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: '**Error Codes**

            * `PAYMENT_NOT_FOUND`: no payment could be found for the supplied identifier'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: '**Error Codes**

            * `PAYMENT_VOIDED`: Payment is already voided'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: '**Error Codes**

            * `TECHNICAL_ERROR`: Technical error in Payment service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '503':
          description: '**Error Codes**

            * `SERVICE_UNAVAILABLE`: Payment service could not be reached or some unexpected error occurred'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
  /v3/payments/{id}/debtor/refundIban:
    get:
      responses:
        '200':
          description: The IBAN of the debtor used in the specified payment
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/refund-response'
        '401':
          description: '**Error Codes**

            * `UNAUTHORIZED`: caller doesn’t have an api-key access token'
        '403':
          description: '**Error Codes**

            * `ACCESS_DENIED`: access token is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: '**Error Codes**

            * `PAYMENT_NOT_FOUND`: no payment could be found for the supplied identifier'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: '**Error Codes**

            * `REFUND_NOT_ALLOWED`: The payment is not in a `SUCCEEDED` state

            * `REFUND_NOT_AVAILABLE`: debtor details are not available yet'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '429':
          description: '**Error Codes**

            '
        '500':
          description: '**Error Codes**

            * `TECHNICAL_ERROR`: Technical error in Payment service'
        '503':
          description: ''
      description: '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:

        * `subjectType` : "`INTEGRATOR:{CCV_ID}`" or "`MERCHANT:{ID}`"

        * `resource`: "`PAYMENTPROFILE:{profileId}`",

        * `authority`: `MERCHANT_REFUND`


        - 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

        '
      operationId: create-refund
      tags:
      - Refunds
      security:
      - api_key_payment_profile: []
      - JWS-Request-Signature-Payment: []
      parameters:
      - in: path
        name: id
        required: true
        description: id of the payment for which to get the debtor's IBAN needed to refund
        schema:
          type: string
          minLength: 24
          maxLength: 24
      summary: get debtor's refund IBAN
  /v3/payments/pos:
    post:
      responses:
        '201':
          description: Payment successfully created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/payment_create_response'
        '400':
          description: '**Error Codes**

            * `BODY_MISSING`: A json needs to be provided

            * `FIELD_IS_REQUIRED`: Field X is mandatory

            * `FIELD_IS_INVALID`: Field X is invalid'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '401':
          description: '**Error Codes**

            * `UNAUTHORIZED`: user doesn’t have an access token'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '403':
          description: '**Error Codes**

            * `ACCESS_DENIED`: The JWT could not be verified (different format) - The JWT doesn’t contain
            the required authority to access the resource requested'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: '**Error Codes**

            * `MERCHANT_PROFILE_NOT_FOUND`: The merchant profile does not exist'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '422':
          description: '**Error Codes**

            * `UNABLE_TO_PAY_CREDITOR`: Variable reason(Depends on automatic processing).'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '500':
          description: '**Error Codes**

            * `TECHNICAL_ERROR`: Technical error in Payment service'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '503':
          description: '**Error Codes**

            * `TRY_AGAIN_LATER`: one of the internal services is unavailable'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      summary: create static qr payment
      tags:
      - Merchant Endpoints
      description: '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: []
      - JWS-Request-Signature-Payment: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/static_qr_payment_create_request'
      operationId: create_static_qr_payment
tags:
- name: Merchant Endpoints
security:
- api_key_payment_profile: []
servers:
- url: https://merchant.api.preprod.bancontact.net
  description: PREPROD merchant API


# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bancontact/refs/heads/main/openapi/bancontact-payment-v3-api-openapi.yml