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

        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`
      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
            Payconiq Company waits a response from the callback endpoint and a
            return code of 200 informs Bancontact Payconiq 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
            Payconiq Company waits a response from the callback endpoint and an
            error code of 4xx or 5xx informs Bancontact Payconiq 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 Payconiq Company has a retry mechanism so in
            total Bancontact Payconiq 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 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.
      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).


            Bancontact Payconiq Company hosts the certificates in [JWK
            format](https://tools.ietf.org/html/rfc7517) at Bancontact Payconiq
            Company hosts the Public Key in JWK format as JWKS 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 and verify the certificate thumbprint
            present in x5t#S256 JOSE header against the downloaded certificate.


            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",
                  "sub" : "{merchantProfileId}",
                  "x5t#S256" : "[X.509 certificate SHA-256 thumbprint](https://tools.ietf.org/html/rfc7515#section-4.1.8).",
                  "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/iss", "https://payconiq.com/iat", "https://payconiq.com/jti", "https://payconiq.com/path"]
                }

            JWS 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 Payconiq 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 P2P or PAYMENT_REQUEST
            * `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`


        - 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
      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
  - url: https://merchant.api.bancontact.net
    description: PROD merchant API
components:
  securitySchemes:
    api_key_payment_profile:
      type: apiKey
      in: header
      description: >-
        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.
      name: Authorization
    JWS-Request-Signature-Payment:
      type: apiKey
      name: Signature
      in: header
      description: >-
        [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.
  schemas:
    get_payment_response:
      type: object
      title: GetPaymentResponse
      description: Response containing information on the requested payment.
      properties:
        paymentId:
          type: string
          description: id of the payment
          minLength: 24
          maxLength: 24
          examples:
            - 5f91483d-78a7-4914-bc6f=
        createdAt:
          type: string
          format: date-time
          description: the creation time of the payment
        expireAt:
          type: string
          format: date-time
          description: the time from which the payment will be expired
        succeededAt:
          type: string
          format: date-time
          description: >-
            if the payment is SUCCEEDED, then this field represents the
            date-time on which the payment was SUCCEEDED
        currency:
          $ref: '#/components/schemas/currency'
        status:
          $ref: '#/components/schemas/merchant-payment-status'
        creditor:
          $ref: '#/components/schemas/payment_creditor_response'
        debtor:
          type: object
          properties:
            name:
              type: string
              description: First name of Debtor
              examples:
                - John
            iban:
              type: string
              description: IBAN of Debtor masked
              examples:
                - '*************12636'
        amount:
          type: integer
          format: int64
          description: >-
            Amount in cents originally requested. If no amount was requested by
            creditor, this will be 0
        description:
          type: string
          description: merchant's description of the payment
          examples:
            - 5 coke.
        message:
          type: string
          description: debtor's message of the payment
          examples:
            - Money send.
        reference:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
            in the merchant's system
          examples:
            - '19848995'
        bulkId:
          type: string
          description: >-
            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.
          examples:
            - Bulk-1-200
        _links:
          $ref: '#/components/schemas/links'
      required:
        - paymentId
        - createdAt
        - expireAt
        - currency
        - status
        - creditor
        - amount
        - totalAmount
    payment_create_request:
      type: object
      title: PaymentCreateRequest
      description: Request to initiate/create a payment as a Merchant
      properties:
        reference:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
          maxLength: 35
          examples:
            - '19848995'
        bulkId:
          type: string
          maxLength: 35
          description: >-
            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.
          examples:
            - Bulk-1-200
        amount:
          type: integer
          description: Amount in cents requested
          format: int64
          minimum: 1
          exclusiveMinimum: 1
          maximum: 999999999999
        currency:
          $ref: '#/components/schemas/currency'
        description:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
          maxLength: 140
        identifyCallbackUrl:
          type: string
          description: >-
            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
          pattern: ^https:\/\/([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(:\d+)?(\/[^\s]*)?$
          examples:
            - https://api.merchant.bancontact.net/identify
        callbackUrl:
          type: string
          description: >-
            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
          pattern: ^https:\/\/([a-zA-Z0-9-:]+\.)+[a-zA-Z]{2,}(:\d+)?(\/[^\s]*)?$
          examples:
            - https://api.merchant.bancontact.net/payment
        returnUrl:
          type: string
          description: >-
            Merchant return url to which the dynamic payment page will redirect
            after the payment is completed
          minLength: 1
          maxLength: 2048
          pattern: ^https:\/\/([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(:\d+)?(\/[^\s]*)?$
          examples:
            - https://api.merchant.bancontact.net/payment
        voucherEligibility:
          deprecated: true
          type: array
          description: >-
            List of Value Added Services (vouchers) eligible amounts within the
            payment
          items:
            $ref: '#/components/schemas/VoucherEligibleAmount'
      required:
        - amount
    payment_create_response:
      type: object
      title: PaymentCreateResponse
      description: Object returned if the payment gets successfully created
      properties:
        paymentId:
          type: string
          description: Payment ID
          minLength: 24
          maxLength: 24
          examples:
            - 5f91483d-78a7-4914-bc6f=
        status:
          type: string
          enum:
            - PENDING
          description: the status of the payment created
        createdAt:
          type: string
          format: date-time
          description: the creation time of the payment
        expiresAt:
          type: string
          format: date-time
          description: the time from which the payment will be expired
        description:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
            Only first 35 characters will be used for the remittance info
        reference:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
          examples:
            - '19848995'
        amount:
          type: integer
          format: int64
          minimum: 1
          exclusiveMinimum: 1
          maximum: 999999999999
          description: Amount in cents requested
        currency:
          $ref: '#/components/schemas/currency'
        creditor:
          $ref: '#/components/schemas/payment_creditor_response'
        _links:
          $ref: '#/components/schemas/links'
      required:
        - paymentId
        - status
        - createdAt
        - expiresAt
        - amount
        - currency
        - creditor
        - _links
    merchant-acknowledge:
      type: object
      title: MerchantAcknowledge
      properties:
        currency:
          $ref: '#/components/schemas/currency'
        amount:
          $ref: '#/components/schemas/payment_amount'
        reference:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
          examples:
            - '19848995'
      required:
        - currency
        - amount
    merchant-callback:
      type: object
      title: MerchantCallback
      properties:
        paymentId:
          type: string
          description: PaycBancontact Payconiq Company Payment ID
          minLength: 24
          maxLength: 24
          examples:
            - 5f91483d-78a7-4914-bc6f=
        currency:
          type: string
          default: EUR
          description: Only EUR is supported currently
        amount:
          type: integer
          description: Requested amount in cents
          format: int64
        description:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
        reference:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
          examples:
            - '19848995'
        createdAt:
          type: string
          format: date-time
          description: When the payment was created
        expireAt:
          type: string
          format: date-time
          description: >-
            When the payment is going to expire. After that date the payment
            can't be confirmed anymore
        succeededAt:
          type: string
          format: date-time
          description: >-
            if the payment is SUCCEEDED, then this field represents the
            date-time on which the payment was SUCCEEDED
        status:
          $ref: '#/components/schemas/merchant-payment-status'
        debtor:
          type: object
          description: Customer that paid
          required:
            - iban
          properties:
            iban:
              type: string
              description: Debtor's IBAN masked
              examples:
                - '*************12636'
            name:
              type: string
              description: Debtor's first name
              examples:
                - John
      required:
        - paymentId
        - totalAmount
        - currency
        - amount
        - createdAt
        - status
        - debtor
    payment_stage:
      type: string
      title: PaymentStage
      enum:
        - AUTHORIZE
        - CAPTURE
        - COMPLETED
        - IDENTIFY
        - ACCEPT
        - NOTIFY
        - INITIALIZED
        - SOLVENCY
        - CANCEL
        - CREATE
        - CONFIRM
        - RISK_ACTIONS
      description: Payment stage
    payment_type:
      type: string
      title: PaymentType
      description: Payment type
      enum:
        - P2P
        - DIRECT_PAY
        - DYNAMIC
        - STATIC
        - TEMPLATE
        - UNKNOWN
        - SCAN_PAY
        - PAYMENT_REQUEST
    error:
      type: object
      description: error response received from server
      title: ErrorResponse
      properties:
        code:
          type: string
          description: ''
        message:
          type: string
          description: ''
        traceId:
          type: string
          description: id that is assigned to a single request, job, or action
        spanId:
          type: string
          description: id of the work unit where the error occured
      required:
        - code
        - message
        - traceId
        - spanId
    payment-search-query:
      type: object
      title: PaymentSearchQuery
      properties:
        from:
          type: string
          format: date-time
          description: default is today - 1day (yesterday)
        to:
          type: string
          format: date-time
        paymentStatuses:
          type: array
          items:
            $ref: '#/components/schemas/merchant-payment-status'
        reference:
          type: string
          description: >
            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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
          examples:
            - '19848995'
    PaymentSearchResponse:
      allOf:
        - $ref: '#/components/schemas/AbstractListResponsePayment'
        - type: object
          properties:
            details:
              type: array
              items:
                $ref: '#/components/schemas/get_payment_response'
    AbstractListResponsePayment:
      type: object
      properties:
        size:
          type: integer
          minimum: 0
          description: Size of the elements returned in current page
        totalPages:
          type: integer
          description: Total number of pages in the backend for the list requested
        totalElements:
          type: integer
          description: |
            Total number of elements in the list requested
        number:
          type: integer
          description: Current page number
      required:
        - size
        - totalPages
        - totalElements
        - number
    refund-response:
      type: object
      title: RefundResponse
      properties:
        iban:
          type: string
          description: Debtor's IBAN
          examples:
            - BE12 3456 7890 1234
      required:
        - iban
    merchant-payment-status:
      type: string
      title: MerchantPaymentStatus
      description: >
        | 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
    currency:
      type: string
      title: Currency
      description: >-
        Currency code. Only EUR is supported [ISO
        4217](http://en.wikipedia.org/wiki/ISO_4217)
      enum:
        - EUR
      default: EUR
    payment_creditor_response:
      type: object
      title: PaymentCreditorResponse
      description: Creditor account set to receive the payment
      properties:
        profileId:
          type: string
          description: The configuration ID of the Merchant
          examples:
            - 07e998f9-d932-4848-8b60-d5b5ae94b1b2
        merchantId:
          type: string
          description: the Id of the merchant
          examples:
            - dee718bb-3b6d-4312-9404-3d63d14529cc
        name:
          type: string
          description: Merchant's company name that will be shown to the debtor
          examples:
            - John
        iban:
          type: string
          description: >-
            Creditor's Bank Account Iban to where the money will be sent to for
            this current payment
          examples:
            - BE12 3456 7890 1234
        identifyCallbackUrl:
          type: string
          description: >-
            callbackUrl to which the merchant will be notified about the payment
            identification
          examples:
            - https://api.merchant.bancontact.net/identify
        callbackUrl:
          type: string
          description: >-
            callbackUrl to which the merchant will be notified about the payment
            payout
          examples:
            - https://api.merchant.bancontact.net/payment
    links:
      type: object
      title: Links
      description: >-
        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)
      properties:
        self:
          $ref: '#/components/schemas/link'
          examples:
            - https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f=
        deeplink:
          $ref: '#/components/schemas/link'
          examples:
            - https://payconiq.com/pay/2/5f91483d-78a7-4914-bc6f=
        qrcode:
          $ref: '#/components/schemas/link'
          examples:
            - >-
              https://qrcodegenerator.api.bancontact.net/qrcode?c=https%3A%2F%2Fpayconiq.com%2Fpay%2F2%2F5f91483d-78a7-4914-bc6f=
        cancel:
          $ref: '#/components/schemas/link'
          examples:
            - https://api.merchant.bancontact.net/5f91483d-78a7-4914-bc6f=
        refund:
          $ref: '#/components/schemas/link'
          examples:
            - >-
              https://merchant.api.bancontact.net/payments/5f91483d-78a7-4914-bc6f=/refunds
        checkout:
          $ref: '#/components/schemas/link'
          examples:
            - >-
              https://checkout.example.com?paymentId=12345&timestamp=1700000000000&token=abcdef1234567890
      required:
        - self
        - deeplink
        - qrcode
    link:
      type: object
      title: Link
      properties:
        href:
          type: string
      required:
        - href
    static_qr_payment_create_request:
      type: object
      title: StaticQRPaymentCreateRequest
      description: Request to initiate/create a static qr payment as a Merchant
      properties:
        reference:
          $ref: '#/components/schemas/payment_reference'
        bulkId:
          $ref: '#/components/schemas/bulkId'
        amount:
          type: integer
          description: Amount in cents requested
          format: int64
          minimum: 1
          exclusiveMinimum: 1
          maximum: 999999999999
        currency:
          $ref: '#/components/schemas/currency'
        description:
          $ref: '#/components/schemas/payment_description'
        posId:
          $ref: '#/components/schemas/posId'
        shopId:
          $ref: '#/components/schemas/shopId'
        shopName:
          type: string
          description: >-
            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.
          examples:
            - Bun café
          maxLength: 36
        identifyCallbackUrl:
          type: string
          description: >-
            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
          examples:
            - https://api.merchant.bancontact.net/identify
        callbackUrl:
          type: string
          description: >-
            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
          examples:
            - https://api.merchant.bancontact.net/payment
        voucherEligibility:
          deprecated: true
          type: array
          description: >-
            List of Value Added Services (vouchers) eligible amounts within the
            payment
          items:
            $ref: '#/components/schemas/VoucherEligibleAmount'
      required:
        - amount
        - posId
    payment_reference:
      type: string
      description: >-
        Partner payment reference, used to reference the Bancontact Payconiq
        Company payment in the partner's system
      maxLength: 35
      examples:
        - '19848995'
    bulkId:
      type: string
      maxLength: 35
      description: >-
        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.
      examples:
        - Bulk-1-200
    payment_description:
      type: string
      description: >
        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](https://www.europeanpaymentscouncil.eu/document-library/guidance-documents/sepa-requirements-extended-character-set-unicode-subset-best).
      maxLength: 140
    posId:
      type: string
      description: Merchant's point of sale identifier
      maxLength: 36
      pattern: ^[A-Za-z0-9]+$
      examples:
        - POS00001
    shopId:
      type: string
      description: Id of the shop, where payment is created
      maxLength: 36
      examples:
        - 3418e946-ef71-41ef-ad56-c41421c1e079
    payment_amount:
      type: integer
      format: int64
      minimum: 1
      exclusiveMinimum: 1
      maximum: 999999999999
      description: Amount in cents requested
    payment_id:
      type: string
      description: Payment ID
      minLength: 24
      maxLength: 24
      examples:
        - 5f91483d-78a7-4914-bc6f=
    merchantId:
      type: string
      description: the Id of the merchant
      examples:
        - 6ce074ed-d10d-403d-9267-f08c5257922c
    profileId:
      type: string
      description: The payment profile id of the merchant
      examples:
        - 8f4a3773-fb65-4f7f-b0fe-c30c6294f73c
    country:
      type: string
      description: >-
        The ISO Alpha-3 country code where the payment takes place. See
        https://www.iso.org/obp/ui/#search/code/.
      enum:
        - LUX
        - NLD
        - BEL
    VoucherEligibleAmount:
      type: object
      description: Defines an amount could be payed with proper voucher schemes
      required:
        - voucherSchemes
        - amount
      properties:
        voucherSchemes:
          type: array
          description: List of voucher schemes could be used to pay the amount
          minItems: 1
          items:
            $ref: '#/components/schemas/VoucherScheme'
        amount:
          type: integer
          description: >-
            Amount in cents eligible for payment with voucher. EUR 10.13 will be
            1013
          format: int64
          minimum: 1
          exclusiveMinimum: 1
          maximum: 999999999999
          examples:
            - 1013
    VoucherAmount:
      type: object
      description: Defines an amount that was payed with voucher scheme
      required:
        - voucherProvider
        - voucherScheme
        - amount
      properties:
        voucherProvider:
          $ref: '#/components/schemas/VoucherProvider'
        voucherScheme:
          $ref: '#/components/schemas/VoucherScheme'
        amount:
          type: integer
          description: Amount in cents was that payed with voucher. EUR 10.13 will be 1013
          format: int64
          minimum: 1
          exclusiveMinimum: 1
          maximum: 999999999999
          examples:
            - 1013
    VoucherProvider:
      type: string
      description: >
        Provider of the Value Added Service (vouchers), has the form
        [alpha-3-country-code]_[identifier]

        currently known values:
          - BEL_MONIZZE
          - BEL_SODEXO
          - BEL_EDENRED
      examples:
        - BEL_MONIZZE
      minLength: 1
      maxLength: 36
      pattern: ^[A-Z]{3}_[A-Z_]+$
    VoucherScheme:
      type: string
      description: >
        Voucher scheme (voucher type), has the form
        [alpha-3-country-code]_[identifier]

        currently known values:
          - BEL_MEAL_VOUCHER
          - BEL_ECO_VOUCHER
          - BEL_GIFT_VOUCHER
          - BEL_COVID_VOUCHER
          - BEL_SPORT_VOUCHER
          - BEL_CONSUMPTION_VOUCHER

        The api should allow for new schemes, providers and categories without
        having to upgrade all the services/apps

        using this API. Because most services will use the java api artifact for
        this (which will 'close' any enums

        defined in an openapi spec), the values above are not encoded explicitly
        as enums.

        The 400 error response will report any invalid values for the scheme and
        providers.
      examples:
        - BEL_MEAL_VOUCHER
      minLength: 1
      maxLength: 36
      pattern: ^[A-Z]{3}_[A-Z_]+$
