{
  "openapi": "3.1.0",
  "info": {
    "title": "Bank Frick Webhook Contract",
    "description": "This specification describes the HTTP POST requests that Bank Frick\nwill send to customer-configured webhook URLs.\n\nCustomers should implement an HTTPS endpoint that accepts the WebhookPayload structure.\nThe webhook URL is configured per notification rule and can be any HTTPS endpoint.",
    "version": "1.2.0"
  },
  "servers": [
    {
      "url": "https://example.com/api/webhooks/bankfrick",
      "description": "Example webhook endpoint (replace with your actual endpoint)"
    }
  ],
  "paths": {},
  "components": {
    "schemas": {
      "AccountDto": {
        "type": "object",
        "description": "Account details",
        "properties": {
          "Id": {
            "$ref": "#/components/schemas/AccountIdDto",
            "description": "Account identification"
          }
        }
      },
      "AccountIdDto": {
        "type": "object",
        "description": "Account identification",
        "properties": {
          "IBAN": {
            "type": "string",
            "description": "Account ID (IBAN). Max 34 characters per Pain.008. ISO-8859-1 character set",
            "example": "LI0000000000000000000"
          }
        }
      },
      "AgentDto": {
        "type": "object",
        "description": "Agent (bank) information",
        "properties": {
          "FinancialInstitution": {
            "$ref": "#/components/schemas/FinancialInstitutionDto",
            "description": "Financial institution details"
          }
        }
      },
      "CreditorReferenceInformationDto": {
        "type": "object",
        "properties": {
          "Reference": {
            "type": "string",
            "description": "Creditor reference information. Max 35 characters per Pain.008. ISO-8859-1 character set",
            "example": "ABC 123 DEF 456"
          },
          "CodeOrIssuer": {
            "type": "string",
            "description": "Creditor reference type code (1-4 characters), or name of the proprietary issuer. Max 35 characters per Pain.008. ISO-8859-1 character set",
            "example": "CODE"
          }
        }
      },
      "CustomerDto": {
        "type": "object",
        "description": "Bank Frick Customer information",
        "properties": {
          "Number": {
            "type": "string",
            "description": "Bank Frick customer number",
            "example": "0123456"
          },
          "Name": {
            "type": "string",
            "description": "Name of the customer",
            "example": "ACME Inc."
          }
        }
      },
      "EventTypeDto": {
        "type": "string",
        "description": "Type of event that triggered the notification:\n  - INSTANT_TRANSACTION_RECEIVED: Event triggered when an instant transaction is received\n  - INSTANT_TRANSACTION_EXECUTED: Event triggered when an outgoing instant transaction is successfully executed",
        "enum": [
          "INSTANT_TRANSACTION_RECEIVED",
          "INSTANT_TRANSACTION_EXECUTED"
        ]
      },
      "FinancialInstitutionDto": {
        "type": "object",
        "description": "Financial institution information",
        "properties": {
          "BIC": {
            "type": "string",
            "description": "BIC code. 8 or 11 characters 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 per Pain.008. ISO-8859-1 character set",
            "example": "Example Bank AG"
          }
        }
      },
      "PartyDto": {
        "type": "object",
        "description": "Party information (creditor or debtor)",
        "properties": {
          "Name": {
            "type": "string",
            "description": "Name of the party. Max 70 characters per Pain.008. ISO-8859-1 character set",
            "example": "Jane Doe"
          },
          "PostalAddress": {
            "$ref": "#/components/schemas/PostalAddressDto",
            "description": "Postal address of the party"
          }
        }
      },
      "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"
          }
        }
      },
      "PostalAddressDto": {
        "type": "object",
        "description": "Postal address information",
        "properties": {
          "BuildingNumber": {
            "type": "string",
            "description": "Building number. Max 16 characters 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 per Pain.008. ISO-8859-1 character set",
            "example": "Sample District"
          },
          "Department": {
            "type": "string",
            "description": "Department. Max 70 characters per Pain.008. ISO-8859-1 character set",
            "example": "Accounting Department"
          },
          "DistrictName": {
            "type": "string",
            "description": "District name. Max 35 characters per Pain.008. ISO-8859-1 character set",
            "example": "City Center"
          },
          "Postbox": {
            "type": "string",
            "description": "Post box. Max 16 characters per Pain.008. ISO-8859-1 character set",
            "example": "PO Box 100"
          },
          "PostalCode": {
            "type": "string",
            "description": "Postal code. Max 16 characters per Pain.008. ISO-8859-1 character set",
            "example": "L-1234"
          },
          "Room": {
            "type": "string",
            "description": "Room. Max 70 characters per Pain.008. ISO-8859-1 character set",
            "example": "Room 101"
          },
          "StreetName": {
            "type": "string",
            "description": "Street name. Max 70 characters per Pain.008. ISO-8859-1 character set",
            "example": "Commerce Avenue"
          },
          "SubDepartment": {
            "type": "string",
            "description": "Sub-department. Max 70 characters per Pain.008. ISO-8859-1 character set",
            "example": "Payment Operations"
          },
          "TownLocationName": {
            "type": "string",
            "description": "Town location name. Max 35 characters per Pain.008. ISO-8859-1 character set",
            "example": "Business District"
          },
          "TownName": {
            "type": "string",
            "description": "Town name. Max 35 characters per Pain.008. ISO-8859-1 character set",
            "example": "Sample Town"
          },
          "AddressLine": {
            "type": "array",
            "description": "Unstructured address lines. Max 7 lines per Pain.008, each line max 70 characters. ISO-8859-1 character set",
            "example": [
              "Commerce Avenue 42",
              "Floor 3"
            ],
            "items": {
              "type": "string"
            }
          }
        }
      },
      "RemittanceInformationDto": {
        "type": "object",
        "description": "Remittance information",
        "properties": {
          "UnstructuredReference": {
            "type": "array",
            "description": "Unstructured remittance references. Each element max 140 characters per Pain.008. ISO-8859-1 character set",
            "example": [
              "INV-2025-0001",
              "Payment for services"
            ],
            "items": {
              "type": "string"
            }
          },
          "StructuredReference": {
            "type": "array",
            "description": "Structured remittance information",
            "items": {
              "$ref": "#/components/schemas/StructuredRemittanceInformationDto"
            }
          }
        }
      },
      "StructuredRemittanceInformationDto": {
        "type": "object",
        "properties": {
          "CreditorReferenceInformation": {
            "$ref": "#/components/schemas/CreditorReferenceInformationDto",
            "description": "Creditor reference information"
          }
        }
      },
      "TransactionAmountDto": {
        "type": "object",
        "description": "Transaction amount",
        "properties": {
          "Currency": {
            "type": "string",
            "description": "Currency code. 3-letter ISO 4217 code",
            "example": "EUR"
          },
          "Amount": {
            "type": "string",
            "description": "Amount value. Should be positive per Pain.008",
            "example": 100.0
          }
        }
      },
      "WebhookPayloadDto": {
        "type": "object",
        "description": "Webhook notification payload with ISO 20022 transaction data",
        "properties": {
          "AcceptanceDateTime": {
            "type": "string",
            "description": "Acceptance date and time",
            "example": "2025-11-18T15:41:46.141Z"
          },
          "UniqueEventId": {
            "type": "string",
            "description": "Unique ID of event, can be used for deduplication of messages",
            "example": "cb23c1b7-9fbf-4c95-b9a2-bbdbeda05a00"
          },
          "EventType": {
            "$ref": "#/components/schemas/EventTypeDto",
            "description": "Type of event that triggered the notification"
          },
          "Customer": {
            "$ref": "#/components/schemas/CustomerDto",
            "description": "Bank Frick customer information"
          },
          "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"
          },
          "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"
          },
          "TransactionAmount": {
            "$ref": "#/components/schemas/TransactionAmountDto",
            "description": "Transaction amount and currency"
          },
          "SettlementDate": {
            "type": "string",
            "description": "Date of settlement",
            "example": "2025-12-18Z"
          },
          "PaymentIdentification": {
            "$ref": "#/components/schemas/PaymentIdentificationDto",
            "description": "Payment identification"
          },
          "RemittanceInformation": {
            "$ref": "#/components/schemas/RemittanceInformationDto",
            "description": "Remittance information"
          }
        }
      },
      "ProblemDetail": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer",
            "format": "int32"
          },
          "detail": {
            "type": "string"
          },
          "instance": {
            "type": "string",
            "format": "uri"
          },
          "properties": {
            "type": "object",
            "additionalProperties": {}
          }
        }
      }
    }
  },
  "webhooks": {
    "notificationWebhook": {
      "post": {
        "summary": "Webhook notification",
        "description": "Bank Frick will POST webhook notifications to the URL you configure in your notification rule.\n\nYou can configure any HTTPS endpoint URL. The path is entirely up to you.\n\nExample URLs:\n- https://your-domain.com/api/webhooks/bankfrick\n- https://your-domain.com/notifications\n- https://api.your-service.com/v1/incoming-webhooks",
        "parameters": [
          {
            "name": "Algorithm",
            "in": "header",
            "description": "Signature algorithm used to sign the webhook payload",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "rsa-sha512"
              ],
              "example": "rsa-sha512"
            }
          },
          {
            "name": "Signature",
            "in": "header",
            "description": "Base64-encoded RSA signature of the webhook payload. Verify using the public key to ensure the webhook came from Bank Frick",
            "required": true,
            "schema": {
              "type": "string",
              "example": "MEUCIQDf...truncated..."
            }
          }
        ],
        "requestBody": {
          "description": "Webhook notification payload",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WebhookPayloadDto"
              },
              "examples": {
                "instant_payment_received_address_lines": {
                  "summary": "Instant payment received with unstructured address lines in postal address",
                  "description": "An incoming instant payment (pacs.008) where the debtor\u0027s 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.",
                  "value": {
                    "AcceptanceDateTime": "2025-11-18T15:41:46.141Z",
                    "EventType": "INSTANT_TRANSACTION_RECEIVED",
                    "Creditor": {
                      "Name": "Example Bank AG",
                      "PostalAddress": {
                        "TownName": "Example City",
                        "Country": "LI",
                        "AddressLine": [
                          "Main Street 123",
                          "Floor 5",
                          "Building A",
                          "Finance Division",
                          "Payment Processing",
                          "PO Box 100",
                          "Example City, LI 9490"
                        ]
                      }
                    },
                    "CreditorAccount": {
                      "Id": {
                        "IBAN": "LI6808811000000001234"
                      }
                    },
                    "CreditorAgent": {
                      "FinancialInstitution": {
                        "BIC": "BFRILI22XXX"
                      }
                    },
                    "Debtor": {
                      "Name": "Jane Doe",
                      "PostalAddress": {
                        "TownName": "Sample Town",
                        "Country": "LU",
                        "AddressLine": [
                          "Commerce Avenue 42",
                          "Room 101",
                          "Accounting Department",
                          "Payment Operations",
                          "Business District",
                          "PO Box 200",
                          "Sample Town, LU L-1234"
                        ]
                      }
                    },
                    "DebtorAccount": {
                      "Id": {
                        "IBAN": "LI11188110101101K001E"
                      }
                    },
                    "DebtorAgent": {
                      "FinancialInstitution": {
                        "BIC": "BFRILI22XXX"
                      }
                    },
                    "TransactionAmount": {
                      "Currency": "EUR",
                      "Amount": 100.0
                    },
                    "RemittanceInformation": {
                      "UnstructuredReference": [
                        "INV-2025-0001"
                      ]
                    }
                  }
                },
                "instant_payment_received_structured_address": {
                  "summary": "Instant payment received with structured address fields in postal address",
                  "description": "An incoming instant payment (pacs.008) where the debtor\u0027s 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.",
                  "value": {
                    "AcceptanceDateTime": "2025-11-18T15:41:46.141Z",
                    "EventType": "INSTANT_TRANSACTION_RECEIVED",
                    "Creditor": {
                      "Name": "Example Bank AG",
                      "PostalAddress": {
                        "StreetName": "Main Street",
                        "BuildingNumber": "123",
                        "PostalCode": "9490",
                        "TownName": "Example City",
                        "Country": "LI",
                        "CountrySubDivision": "Example District",
                        "Department": "Treasury",
                        "DistrictName": "Central District",
                        "Postbox": "PO Box 100",
                        "Room": "Floor 5",
                        "SubDepartment": "Payment Processing",
                        "TownLocationName": "Business District"
                      }
                    },
                    "CreditorAccount": {
                      "Id": {
                        "IBAN": "LI6808811000000001234"
                      }
                    },
                    "CreditorAgent": {
                      "FinancialInstitution": {
                        "BIC": "BFRILI22XXX",
                        "Name": "Bank Frick AG"
                      }
                    },
                    "Debtor": {
                      "Name": "Jane Doe",
                      "PostalAddress": {
                        "StreetName": "Commerce Avenue",
                        "BuildingNumber": "42",
                        "PostalCode": "L-1234",
                        "TownName": "Sample Town",
                        "Country": "LU",
                        "CountrySubDivision": "Sample District",
                        "Department": "Accounting Department",
                        "DistrictName": "City Center",
                        "Postbox": "PO Box 200",
                        "Room": "Room 101",
                        "SubDepartment": "Payment Operations",
                        "TownLocationName": "Business District"
                      }
                    },
                    "DebtorAccount": {
                      "Id": {
                        "IBAN": "LI11188110101101K001E"
                      }
                    },
                    "DebtorAgent": {
                      "FinancialInstitution": {
                        "BIC": "BFRILI22XXX",
                        "Name": "Bank Frick AG"
                      }
                    },
                    "TransactionAmount": {
                      "Currency": "EUR",
                      "Amount": 100.0
                    },
                    "SettlementDate": "2025-11-19Z",
                    "RemittanceInformation": {
                      "UnstructuredReference": [
                        "INV-2025-0001"
                      ]
                    }
                  }
                },
                "instant_payment_received_structured_remittance_information": {
                  "summary": "Instant payment received with 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.",
                  "value": {
                    "AcceptanceDateTime": "2025-11-18T15:41:46.141Z",
                    "EventType": "INSTANT_TRANSACTION_RECEIVED",
                    "Creditor": {
                      "Name": "Example Bank AG",
                      "PostalAddress": {
                        "TownName": "Example City",
                        "Country": "LI",
                        "AddressLine": [
                          "Main Street 123",
                          "Floor 5",
                          "Building A",
                          "Finance Division",
                          "Payment Processing",
                          "PO Box 100",
                          "Example City, LI 9490"
                        ]
                      }
                    },
                    "CreditorAccount": {
                      "Id": {
                        "IBAN": "LI6808811000000001234"
                      }
                    },
                    "CreditorAgent": {
                      "FinancialInstitution": {
                        "BIC": "BFRILI22XXX",
                        "Name": "Bank Frick AG"
                      }
                    },
                    "Debtor": {
                      "Name": "Jane Doe",
                      "PostalAddress": {
                        "TownName": "Sample Town",
                        "Country": "LU",
                        "AddressLine": [
                          "Commerce Avenue 42",
                          "Room 101",
                          "Accounting Department",
                          "Payment Operations",
                          "Business District",
                          "PO Box 200",
                          "Sample Town, LU L-1234"
                        ]
                      }
                    },
                    "DebtorAccount": {
                      "Id": {
                        "IBAN": "LI11188110101101K001E"
                      }
                    },
                    "DebtorAgent": {
                      "FinancialInstitution": {
                        "BIC": "BFRILI22XXX",
                        "Name": "Bank Frick AG"
                      }
                    },
                    "TransactionAmount": {
                      "Currency": "EUR",
                      "Amount": 100.0
                    },
                    "SettlementDate": "2025-11-19Z",
                    "RemittanceInformation": {
                      "StructuredReference": [
                        {
                          "CreditorReferenceInformation": {
                            "Reference": "INV-2025-0001",
                            "CodeOrIssuer": "ABCD"
                          }
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Webhook received and accepted for processing"
          },
          "408": {
            "description": "Request Timeout - webhook will be retried",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetail"
                },
                "examples": {
                  "timeout": {
                    "description": "timeout",
                    "value": {
                      "type": "about:blank",
                      "title": "Request Timeout",
                      "status": 408,
                      "detail": "The request timed out",
                      "instance": "/api/webhooks"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too Many Requests - webhook will be retried",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetail"
                },
                "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"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error - webhook will be retried",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetail"
                },
                "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"
                    }
                  }
                }
              }
            }
          },
          "502": {
            "description": "Bad Gateway - webhook will be retried",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetail"
                },
                "examples": {
                  "bad_gateway": {
                    "description": "bad_gateway",
                    "value": {
                      "type": "about:blank",
                      "title": "Bad Gateway",
                      "status": 502,
                      "detail": "Bad gateway error occurred",
                      "instance": "/api/webhooks"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Service Unavailable - webhook will be retried",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetail"
                },
                "examples": {
                  "service_unavailable": {
                    "description": "service_unavailable",
                    "value": {
                      "type": "about:blank",
                      "title": "Service Unavailable",
                      "status": 503,
                      "detail": "The service is temporarily unavailable",
                      "instance": "/api/webhooks"
                    }
                  }
                }
              }
            }
          },
          "504": {
            "description": "Gateway Timeout - webhook will be retried",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetail"
                },
                "examples": {
                  "gateway_timeout": {
                    "description": "gateway_timeout",
                    "value": {
                      "type": "about:blank",
                      "title": "Gateway Timeout",
                      "status": 504,
                      "detail": "Gateway timeout occurred",
                      "instance": "/api/webhooks"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}