Authorization

In order to fetch the accounts and transactions of a user customers require the access token that has been obtained in the previous steps. Use this token to make requests to the accounts and transactions endpoints.

Endpoints Overview

Request Example:

GET /rest/account-verifications/{account-verification-id}

Example Response:

{
  "id": "9054f9b1-0d19-4788-a990-b493d5723419",
  "provided": {
    "name": "Ahmad Al-Faisal",
    "iban": "SA4420000001234567891234"
  },
  "matched": {
    "name": "Ahmad Al-Faisal",
    "affinity": "VERY_HIGH"
  },
  "account": {
    "name": "Savings Account",
    "type": "Current Account",
    "owners": [],
    "iban": "SA4420000001234567891234",
    "currency": "SAR"
  }
}

The verification report provides an evaluation of the affinity between the initially provided name and the best matching account-holder name.

The affinity is:

• VERY_HIGH if the names literally match (case-insensitive).
• HIGH if there is a significant overlap with only minor deviations (e.g., "Al-Saud, Khalid" instead of "Khalid Al-Saud" or "Mohammed Al-Faisal" instead of "Muhammad Al-Faisal").
• MEDIUM if there is only some similarity between the names (e.g., "Ali Ahmed" vs. "Omar Ahmed").
• LOW if the names don't match at all.

📘

Under normal circumstances, it is advised to consider the affinities VERY_HIGH and HIGH as a match and disregard MEDIUM and LOW affinities.

The receipt also contains some basic account information like the IBAN, type and account-
name.

Error Handling

The finX API employs HTTP status codes to indicate the outcome of each API request. Familiarity with these codes is essential for understanding the response.

200 OK: This status code indicates a successful request, typically returned when retrieving account or transaction data.

400 Bad Request: If the request is malformed, contains missing or invalid parameters, or violates validation rules, the API responds with a 400 status code.

401 Unauthorized: When the provided authorization is insufficient or invalid, the API responds with a 401 status code, indicating the need for proper user authentication.

403 Forbidden: This status code signifies that the user's authorization is valid, but they lack access to the requested resource. Further permissions or consent may be required.