openapi: 3.2.0
info:
  title: Payment V3 Merchant Acknowledge API
  version: 3.6.5
  description: APIs intended to support the merchant/partner's payment flow on creation, cancellation, search and refunds.
servers:
- url: https://merchant.api.preprod.bancontact.net
  description: PREPROD merchant API
- url: https://merchant.api.bancontact.net
  description: PROD merchant API
security:
- api_key_payment_profile: []
tags:
- name: Merchant Acknowledge
paths:
  /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'
components:
  schemas:
    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 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
    payment_amount:
      type: integer
      format: int64
      minimum: 1
      exclusiveMinimum: 1
      maximum: 999999999999
      description: Amount in cents requested
    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
    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
  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).\n\nBancontact  Company hosts the certificates in [JWK format](https://tools.ietf.org/html/rfc7517) as [JWKS](https://tools.ietf.org/html/rfc7517#appendix-B) at :\n- https://jwks.bancontact.net/\n- https://jwks.preprod.bancontact.net/\nfor PROD and PREPROD environments respectively.\n\nThe merchant system should download the certificate in JWK format from the URL specified above.\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      \"https://payconiq.com/sub\" : \"{merchantProfileId}\",\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/sub\", \"https://payconiq.com/iss\", \"https://payconiq.com/iat\", \"https://payconiq.com/jti\", \"https://payconiq.com/path\"]\n    }\n\nJWS Payload MUST be the same as response body as base64url encoded JSON data."