openapi: 3.1.0
info:
  description: |-
    This specification describes the HTTP POST requests that Bank Frick
    will send to customer-configured webhook URLs.

    Customers should implement an HTTPS endpoint that accepts the WebhookPayload structure.
    The webhook URL is configured per notification rule and can be any HTTPS endpoint.
  title: Bank Frick Webhook Contract
  version: 1.5.0
servers:
- description: Example webhook endpoint (replace with your actual endpoint)
  url: https://example.com/api/webhooks/bankfrick
paths: {}
components:
  schemas:
    AccountDto:
      type: object
      description: Account details
      properties:
        Id:
          $ref: "#/components/schemas/AccountIdDto"
          description: Account identification
      required:
      - Id
    AccountIdDto:
      type: object
      description: Account identification
      properties:
        IBAN:
          type: string
          description: Account ID (IBAN). Max 34 characters as per pain.008. ISO-8859-1
            character set
          example: LI0000000000000000000
      required:
      - IBAN
    AgentDto:
      type: object
      description: Agent (bank) information
      properties:
        FinancialInstitution:
          $ref: "#/components/schemas/FinancialInstitutionDto"
          description: Financial institution details
      required:
      - FinancialInstitution
    CreditorReferenceInformationDto:
      type: object
      properties:
        CodeOrIssuer:
          type: string
          description: "Creditor reference type code (1-4 characters), or name of\
            \ the proprietary issuer. Max 35 characters as per pain.008. ISO-8859-1\
            \ character set"
          example: CODE
        Reference:
          type: string
          description: Creditor reference information. Max 35 characters as per pain.008.
            ISO-8859-1 character set
          example: ABC 123 DEF 456
    CustomerDto:
      type: object
      description: Bank Frick Customer information
      properties:
        Name:
          type: string
          description: Name of the customer
          example: ACME Inc.
        Number:
          type: string
          description: Bank Frick customer number
          example: "0123456"
      required:
      - Name
      - Number
    EventTypeDto:
      type: string
      description: |-
        Type of event that triggered the notification:
          - INSTANT_TRANSACTION_RECEIVED: Event triggered when an instant transaction is received
          - INSTANT_TRANSACTION_EXECUTED: Event triggered when an outgoing instant transaction is successfully executed
          - INSTANT_TRANSACTION_REJECTED: Event triggered when an outgoing instant transaction is rejected
      enum:
      - INSTANT_TRANSACTION_RECEIVED
      - INSTANT_TRANSACTION_EXECUTED
      - INSTANT_TRANSACTION_REJECTED
    FinancialInstitutionDto:
      type: object
      description: Financial institution information
      properties:
        BIC:
          type: string
          description: "BIC code. 8 or 11 characters as per pain.008 (format: 6 letters\
            \ + 2 alphanumeric + optional 3 alphanumeric). ISO-8859-1 character set"
          example: EXMPLI22XXX
        Name:
          type: string
          description: Name of the financial institution. Max 140 characters as per
            pain.008. ISO-8859-1 character set
          example: Example Bank AG
      required:
      - BIC
    PartyDto:
      type: object
      description: Party information (creditor or debtor)
      properties:
        Name:
          type: string
          description: Name of the party. Max 70 characters as per pain.008. ISO-8859-1
            character set
          example: Jane Doe
        PostalAddress:
          $ref: "#/components/schemas/PostalAddressDto"
          description: Postal address of the party
      required:
      - Name
      - PostalAddress
    PaymentIdentificationDto:
      type: object
      description: Payment identification
      properties:
        EndToEndId:
          type: string
          description: End-to-End Identification of the Payment
          example: NOTPROVIDED
        InstrId:
          type: string
          description: Instruction Identification - point-to-point reference
          example: INSTR123456
        TxId:
          type: string
          description: Transaction Identification - unique identification assigned
            by the first instructing agent
          example: TXN987654321
        UETR:
          type: string
          description: Unique End-to-End Transaction Reference - universally unique
            identifier (UUIDv4)
          example: e3bf5f77-30aa-40fc-83d7-72bc9067aa9b
      required:
      - EndToEndId
    PostalAddressDto:
      type: object
      description: Postal address information
      properties:
        AddressLine:
          type: array
          description: "Unstructured address lines. Max 7 lines as per pain.008, each\
            \ line max 70 characters. ISO-8859-1 character set"
          example:
          - Commerce Avenue 42
          - Floor 3
          items:
            type: string
        BuildingNumber:
          type: string
          description: Building number. Max 16 characters as per pain.008. ISO-8859-1
            character set
          example: "42"
        Country:
          type: string
          description: "Country code. ISO 3166-1 alpha-2, 2 uppercase letters"
          example: LU
        CountrySubDivision:
          type: string
          description: Country subdivision. Max 35 characters as per pain.008. ISO-8859-1
            character set
          example: Sample District
        Department:
          type: string
          description: Department. Max 70 characters as per pain.008. ISO-8859-1 character
            set
          example: Accounting Department
        DistrictName:
          type: string
          description: District name. Max 35 characters as per pain.008. ISO-8859-1
            character set
          example: City Center
        PostalCode:
          type: string
          description: Postal code. Max 16 characters as per pain.008. ISO-8859-1
            character set
          example: L-1234
        Postbox:
          type: string
          description: Post box. Max 16 characters as per pain.008. ISO-8859-1 character
            set
          example: PO Box 100
        Room:
          type: string
          description: Room. Max 70 characters as per pain.008. ISO-8859-1 character
            set
          example: Room 101
        StreetName:
          type: string
          description: Street name. Max 70 characters as per pain.008. ISO-8859-1
            character set
          example: Commerce Avenue
        SubDepartment:
          type: string
          description: Sub-department. Max 70 characters as per pain.008. ISO-8859-1
            character set
          example: Payment Operations
        TownLocationName:
          type: string
          description: Town location name. Max 35 characters as per pain.008. ISO-8859-1
            character set
          example: Business District
        TownName:
          type: string
          description: Town name. Max 35 characters as per pain.008. ISO-8859-1 character
            set
          example: Sample Town
    ProblemDetail:
      type: object
      properties:
        detail:
          type: string
        instance:
          type: string
          format: uri
        properties:
          type: object
          additionalProperties: {}
        status:
          type: integer
          format: int32
        title:
          type: string
        type:
          type: string
          format: uri
    RemittanceInformationDto:
      type: object
      description: Remittance information
      properties:
        StructuredReference:
          type: array
          description: Structured remittance information
          items:
            $ref: "#/components/schemas/StructuredRemittanceInformationDto"
        UnstructuredReference:
          type: array
          description: Unstructured remittance references. Each element max 140 characters
            as per pain.008. ISO-8859-1 character set
          example:
          - INV-2025-0001
          - Payment for services
          items:
            type: string
    StructuredRemittanceInformationDto:
      type: object
      properties:
        CreditorReferenceInformation:
          $ref: "#/components/schemas/CreditorReferenceInformationDto"
          description: Creditor reference information
    TransactionAmountDto:
      type: object
      description: Transaction amount
      properties:
        Amount:
          type: number
          description: Amount value. Should be positive as per pain.008
          example: 100.0
        Currency:
          type: string
          description: Currency code. 3-letter ISO 4217 code
          example: EUR
      required:
      - Amount
      - Currency
    WebhookPayloadBookedDto:
      allOf:
      - $ref: "#/components/schemas/WebhookPayloadDto"
      - type: object
        properties:
          AcceptanceDateTime:
            type: string
            description: Acceptance date and time
            example: 2025-11-18T15:41:46.141Z
          SettlementDate:
            type: string
            description: Date of settlement
            example: 2025-12-18Z
          TransactionNumber:
            type: string
            description: "Transaction number for filtering booked transactions via\
              \ the API, see https://developers.bankfrick.li/api_docs/#transactions-get"
            example: "87654321"
      description: Webhook payload for accepted and booked transactions
      required:
      - AcceptanceDateTime
      - Creditor
      - CreditorAccount
      - CreditorAgent
      - Customer
      - DebtorAccount
      - DebtorAgent
      - EventType
      - PaymentIdentification
      - RemittanceInformation
      - TransactionAmount
      - TransactionNumber
      - UniqueEventId
    WebhookPayloadDto:
      type: object
      description: Webhook notification payload with ISO 20022 transaction data
      discriminator:
        mapping:
          INSTANT_TRANSACTION_EXECUTED: "#/components/schemas/WebhookPayloadBookedDto"
          INSTANT_TRANSACTION_RECEIVED: "#/components/schemas/WebhookPayloadBookedDto"
          INSTANT_TRANSACTION_REJECTED: "#/components/schemas/WebhookPayloadRejectedDto"
        propertyName: EventType
      oneOf:
      - $ref: "#/components/schemas/WebhookPayloadBookedDto"
      - $ref: "#/components/schemas/WebhookPayloadRejectedDto"
      properties:
        Creditor:
          $ref: "#/components/schemas/PartyDto"
          description: Creditor party information
        CreditorAccount:
          $ref: "#/components/schemas/AccountDto"
          description: Creditor account details
        CreditorAgent:
          $ref: "#/components/schemas/AgentDto"
          description: Creditor agent (bank) information
        Customer:
          $ref: "#/components/schemas/CustomerDto"
          description: Bank Frick customer information
        Debtor:
          $ref: "#/components/schemas/PartyDto"
          description: Debtor party information
        DebtorAccount:
          $ref: "#/components/schemas/AccountDto"
          description: Debtor account details
        DebtorAgent:
          $ref: "#/components/schemas/AgentDto"
          description: Debtor agent (bank) information
        EventType:
          $ref: "#/components/schemas/EventTypeDto"
          description: Type of event that triggered the notification
        PaymentIdentification:
          $ref: "#/components/schemas/PaymentIdentificationDto"
          description: Payment identification
        RemittanceInformation:
          $ref: "#/components/schemas/RemittanceInformationDto"
          description: Remittance information
        TransactionAmount:
          $ref: "#/components/schemas/TransactionAmountDto"
          description: Transaction amount and currency
        UniqueEventId:
          type: string
          description: "Unique ID of event, can be used for deduplication of messages"
          example: cb23c1b7-9fbf-4c95-b9a2-bbdbeda05a00
      required:
      - Creditor
      - CreditorAccount
      - CreditorAgent
      - Customer
      - DebtorAccount
      - DebtorAgent
      - EventType
      - PaymentIdentification
      - RemittanceInformation
      - TransactionAmount
      - UniqueEventId
    WebhookPayloadRejectedDto:
      allOf:
      - $ref: "#/components/schemas/WebhookPayloadDto"
      - type: object
        properties:
          RejectionDateTime:
            type: string
            description: Rejection date and time
            example: 2025-11-18T15:41:46.141Z
          RejectionReason:
            type: string
            description: Reason for transaction rejection
            example: Insufficient funds
      description: Webhook payload for rejected transactions
      required:
      - Creditor
      - CreditorAccount
      - CreditorAgent
      - Customer
      - DebtorAccount
      - DebtorAgent
      - EventType
      - PaymentIdentification
      - RejectionDateTime
      - RemittanceInformation
      - TransactionAmount
      - UniqueEventId
