openapi: 3.2.0
info:
  title: Payment V3 Refunds 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: Refunds
paths:
  /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
components:
  schemas:
    refund-response:
      type: object
      title: RefundResponse
      properties:
        iban:
          type: string
          description: Debtor's IBAN
          examples:
          - BE12 3456 7890 1234
      required:
      - iban
    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."