{
  "openapi": "3.0.0",
  "info": {
    "title": "Bank Webhooks API",
    "version": "2.0.0",
    "description": "API documentation for bank-related webhooks, including account and payment operations."
  },
  "components": {
    "schemas": {
      "Address": {
        "type": "object",
        "properties": {
          "street_name": {
            "type": "string",
            "description": "Street name.",
            "maxLength": 70
          },
          "building_number": {
            "type": "string",
            "description": "Building number."
          },
          "town_name": {
            "type": "string",
            "description": "Name of town/city."
          },
          "postal_code": {
            "type": "string",
            "description": "Postal code."
          },
          "country": {
            "type": "string",
            "description": "The country identifier as defined by ISO 3166-1 alpha-2.",
            "maxLength": 2
          }
        },
        "required": [
          "country"
        ]
      },
      "Account": {
        "type": "object",
        "properties": {
          "resource_id": {
            "type": "string",
            "description": "The account ID."
          },
          "iban": {
            "type": "string",
            "description": "The IBAN of the account.",
            "maxLength": 34
          },
          "bban": {
            "type": "string",
            "description": "The local ASPSP identifier of the account.",
            "maxLength": 30
          },
          "account_number": {
            "type": "integer",
            "description": "The account number. Used to identify the account in the United Kingdom.",
            "maxLength": 8
          },
          "sort_code": {
            "type": "integer",
            "description": "The sort code. Used to identify the account in the United Kingdom.",
            "maxLength": 6
          },
          "currency": {
            "type": "string",
            "description": "The account currency in ISO 4217 alpha-3 currency code.",
            "maxLength": 3
          },
          "name": {
            "type": "string",
            "description": "The account name."
          },
          "payment_schemes": {
            "type": "array",
            "description": "The list of possible payment schemes for when the account is used as a debtor during the payment.",
            "items": {
              "type": "string",
              "enum": [
                "SCT",
                "SCTI",
                "FPS",
                "BACS",
                "CHAPS",
                "SWIFT"
              ]
            }
          }
        }
      },
      "DebtorAccount": {
        "type": "object",
        "properties": {
          "iban": {
            "type": "string",
            "description": "The IBAN of the account.",
            "maxLength": 34
          },
          "bban": {
            "type": "string",
            "description": "The local ASPSP identifier of the account.",
            "maxLength": 30
          },
          "account_number": {
            "type": "integer",
            "description": "The account number. Used to identify the account in the United Kingdom.",
            "maxLength": 8
          },
          "sort_code": {
            "type": "integer",
            "description": "The sort code. Used to identify the account in the United Kingdom.",
            "maxLength": 6
          }
        }
      },
      "CreditorAccount": {
        "type": "object",
        "properties": {
          "iban": {
            "type": "string",
            "description": "The IBAN of the account.",
            "maxLength": 34
          },
          "bban": {
            "type": "string",
            "description": "The local ASPSP identifier of the account.",
            "maxLength": 30
          },
          "account_number": {
            "type": "string",
            "description": "The account number. Used to identify the account in the United Kingdom.",
            "maxLength": 8
          },
          "sort_code": {
            "type": "integer",
            "description": "The sort code. Used to identify the account in the United Kingdom.",
            "maxLength": 6
          }
        }
      },
      "Balance": {
        "type": "object",
        "properties": {
          "balance_amount": {
            "$ref": "#/components/schemas/Amount"
          },
          "balance_type": {
            "type": "string",
            "description": "The type of the balance.",
            "enum": [
              "openingBooked",
              "interimAvailable",
              "interimBooked",
              "forwardAvailable",
              "nonInvoiced"
            ]
          }
        }
      },
      "RemittanceInformationStructured": {
        "type": "object",
        "properties": {
          "reference": {
            "type": "string",
            "description": "The remittance information.",
            "maxLength": 35
          },
          "reference_type": {
            "type": "string",
            "description": "The type of the remittance information.",
            "maxLength": 35
          }
        }
      },
      "AccountTransactionsRequest": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "The account ID. Identical to the `resource_id` from the [Get account list](#webhooks--accounts--get-account-list) webhook."
          },
          "booking_status": {
            "type": "string",
            "description": "The type of transactions to return.",
            "enum": [
              "booked",
              "pending",
              "both"
            ]
          },
          "page_key": {
            "type": "string",
            "description": "The value indicates which page to retrieve. Applicable when there is more than one data page available."
          },
          "page_size": {
            "type": "integer",
            "description": "The maximum number of transactions to show in the response. The default value is `100`.",
            "default": 100
          },
          "date_from": {
            "type": "string",
            "description": "Filters transactions beginning from a specific date in `YYYY-MM-DD` format."
          },
          "date_to": {
            "type": "string",
            "description": "Filters transactions ending on a specific date in `YYYY-MM-DD` format."
          }
        },
        "required": [
          "account_id",
          "booking_status"
        ]
      },
      "AccountTransaction": {
        "type": "object",
        "properties": {
          "booked": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          },
          "pending": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          }
        }
      },
      "AccountTransactionsResponse": {
        "type": "object",
        "properties": {
          "transactions": {
            "$ref": "#/components/schemas/AccountTransaction"
          },
          "page_key": {
            "type": "string",
            "description": "The key for the next page of results."
          }
        }
      },
      "AccountRequest": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "The account ID."
          }
        },
        "required": [
          "account_id"
        ]
      },
      "AccountResponse": {
        "type": "object",
        "properties": {
          "account": {
            "$ref": "#/components/schemas/Account"
          }
        }
      },
      "AccountBalanceRequest": {
        "type": "object",
        "properties": {
          "account_id": {
            "type": "string",
            "description": "The account ID."
          }
        },
        "required": [
          "account_id"
        ]
      },
      "AccountBalanceResponse": {
        "type": "object",
        "properties": {
          "balances": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Balance"
            }
          }
        }
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "transaction_id": {
            "type": "string",
            "description": "The transaction ID."
          },
          "creditor_name": {
            "type": "string",
            "description": "The transaction recipient's name."
          },
          "creditor_account": {
            "$ref": "#/components/schemas/Account"
          },
          "debtor_name": {
            "type": "string",
            "description": "The transaction sender's name."
          },
          "debtor_account": {
            "$ref": "#/components/schemas/Account"
          },
          "remittance_information_unstructured": {
            "type": "string",
            "description": "The remittance information in a single string.",
            "maxLength": 140
          },
          "remittance_information_structured": {
            "$ref": "#/components/schemas/RemittanceInformationStructured"
          },
          "transaction_amount": {
            "type": "object",
            "properties": {
              "amount": {
                "type": "string",
                "description": "The transaction amount."
              },
              "currency": {
                "type": "string",
                "description": "The transaction currency in ISO 4217 alpha-3 currency code.",
                "maxLength": 3
              },
              "value_date": {
                "type": "string",
                "description": "The date when assets become available.",
                "format": "date"
              },
              "booking_date": {
                "type": "string",
                "description": "The date when entry is posted to the account.",
                "format": "date"
              }
            }
          }
        }
      },
      "Amount": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "string",
            "description": "The amount value. The decimal separator is a dot."
          },
          "currency": {
            "type": "string",
            "description": "The currency in ISO 4217 alpha-3 currency code.",
            "maxLength": 3
          }
        },
        "required": [
          "amount",
          "currency"
        ]
      },
      "CreditorBank": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "The name of the institution."
          },
          "bic": {
            "type": "string",
            "description": "The Business Identifier Code."
          },
          "country": {
            "type": "string",
            "description": "The country identifier as defined by the ISO 3166-1 alpha-2.",
            "maxLength": 2
          }
        },
        "required": [
          "name",
          "country"
        ]
      },
      "PaymentSingleRequest": {
        "type": "object",
        "properties": {
          "payment_scheme": {
            "type": "string",
            "enum": [
              "SCT",
              "SCTI",
              "FPS",
              "BACS",
              "CHAPS",
              "SWIFT"
            ],
            "description": "Describes which payment scheme is used. See [Payment Schemes](#appendix--enum--payment-schemes) for possible values."
          },
          "debtor_account": {
            "$ref": "#/components/schemas/DebtorAccount"
          },
          "debtor_name": {
            "type": "string",
            "maxLength": 70,
            "description": "The name of the debtor/sender."
          },
          "creditor_account": {
            "$ref": "#/components/schemas/CreditorAccount"
          },
          "creditor_name": {
            "type": "string",
            "maxLength": 70,
            "description": "The name of the creditor/receiver."
          },
          "remittanceInformationUnstructured": {
            "type": "string",
            "maxLength": 140,
            "description": "An unstructured reference of the transaction."
          },
          "remittanceInformationStructured": {
            "$ref": "#/components/schemas/RemittanceInformationStructured"
          },
          "creditorAddress": {
            "$ref": "#/components/schemas/Address"
          },
          "instructedAmount": {
            "$ref": "#/components/schemas/Amount"
          },
          "callback_url": {
            "type": "string",
            "description": "The URL to which the transaction flow redirects after the SCA."
          },
          "creditor_bank": {
            "$ref": "#/components/schemas/CreditorBank"
          }
        },
        "required": [
          "instructed_amount",
          "callback_url"
        ]
      },
      "PaymentSingleResponse": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "description": "[Payment Status](#appendix--enum--payment-status)",
            "enum": [
              "ACCC",
              "ACCP",
              "ACSC",
              "ACSP",
              "ACTC",
              "ACWC",
              "ACWP",
              "RCVD",
              "PDNG",
              "RJCT",
              "CANC",
              "ACFC",
              "PATC",
              "PART"
            ]
          },
          "confirmation_url": {
            "type": "string",
            "description": "The URL to which the user gets redirected to enter their SCA confirmation."
          },
          "payment_id": {
            "type": "string",
            "description": "The unique payment identifier.",
            "maxLength": 255
          }
        },
        "required": [
          "status",
          "confirmation_url",
          "payment_id"
        ]
      },
      "PaymentCallbackParameters": {
        "type": "object",
        "required": ["status", "payment_id"],
        "properties": {
          "status": {
            "type": "string",
            "description": "The payment status after confirmation.",
            "maxLength": 4,
            "enum": ["ACCC", "ACCP", "ACSC", "ACSP", "ACTC", "ACWC", "ACWP", "RCVD", "PDNG", "RJCT", "CANC", "ACFC", "PATC", "PART"]
          },
          "payment_id": {
            "type": "string",
            "description": "The unique payment identifier.",
            "maxLength": 255
          },
          "message": {
            "type": "string",
            "description": "The message with a description in case of error."
          }
        }
      },
      "PaymentSingleStatusRequest": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string",
            "description": "The unique payment identifier.",
            "maxLength": 255
          }
        },
        "required": [
          "payment_id"
        ]
      },
      "TransactionStatusResponse": {
        "type": "object",
        "properties": {
          "transaction_status": {
            "type": "string",
            "description": "[Payment status](#appendix--enum--payment-status)",
            "enum": [
              "ACCC",
              "ACCP",
              "ACSC",
              "ACSP",
              "ACTC",
              "ACWC",
              "ACWP",
              "RCVD",
              "PDNG",
              "RJCT",
              "CANC",
              "ACFC",
              "PATC",
              "PART"
            ]
          }
        },
        "required": [
          "transaction_status"
        ]
      },
      "InstructedTotals": {
        "type": "object",
        "properties": {
          "currency": {
            "type": "string",
            "maxLength": 3,
            "description": "The total amount of currency in ISO 4217 alpha-3 currency code."
          },
          "amount": {
            "type": "string",
            "maxLength": 10,
            "description": "The total amount."
          }
        },
        "required": ["currency", "amount"]
      },
      "SingleBulkPayment": {
        "type": "object",
        "properties": {
          "creditor_account": {
            "$ref": "#/components/schemas/CreditorAccount"
          },
          "creditorName": {
            "type": "string",
            "maxLength": 70,
            "description": "The name of the creditor/receiver."
          },
          "remittanceInformationUnstructured": {
            "type": "string",
            "maxLength": 140,
            "description": "An unstructured reference of the transaction."
          },
          "remittanceInformationStructured": {
            "$ref": "#/components/schemas/RemittanceInformationStructured"
          },
          "creditorAddress": {
            "$ref": "#/components/schemas/Address"
          },
          "instructedAmount": {
            "$ref": "#/components/schemas/Amount"
          }
        },
        "required": ["instructed_amount"]
      },
      "PaymentBulkRequest": {
        "type": "object",
        "properties": {
          "payment_scheme": {
            "type": "string",
            "enum": [
              "SCT",
              "SCTI",
              "FPS",
              "BACS",
              "CHAPS",
              "SWIFT"
            ],
            "description": "Describes which payment scheme is used."
          },
          "debtor_account": {
            "$ref": "#/components/schemas/DebtorAccount"
          },
          "debtor_name": {
            "type": "string",
            "maxLength": 70,
            "description": "The name of the debtor/sender."
          },
          "callback_url": {
            "type": "string",
            "description": "The URL to which the transaction flow redirects after the SCA."
          },
          "instructed_totals": {
            "$ref": "#/components/schemas/InstructedTotals"
          },
          "payments": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/SingleBulkPayment"
            }
          }
        },
        "required": [
          "callback_url",
          "instructed_totals",
          "payments"
        ]
      },
      "PaymentBulkStatusRequest": {
        "type": "object",
        "properties": {
          "payment_id": {
            "type": "string",
            "description": "The unique payment identifier.",
            "maxLength": 255
          }
        },
        "required": [
          "payment_id"
        ]
      }
    }
  },
  "paths": {
    "/v2_accounts": {
      "post": {
        "summary": "Get account list.",
        "description": "Get the list of accounts for the authenticated user.\n\n \"Get accounts\" is initiated by the request from TPP and it is part of the [Get data flow](#appendix--workflow-get-data) between the BANK and TOB. TPP requests client’s accounts information from TOB which requests the information from the BANK. \n\n In the case of multicurrency accounts, the account for each of the currencies associated with the same account identifier (e.g. IBAN) will be returned in the response with a different `resource_id`.",
        "tags": [
          "Accounts"
        ],
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "accounts": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Account"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v2_account": {
      "post": {
        "summary": "Get single account details.",
        "description": "Get details for a specific account.",
        "tags": [
          "Accounts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                    "$ref": "#/components/schemas/AccountResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2_account_balances": {
      "post": {
        "summary": "Get account balances.",
        "description": "Get balances for a specific account.",
        "tags": [
          "Accounts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountBalanceRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountBalanceResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2_account_transactions": {
      "post": {
        "summary": "Get account transactions.",
        "description": "Get transactions for a specific account.",
        "tags": [
          "Accounts"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AccountTransactionsRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountTransactionsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2_payment_single": {
      "post": {
        "summary": "Single payment",
        "description": "\"Single payment\" is initiated by the request from TPP, which requests TOB to initiate the [payment](#appendix--workflow--payment). \nTOB requests BANK to initiate the payment and respond with a `confirmation_url` to which the user should be redirected to complete the SCA.",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "description": "In the case of debtor_account and creditor_account, at least one of IBAN, BBAN or account_number **with** sort_code has to be provided, depending on the `payment_scheme` and type of payment initiated.\n",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentSingleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentSingleResponse"
                }
              }
            }
          },
          "302": {
            "description": "Callback URL parameters for redirect after user accesses `confirmation_url` and BANK performs redirect to `callback_url` from request content:\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentCallbackParameters"
                }
              }
            }
          }
        }
      }
    },
    "/v2_payment_single_status": {
      "post": {
        "summary": "Get single payment status",
        "description": "\"Get single payment status\" is initiated by the request from TPP. It is a part of the [Get data flow](#appendix--workflow--get-data) between the BANK and TOB.\nTPP requests the status of initiated payment from TOB, which then requests the information from the BANK.",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentSingleStatusRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2_payment_bulk": {
      "post": {
        "summary": "Bulk payment.",
        "description": "\"Bulk payment\" is initiated by the request from TPP to TOB to initiate the [payment](#appendix--workflow--payment).\nTOB requests BANK to initiate a bulk of payments and respond with a `confirmation_url` to which the user should be redirected.",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "description": "In the case of debtor_account and creditor_account, at least one of IBAN, BBAN, or account_number with sort_code has to be provided.",
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentBulkRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentSingleResponse"
                }
              }
            }
          },
          "302": {
            "description": "Callback URL parameters for redirect after user accesses `confirmation_url` and BANK performs redirect to `callback_url` from request content:\n",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentCallbackParameters"
                }
              }
            }
          }
        }
      }
    },
    "/v2_payment_bulk_status": {
      "post": {
        "summary": "Get bulk payment status",
        "description": "\"Get bulk payment status\" is initiated by the request from TPP. It is part of the [Get data flow](#appendix--workflow--get-data) between the BANK and TOB.\nTPP requests the status of initiated payment from TOB, which then requests the information from the BANK.",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentBulkStatusRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionStatusResponse"
                }
              }
            }
          }
        }
      }
    },
    "/v2_payment_direct_single": {
      "post": {
        "summary": "Direct payment initiation.",
        "description": "\"Direct payment initiation\" is initiated by the request from TPP. TOB requests BANK to initiate the payment and respond with a `confirmation_url` to which the user should be redirected.\nIt is a part of the flow where TPP requests TOB to initiate the [Direct payment](#appendix--workflow--direct-payment).\nThe endpoint is almost identical to the [payment](#webhooks--payment--initiate) one. The difference has to do with [Security](#security) where the `X-Auth-Token` header identifying the user is not passed.",
        "tags": [
          "Payments"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentSingleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentSingleResponse"
                }
              }
            }
          },
          "302": {
            "description": "Callback URL parameters for redirect after the user accesses `confirmation_url` and BANK performs redirect to `callback_url` from request content:\n.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentCallbackParameters"
                }
              }
            }
          }
        }
      }
    },
    "/v2_funds_confirmations": {
      "post": {
        "summary": "Confirmation of funds.",
        "description": "\"Confirmation of funds\" is initiated by the request from TPP. It is a part of the [Get data flow](#appendix--workflow--get-data) between the BANK and TOB.\n\nIt can be used by CBPII to confirm the amount of funds available in the account. Funds can only be confirmed against the currency of the account. This action does not reserve an amount requested in the account but only indicates if the requested amount is present at the time of the API call.\n",
        "tags": [
          "Funds"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "account": {
                    "$ref": "#/components/schemas/Account"
                  },
                  "instructed_amount": {
                    "$ref": "#/components/schemas/Amount"
                  }
                },
                "required": [
                  "account",
                  "instructed_amount"
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "funds_available": {
                      "type": "boolean",
                      "description": "Indicates if the requested amount is available in the account."
                    }
                  },
                  "required": [
                    "funds_available"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}