webhooks:
  notificationWebhook:
    post:
      description: |-
        Bank Frick will POST webhook notifications to the URL you configure in your notification rule.

        You can configure any HTTPS endpoint URL. The path is entirely up to you.

        Example URLs:
        - https://your-domain.com/api/webhooks/bankfrick
        - https://your-domain.com/notifications
        - https://api.your-service.com/v1/incoming-webhooks
      parameters:
      - description: Signature algorithm used to sign the webhook payload
        in: header
        name: Algorithm
        required: true
        schema:
          type: string
          enum:
          - rsa-sha512
          example: rsa-sha512
      - description: Base64-encoded RSA signature of the webhook payload. Verify using
          the public key to ensure the webhook came from Bank Frick
        in: header
        name: Signature
        required: true
        schema:
          type: string
          example: MEUCIQDf...truncated...
      requestBody:
        content:
          application/json:
            examples:
              instant_payment_executed:
                description: An outgoing instant payment (pacs.008) that has been
                  accepted and was successfully booked.
                summary: Instant payment executed
                value:
                  AcceptanceDateTime: 2025-11-18T15:41:46.141Z
                  Creditor:
                    Name: Jane Doe
                    PostalAddress:
                      BuildingNumber: "42"
                      Country: LU
                      CountrySubDivision: Sample District
                      Department: Accounting Department
                      DistrictName: City Center
                      PostalCode: L-1234
                      Postbox: PO Box 200
                      Room: Room 101
                      StreetName: Commerce Avenue
                      SubDepartment: Payment Operations
                      TownLocationName: Business District
                      TownName: Sample Town
                  CreditorAccount:
                    Id:
                      IBAN: LI11188110101101K001E
                  CreditorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                      Name: Bank Frick AG
                  Customer:
                    Name: ACME Inc.
                    Number: "0123456"
                  Debtor:
                    Name: Example Bank AG
                    PostalAddress:
                      BuildingNumber: "123"
                      Country: LI
                      CountrySubDivision: Example District
                      Department: Treasury
                      DistrictName: Central District
                      PostalCode: "9490"
                      Postbox: PO Box 100
                      Room: Floor 5
                      StreetName: Main Street
                      SubDepartment: Payment Processing
                      TownLocationName: Business District
                      TownName: Example City
                  DebtorAccount:
                    Id:
                      IBAN: LI6808811000000001234
                  DebtorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                      Name: Bank Frick AG
                  EventType: INSTANT_TRANSACTION_EXECUTED
                  PaymentIdentification:
                    EndToEndId: E2E-2025-INV-0001
                  RemittanceInformation:
                    UnstructuredReference:
                    - INV-2025-0001
                  SettlementDate: 2025-11-19Z
                  TransactionAmount:
                    Amount: 100.0
                    Currency: EUR
                  TransactionNumber: "87654321"
                  UniqueEventId: cb23c1b7-9fbf-4c95-b9a2-bbdbeda05a00
              instant_payment_received_address_lines:
                description: An incoming instant payment (pacs.008) where the debtor's
                  postal address is provided using free-form address lines (AdrLine)
                  rather than structured fields. This format is common when the originating
                  bank does not support structured addresses.
                summary: Instant payment received with unstructured address lines
                  in postal address
                value:
                  AcceptanceDateTime: 2025-11-18T15:41:46.141Z
                  Creditor:
                    Name: Example Bank AG
                    PostalAddress:
                      AddressLine:
                      - Main Street 123
                      - Floor 5
                      - Building A
                      - Finance Division
                      - Payment Processing
                      - PO Box 100
                      - "Example City, LI 9490"
                      Country: LI
                      TownName: Example City
                  CreditorAccount:
                    Id:
                      IBAN: LI6808811000000001234
                  CreditorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                  Customer:
                    Name: ACME Inc.
                    Number: "0123456"
                  Debtor:
                    Name: Jane Doe
                    PostalAddress:
                      AddressLine:
                      - Commerce Avenue 42
                      - Room 101
                      - Accounting Department
                      - Payment Operations
                      - Business District
                      - PO Box 200
                      - "Sample Town, LU L-1234"
                      Country: LU
                      TownName: Sample Town
                  DebtorAccount:
                    Id:
                      IBAN: LI11188110101101K001E
                  DebtorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                  EventType: INSTANT_TRANSACTION_RECEIVED
                  PaymentIdentification:
                    EndToEndId: E2E-2025-INV-0001
                  RemittanceInformation:
                    UnstructuredReference:
                    - INV-2025-0001
                  TransactionAmount:
                    Amount: 100.0
                    Currency: EUR
                  TransactionNumber: "87654321"
                  UniqueEventId: a1b2c3d4-5678-90ab-cdef-1234567890ab
              instant_payment_received_structured_address:
                description: "An incoming instant payment (pacs.008) where the debtor's\
                  \ postal address is provided using structured fields such as street\
                  \ name, building number, postal code, town, and country. This format\
                  \ provides better data quality for address validation and processing."
                summary: Instant payment received with structured address fields in
                  postal address
                value:
                  AcceptanceDateTime: 2025-11-18T15:41:46.141Z
                  Creditor:
                    Name: Example Bank AG
                    PostalAddress:
                      BuildingNumber: "123"
                      Country: LI
                      CountrySubDivision: Example District
                      Department: Treasury
                      DistrictName: Central District
                      PostalCode: "9490"
                      Postbox: PO Box 100
                      Room: Floor 5
                      StreetName: Main Street
                      SubDepartment: Payment Processing
                      TownLocationName: Business District
                      TownName: Example City
                  CreditorAccount:
                    Id:
                      IBAN: LI6808811000000001234
                  CreditorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                      Name: Bank Frick AG
                  Customer:
                    Name: ACME Inc.
                    Number: "0123456"
                  Debtor:
                    Name: Jane Doe
                    PostalAddress:
                      BuildingNumber: "42"
                      Country: LU
                      CountrySubDivision: Sample District
                      Department: Accounting Department
                      DistrictName: City Center
                      PostalCode: L-1234
                      Postbox: PO Box 200
                      Room: Room 101
                      StreetName: Commerce Avenue
                      SubDepartment: Payment Operations
                      TownLocationName: Business District
                      TownName: Sample Town
                  DebtorAccount:
                    Id:
                      IBAN: LI11188110101101K001E
                  DebtorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                      Name: Bank Frick AG
                  EventType: INSTANT_TRANSACTION_RECEIVED
                  PaymentIdentification:
                    EndToEndId: E2E-2025-INV-0001
                  RemittanceInformation:
                    UnstructuredReference:
                    - INV-2025-0001
                  SettlementDate: 2025-11-19Z
                  TransactionAmount:
                    Amount: 100.0
                    Currency: EUR
                  TransactionNumber: "87654321"
                  UniqueEventId: b2c3d4e5-6789-01ab-cdef-2345678901ab
              instant_payment_received_structured_remittance_information:
                description: "An incoming instant payment (pacs.008) containing structured\
                  \ remittance information with creditor reference (e.g., ISO 11649\
                  \ RF creditor reference). Useful for automated reconciliation and\
                  \ invoice matching."
                summary: Instant payment received with structured remittance information
                value:
                  AcceptanceDateTime: 2025-11-18T15:41:46.141Z
                  Creditor:
                    Name: Example Bank AG
                    PostalAddress:
                      AddressLine:
                      - Main Street 123
                      - Floor 5
                      - Building A
                      - Finance Division
                      - Payment Processing
                      - PO Box 100
                      - "Example City, LI 9490"
                      Country: LI
                      TownName: Example City
                  CreditorAccount:
                    Id:
                      IBAN: LI6808811000000001234
                  CreditorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                      Name: Bank Frick AG
                  Customer:
                    Name: ACME Inc.
                    Number: "0123456"
                  Debtor:
                    Name: Jane Doe
                    PostalAddress:
                      AddressLine:
                      - Commerce Avenue 42
                      - Room 101
                      - Accounting Department
                      - Payment Operations
                      - Business District
                      - PO Box 200
                      - "Sample Town, LU L-1234"
                      Country: LU
                      TownName: Sample Town
                  DebtorAccount:
                    Id:
                      IBAN: LI11188110101101K001E
                  DebtorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                      Name: Bank Frick AG
                  EventType: INSTANT_TRANSACTION_RECEIVED
                  PaymentIdentification:
                    EndToEndId: E2E-2025-INV-0001
                  RemittanceInformation:
                    StructuredReference:
                    - CreditorReferenceInformation:
                        CodeOrIssuer: ABCD
                        Reference: INV-2025-0001
                  SettlementDate: 2025-11-19Z
                  TransactionAmount:
                    Amount: 100.0
                    Currency: EUR
                  TransactionNumber: "87654321"
                  UniqueEventId: c3d4e5f6-7890-12ab-cdef-3456789012ab
              instant_payment_rejected:
                description: An outgoing instant payment (pacs.008) that has been
                  rejected.
                summary: Instant payment rejected
                value:
                  Creditor:
                    Name: Example Bank AG
                    PostalAddress:
                      AddressLine:
                      - Main Street 123
                      - Floor 5
                      - Building A
                      - Finance Division
                      - Payment Processing
                      - PO Box 100
                      - "Example City, LI 9490"
                      Country: LI
                      TownName: Example City
                  CreditorAccount:
                    Id:
                      IBAN: LI6808811000000001234
                  CreditorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                  Customer:
                    Name: ACME Inc.
                    Number: "0123456"
                  Debtor:
                    Name: Jane Doe
                    PostalAddress:
                      AddressLine:
                      - Commerce Avenue 42
                      - Room 101
                      - Accounting Department
                      - Payment Operations
                      - Business District
                      - PO Box 200
                      - "Sample Town, LU L-1234"
                      Country: LU
                      TownName: Sample Town
                  DebtorAccount:
                    Id:
                      IBAN: LI11188110101101K001E
                  DebtorAgent:
                    FinancialInstitution:
                      BIC: BFRILI22XXX
                  EventType: INSTANT_TRANSACTION_REJECTED
                  PaymentIdentification:
                    EndToEndId: E2E-2025-INV-0001
                  RejectionDateTime: 2025-11-18T15:41:46.141Z
                  RejectionReason: Insufficient funds
                  RemittanceInformation:
                    UnstructuredReference:
                    - INV-2025-0001
                  TransactionAmount:
                    Amount: 100.0
                    Currency: EUR
                  UniqueEventId: cb23c1b7-9fbf-4c95-b9a2-bbdbeda05a00
            schema:
              $ref: "#/components/schemas/WebhookPayloadDto"
        description: Webhook notification payload
        required: true
      responses:
        "204":
          description: Webhook received and accepted for processing
        "408":
          content:
            application/problem+json:
              examples:
                timeout:
                  description: timeout
                  value:
                    type: about:blank
                    title: Request Timeout
                    status: 408
                    detail: The request timed out
                    instance: /api/webhooks
              schema:
                $ref: "#/components/schemas/ProblemDetail"
          description: Request Timeout - webhook will be retried
        "429":
          content:
            application/problem+json:
              examples:
                too_many_requests:
                  description: too_many_requests
                  value:
                    type: about:blank
                    title: Too Many Requests
                    status: 429
                    detail: Too many requests have been received
                    instance: /api/webhooks
              schema:
                $ref: "#/components/schemas/ProblemDetail"
          description: Too Many Requests - webhook will be retried
        "500":
          content:
            application/problem+json:
              examples:
                internal_server_error:
                  description: internal_server_error
                  value:
                    type: about:blank
                    title: Internal Server Error
                    status: 500
                    detail: An unexpected error occurred while processing your request
                    instance: /api/webhooks
              schema:
                $ref: "#/components/schemas/ProblemDetail"
          description: Internal Server Error - webhook will be retried
        "502":
          content:
            application/problem+json:
              examples:
                bad_gateway:
                  description: bad_gateway
                  value:
                    type: about:blank
                    title: Bad Gateway
                    status: 502
                    detail: Bad gateway error occurred
                    instance: /api/webhooks
              schema:
                $ref: "#/components/schemas/ProblemDetail"
          description: Bad Gateway - webhook will be retried
        "503":
          content:
            application/problem+json:
              examples:
                service_unavailable:
                  description: service_unavailable
                  value:
                    type: about:blank
                    title: Service Unavailable
                    status: 503
                    detail: The service is temporarily unavailable
                    instance: /api/webhooks
              schema:
                $ref: "#/components/schemas/ProblemDetail"
          description: Service Unavailable - webhook will be retried
        "504":
          content:
            application/problem+json:
              examples:
                gateway_timeout:
                  description: gateway_timeout
                  value:
                    type: about:blank
                    title: Gateway Timeout
                    status: 504
                    detail: Gateway timeout occurred
                    instance: /api/webhooks
              schema:
                $ref: "#/components/schemas/ProblemDetail"
          description: Gateway Timeout - webhook will be retried
      summary: Webhook notification