Payment Matching

General information

HORES Payment Matching API is designed to process individual payments from bank account statements or similar sources, record them and automatically or manually match them to reservations or invoices in HORES.

API is designed as simple HTTP API using JSON data format, see available endpoints.

Using SSL encryption (HTTPS) is mandatory.

Authorization

Authentication is done via HTTP Authorization header using permanent token.

Token can be defined for each user in HORES and allows for non-interactive authentication of API operations in the name of that user. Use „Authorization“ header with „Token“ keyword such as:

POST /payment_matching/match_payments HTTP/1.1
Host: example.com
Accept: application/json
Authorization: Token 65sad4f64df6sd6f4sdffassdfa

API Endpoints

GET /payment_matching/hores_info

Version and build info about running HORES instance. You can use this endpoint to check if server is running and validate your token.

POST /payment_matching/match_payments

Post one or more transactions to process.

„amount“, „transaction_id“, „currency_code“ and „date_of_payment“ fields are mandatory.

„transaction_id“ must be unique for every transaction for particular client across all accounts. Repeated requests with same transaction_id will result in warning „transaction already exists“ for given transaction. Transaction with duplicated „transaction_id“ is not updated, duplicated data are ignored!

Single request may contain multiple transactions. Transactions are processed individually.

If all transactions within request are processed without error, return code is 0. Otherwise return code is 1 and list of „errors“ is provided.

Any other return code beside 0 and 1 means complete failure to process request.

Example request:

{
  "transactions": [
    {
      "amount": "1000.00",
      "transaction_id": "20230001",
      "date_of_payment": "2023-12-10T12:23:44.233+02:00",
      "currency_code": "EUR",
      "is_transaction_fee": false,
      "variable_symbol": "233445",
      "specific_symbol": "2334",
      "constant_symbol": "0800",
      "bank_account_number": "233456754332",
      "bank_number_code": "3300",
      "transaction_type": null,
      "iban": "CZ6508000000192000145399",
      "bic": "HBUKGB4B",
      "bank_account_name": "Hotel account",
      "private_note": "Reservation 2344",
      "description": "Reservation 2344",
      "original_amount": null,
      "original_amount_currency_code": null,
      "exchange_rate": null,
      "transactional_fee_amount": null
    }
  ]
}

Request JSON Object:

• amount (numeric) – Paid amount, use negative number for outgoing payments.

• transaction_id (string) – Unique payment identification.

• transactional_fee_amount (numeric) – Transaction fee.

• is_transaction_fee (boolean) – If true, entire transaction is considered transaction fee.

• currency_code (string) – ISO code of transaction currency.

• date_of_payment (datetime) – Date of transaction in ISO format with timezone

• variable_symbol (string) – Variable symbol

• specific_symbol (string) – Specific symbol

• constant_symbol (string) – Constant symbol

• bank_account_number (string) – Source bank account number

• bank_number_code (string) – Czech bank code

• transaction_type (string) – Details of payment method

• iban (string) – International IBAN account number for source account

• bid (string) – BIC (SWIFT) code for source account

• bank_account_name" (string) – Account name to identify source account

• private_note (string) – User note for transaction

• description (string) – Sender’s note for transaction

• original_amount (numeric) – Amount in currency different from account currency

• original_amount_currency_code (string) – ISO code for original currency

• exchange_rate (numeric) – Exchange rate used for automatic conversion

Example success response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "result": 0,
  "accepted_transactions": ["20230001"]
}

Example warning response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "result": 0,
  "accepted_transactions": [20230002],
  "warnings": [
    {
      "transaction_id": "20230001",
      "warning": "Unique violation error, transaction already exists!"
    }
}

Example error response:

HTTP/1.1 200 OK
Vary: Accept
Content-Type: application/json

{
  "result": 1,
  "accepted_transactions": [],
  "errors": [
    {
      "transaction_id": "20230001",
      "error": "Missing price!"
    }
}