Bancontact Callback to Merchants API

openapi: 3.2.0
info:
  title: Payment V3 Callback to Merchants 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: Callback to Merchants
paths:
  /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: []
components:
  schemas:
    merchant-callback:
      type: object
      title: MerchantCallback
      properties:
        paymentId:
          type: string
          description: Bancontact 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 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
    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 Bancontact Pay. |

        | 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
  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."