Finverse API

https://docs.finverse.com
Admin
Finverse API provides a platform for integrating payment processing, managing mandates, and...
Tokens:23,783
Snippets:160
Trust Score:7.5
Update:10 months ago
Show doc for...
Tokens:
Raw
### Error: PAYMENT_MANDATE_REJECTED

Source: https://docs.finverse.com/index

Indicates that a mandate setup has been rejected by the sender's bank. This often happens when the accountholder details provided do not match the bank's records, similar to reasons for `PAYMENT_AUTHORIZATION_FAILED`.

```APIDOC
## GET /mandates and GET /mandates/{mandate_id}

### Description
The `PAYMENT_MANDATE_REJECTED` error means the mandate setup was turned down by the sender's bank. This is usually due to a mismatch in account holder information provided versus the bank's records.

### Method
GET

### Endpoint
`/mandates` or `/mandates/{mandate_id}`

### Parameters
#### Path Parameters
* `mandate_id` (string) - Required - The unique identifier of the mandate.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No specific request body for this error, it's a response to an action."
}
```

### Response
#### Success Response (200)
Not applicable for error documentation.

#### Response Example
```json
{
    "error": {
        "error_code": "PAYMENT_MANDATE_REJECTED",
        "message": "Debit authorization rejected",
        "type": "PAYMENT_ERROR",
        "details": "Debit authorization rejected by your institution. Please try again, or contact your institution's customer support. (Error details: {bank_provided_error_code} {bank_provided_error_description})"
    }
}
```
```

--------------------------------

### PAYMENT_MANDATE_REJECTED Error Response (JSON)

Source: https://docs.finverse.com/index

Signifies that a mandate setup has been rejected by the sender's bank. This is relevant for mandate payments and endpoints like GET /mandates and GET /mandates/{mandate_id}. Common causes include mismatches in account holder details compared to bank records.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "error_code": "PAYMENT_MANDATE_REJECTED",
        "message": "Debit authorization rejected",
        "type": "PAYMENT_ERROR",
        "details": "Debit authorization rejected by your institution. Please try again, or contact your institution's customer support. (Error details: {bank_provided_error_code} {bank_provided_error_description})"
    }
}
```

--------------------------------

### Handle PAYMENT_NOT_RECEIVED Errors in JSON

Source: https://docs.finverse.com/index

This JSON response indicates that a manual payment was not received. It's often due to the user not completing the payment or Finverse being unable to match payment information. Relevant endpoints include GET /payments and GET /payments/{payment_id}.

```json
{
    "error": {
        "error_code": "PAYMENT_NOT_RECEIVED",
        "message": "Payment not received",
        "type": "PAYMENT_ERROR",
        "details": "We are unable to confirm receipt of this payment. Please verify that the payment was sent, and that the payment information provided was correct (e.g. sender accountholder name / account number). If you have verified that the payment was sent, please contact Finverse customer support (support@finverse.com)."
    }
}
```

--------------------------------

### GET /login_identity/{login_identity_id}

Source: https://docs.finverse.com/index

Retrieves a specific login identity resource. This endpoint is used to fetch details of a particular login identity using its unique ID.

```APIDOC
## GET /login_identity/{login_identity_id}

### Description
Retrieves a specific login identity resource. This endpoint is used to fetch details of a particular login identity using its unique ID.

### Method
GET

### Endpoint
`/login_identity/{login_identity_id}`

### Parameters
#### Path Parameters
- **login_identity_id** (string) - Required - The unique identifier for the login identity.

### Request Example
(No request body for GET requests)

### Response
#### Success Response (200)
- **(response body structure depends on the actual response)**

#### Response Example
```json
{
  "example": "response body"
}
```

#### Error Response (404 Not Found)
- **error** (object) - Contains error details.
  - **error_code** (string) - Specific error code, e.g., "LOGIN_IDENTITY_NOT_FOUND".
  - **message** (string) - A human-readable message describing the error.
  - **request_id** (string) - Unique identifier for the request.
  - **type** (string) - The type of error, e.g., "API_ERROR".

```json
{
    "error": {
        "error_code": "LOGIN_IDENTITY_NOT_FOUND",
        "message": "login_identity_id cannot be found. Resource does not exist, has been deleted, or is no longer accessible.",
        "request_id": "[request_id]",
        "type": "API_ERROR"
    }
}
```
```

--------------------------------

### PAYMENT_IDENTITY_VERIFICATION_FAILED

Source: https://docs.finverse.com/index

Indicates that a payment or payment method setup has been blocked due to incorrect identity information. This primarily affects mandate payments.

```APIDOC
## PAYMENT_IDENTITY_VERIFICATION_FAILED

### Description
Payment or payment method setup has been blocked by Finverse or a payment processor due to incorrect identity information.

### Relevant payment types
Mandate payments (i.e. direct debit)

### Relevant endpoints
- `GET /mandates`
- `GET /mandates/{mandate_id}`

### Common causes
Accountholder name of the sender account does not match the sender's name.

### Response Example (400 Bad Request)
```json
{
    "error": {
        "error_code": "PAYMENT_IDENTITY_VERIFICATION_FAILED",
        "message": "Identity verification failed",
        "type": "PAYMENT_ERROR",
        "details": "Account holder identity does not match information provided by the biller. Please try again or contact customer support.."
    }
}
```
```

--------------------------------

### Handle PAYMENT_INSUFFICIENT_FUNDS Error

Source: https://docs.finverse.com/index

This error occurs when the sender's bank account has insufficient funds for a payment. It applies to all payment types and is associated with endpoints like POST /payments and GET /payments/{payment_id}. The error details may include gateway-specific codes and descriptions.

```json
{
    "error": {
        "error_code": "PAYMENT_INSUFFICIENT_FUNDS",
        "message": "Insufficient funds",
        "type": "PAYMENT_ERROR",
        "details": "Payment method does not have sufficient funds. Please add funds to your payment method and try again. (Error details: {gateway_error_code} {gateway_error_description})"
    }
}
```

--------------------------------

### Handle PAYMENT_IDENTITY_VERIFICATION_FAILED Error

Source: https://docs.finverse.com/index

This error indicates that a payment or payment method setup has been blocked due to incorrect identity information. It is relevant for mandate payments and occurs when the accountholder name does not match the sender's name. The response includes an error code, message, type, and specific details.

```json
{
    "error": {
        "error_code": "PAYMENT_IDENTITY_VERIFICATION_FAILED",
        "message": "Identity verification failed",
        "type": "PAYMENT_ERROR",
        "details": "Account holder identity does not match information provided by the biller. Please try again or contact customer support.."
    }
}
```

--------------------------------

### Error: PAYMENT_MANDATE_NOT_EFFECTIVE

Source: https://docs.finverse.com/index

This error occurs when the effective date for a debit authorization has not yet started. It is relevant for mandate payments (direct debit) and can happen if the current date is earlier than the requested start date for the mandate.

```APIDOC
## POST /payments and GET /payments/{payment_id}

### Description
The `PAYMENT_MANDATE_NOT_EFFECTIVE` error indicates that the debit authorization's effective date has not yet begun. This is relevant for mandate payments and commonly occurs when the current date precedes the mandate's start date.

### Method
POST, GET

### Endpoint
`/payments` or `/payments/{payment_id}`

### Parameters
#### Path Parameters
* `payment_id` (string) - Required - The unique identifier of the payment.

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No specific request body for this error, it's a response to an action."
}
```

### Response
#### Success Response (200)
Not applicable for error documentation.

#### Response Example
```json
{
    "error": {
        "error_code": "PAYMENT_MANDATE_NOT_EFFECTIVE",
        "message": "Debit authorization not effective",
        "type": "PAYMENT_ERROR",
        "details": "Your required debit authorization is not yet in effect. Please try again later, or set up a new debit authorization. (Error details: {bank_provided_error_code} {bank_provided_error_description})"
    }
}
```
```

--------------------------------

### Handle PAYMENT_REJECTED Errors in JSON

Source: https://docs.finverse.com/index

This JSON response signifies that a payment was rejected by the sender's institution, possibly due to a closed account or insufficient funds. This applies to any payment type and relevant endpoints include POST /payments and GET /payments/{payment_id}.

```json
{
    "error": {
        "error_code": "PAYMENT_REJECTED",
        "message": "Payment rejected",
        "type": "PAYMENT_ERROR",
        "details": "Payment rejected by your payment method. Please verify that you have sufficient funds available and try again, or contact your payment method's customer support. (Error details: {gateway_error_code} {gateway_error_description})"
    }
}
```

--------------------------------

### Handle PAYMENT_RETRIES_EXCEEDED Errors in JSON

Source: https://docs.finverse.com/index

This JSON response indicates that a payment request was blocked due to too many failed attempts, often caused by insufficient funds or a frozen payment method. This error is relevant for any payment type and can occur with GET /payments and GET /payments/{payment_id} endpoints.

```json
{
    "error": {
        "error_code": "PAYMENT_RETRIES_EXCEEDED",
        "message": "Too many payment retry attempts",
        "type": "PAYMENT_ERROR",
        "details": "You have reached the maximum number of payment retries allowed for this period. Please try again later or use a different payment method."
    }
}
```

--------------------------------

### PAYMENT_MANDATE_NOT_EFFECTIVE Error Response (JSON)

Source: https://docs.finverse.com/index

Indicates that a debit authorization's effective date has not yet started. This applies to mandate payments and endpoints such as POST /payments and GET /payments/{payment_id}. A common cause is the current date being earlier than the mandate's requested start date.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "error_code": "PAYMENT_MANDATE_NOT_EFFECTIVE",
        "message": "Debit authorization not effective",
        "type": "PAYMENT_ERROR",
        "details": "Your required debit authorization is not yet in effect. Please try again later, or set up a new debit authorization. (Error details: {bank_provided_error_code} {bank_provided_error_description})"
    }
}
```

--------------------------------

### PRODUCT_NOT_READY

Source: https://docs.finverse.com/index

Indicates that a requested product is not yet ready for use.

```APIDOC
## PRODUCT_NOT_READY

### Description
This error occurs when the requested product or feature is not yet available or fully configured. Please check the product status or try again later.

### Method
GET

### Endpoint
- `/composite_statement`

### Parameters
None

### Request Example
None

### Response
#### Success Response (400)
This error response is returned as a 400 Bad Request.
- **error** (object)
  - **error_code** (string) - "PRODUCT_NOT_READY"
  - **message** (string) - "Requested product is not yet ready. Please review product_status or try again later."
  - **request_id** (string) - A unique identifier for the request.
  - **type** (string) - "API_ERROR"

#### Response Example
```json
{
    "error": {
        "error_code": "PRODUCT_NOT_READY",
        "message": "Requested product is not yet ready. Please review product_status or try again later.",
        "request_id": "{unique_id}",
        "type": "API_ERROR"
    }
}
```
```

--------------------------------

### PRODUCT_NOT_READY Error Response

Source: https://docs.finverse.com/index

This error signifies that the requested product or feature is not yet ready for use. It suggests checking the 'product_status' or trying again later. This is a general API error.

```json
{
    "error": {
        "error_code": "PRODUCT_NOT_READY",
        "message": "Requested product is not yet ready. Please review product_status or try again later.",
        "request_id": "{unique_id}",
        "type": "API_ERROR"
    }
}
```

--------------------------------

### PAYMENT_METHOD_INVALID Error Response (JSON)

Source: https://docs.finverse.com/index

This error signifies that a payment method is no longer valid, for example, if it has been closed or frozen. It applies to card payments and endpoints like GET /payments and GET /payments/{payment_id}. Common causes include the payment method being closed, frozen, or reported stolen.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "error_code": "PAYMENT_METHOD_INVALID",
        "message": "Invalid payment methhod",
        "type": "PAYMENT_ERROR",
        "details": "Your payment method is invalid, closed or frozen. Please use a different payment method."
    }
}
```

--------------------------------

### Finverse Link UI Modes (Web App)

Source: https://docs.finverse.com/index

Explains the different `ui_mode` options for integrating Finverse Link UI within a web application, detailing how each mode affects the user experience and integration flow.

```APIDOC
## Finverse Link UI in a Web App

### Description
When opening the Finverse Link UI in a Web App, it is important to note that we currently support the following `ui_mode`:

### UI Modes

| `ui_mode` value     | Description
```

--------------------------------

### PRODUCT_NOT_SUPPORTED

Source: https://docs.finverse.com/index

This error is returned when a requested product endpoint is not supported by the institution.

```APIDOC
## PRODUCT_NOT_SUPPORTED

### Description
This error indicates that a requested product (e.g., Accounts, Balance History, Transactions) is not supported by the financial institution. Consult the institution's details for supported products.

### Method
Not specified (applies to multiple endpoints)

### Endpoint
Not specified (applies to multiple endpoints)

### Parameters
None

### Request Example
None

### Response
#### Success Response (400)
This error response is returned as a 400 Bad Request.
- **error** (object)
  - **details** (string) - Specific details about the unsupported product.
  - **error_code** (string) - "PRODUCT_NOT_SUPPORTED"
  - **message** (string) - A message indicating the product is not supported.
  - **request_id** (string) - A unique identifier for the request.
  - **type** (string) - "API_ERROR"

#### Response Example
```json
{
    "error": {
        "details": "Balance history is not supported for this bank",
        "error_code": "PRODUCT_NOT_SUPPORTED",
        "message": "Requested product is not yet supported for this institution. Please refer to Institutions list for details on products supported.",
        "request_id": "{unique_id}",
        "type": "API_ERROR"
    }
}
```
```

--------------------------------

### PRODUCT_NOT_SUPPORTED Error Response

Source: https://docs.finverse.com/index

This error indicates that a requested product (e.g., Balance History, Statements) is not supported by the financial institution. The specific details provided will depend on the unsupported product. This is a general API error.

```json
{
    "error": {
        "details": "Balance history is not supported for this bank",
        "error_code": "PRODUCT_NOT_SUPPORTED",
        "message": "Requested product is not yet supported for this institution. Please refer to Institutions list for details on products supported.",
        "request_id": "{unique_id}",
        "type": "API_ERROR"
    }
}
```

--------------------------------

### PAYMENT_METHOD_EXPIRED Error Response (JSON)

Source: https://docs.finverse.com/index

Indicates that a payment method, such as a card, has expired. This is relevant for card payments and endpoints like GET /payments and GET /payments/{payment_id}. The primary cause is a card reaching its expiration date.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "error_code": "PAYMENT_METHOD_EXPIRED",
        "message": "Payment method expired",
        "type": "PAYMENT_ERROR",
        "details": "Please use a different payment method."
    }
}
```

--------------------------------

### Payments API - Payment Links

Source: https://docs.finverse.com/index

Initiates a payment link for processing payments. This is the recommended integration for payments.

```APIDOC
## POST /payment_links

### Description
Creates a payment link for initiating a payment. This endpoint is part of the Payments API and is the recommended integration method.

### Method
POST

### Endpoint
/payment_links

### Parameters
#### Request Body
- **amount** (number) - Required - The payment amount.
- **currency** (string) - Required - The currency of the payment (e.g., 'USD', 'EUR').
- **description** (string) - Optional - A description for the payment.
- **customer_reference** (string) - Optional - A reference for the customer.

### Request Example
```json
{
  "amount": 100.50,
  "currency": "USD",
  "description": "Order #12345",
  "customer_reference": "cust_ref_abc"
}
```

### Response
#### Success Response (200)
- **link_id** (string) - The unique identifier for the payment link.
- **url** (string) - The URL to redirect the user to complete the payment.

#### Response Example
```json
{
  "link_id": "pl_abc123xyz",
  "url": "https://link.prod.finverse.net/pay/abc123xyz"
}
```
```

--------------------------------

### INCOME_ESTIMATION_NOT_SUPPORTED Error Response

Source: https://docs.finverse.com/index

This error signifies that income estimation is not supported for the institution in question. It is specific to the income endpoint.

```json
{
  "error": {
    "code": 40004,
    "message": "Income estimation is not yet supported for this institution",
    "name": "INCOME_ESTIMATON_NOT_SUPPORTED"
  }
}
```

--------------------------------

### Handle LOGIN_IDENTITY_NOT_FOUND API Error

Source: https://docs.finverse.com/index

This error indicates that a requested Login Identity resource could not be found. It is typically returned with a 404 Not Found status code. Ensure the login_identity_id is correct and the resource exists.

```json
HTTP status code: 404 Not Found
{
    "error": {
        "error_code": "LOGIN_IDENTITY_NOT_FOUND",
        "message": "login_identity_id cannot be found. Resource does not exist, has been deleted, or is no longer accessible.",
        "request_id": "[request_id]",
        "type": "API_ERROR"
    }
}
```

--------------------------------

### Data API - Link Token

Source: https://docs.finverse.com/index

Generates a token for initiating the bank linking process for data access.

```APIDOC
## POST /link/token

### Description
Generates a token required to initiate the Finverse Link UI for bank data access. This endpoint is part of the Data API.

### Method
POST

### Endpoint
/link/token

### Parameters
#### Request Body
- **redirect_uri** (string) - Required - Your registered redirect URI.
- **scopes** (array of strings) - Required - The data scopes requested (e.g., ['accounts', 'transactions']).

### Request Example
```json
{
  "redirect_uri": "https://your.app.com/callback",
  "scopes": ["accounts", "transactions"]
}
```

### Response
#### Success Response (200)
- **link_token** (string) - The token to be used with the Finverse Link UI.
- **link_id** (string) - The unique identifier for the link session.

#### Response Example
```json
{
  "link_token": "lt_abcdef12345",
  "link_id": "link_abcdef12345"
}
```
```

--------------------------------

### PAYMENT_MANDATE_STATUS_INVALID Error Response (JSON)

Source: https://docs.finverse.com/index

This error indicates that the mandate's status does not permit a payment to be made. It applies to mandate payments and endpoints like POST /payments and GET /payments/{payment_id}. Common causes include an incomplete or unauthorized mandate.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "error_code": "PAYMENT_MANDATE_STATUS_INVALID",
        "message": "The mandate has not been setup properly. Please check our documentation and try again.",
        "type": "PAYMENT_ERROR",
        "details": ""
    }
}
```

--------------------------------

### Payments API - Direct Debit Mandates

Source: https://docs.finverse.com/index

Sets up a direct debit mandate for recurring payments.

```APIDOC
## POST /mandates/link

### Description
Sets up a direct debit mandate, allowing for recurring payments. This endpoint is part of the Payments API.

### Method
POST

### Endpoint
/mandates/link

### Parameters
#### Request Body
- **amount** (number) - Required - The initial payment amount.
- **currency** (string) - Required - The currency of the payment.
- **interval** (string) - Required - The payment interval (e.g., 'monthly', 'annually').
- **description** (string) - Optional - A description for the mandate.

### Request Example
```json
{
  "amount": 50.00,
  "currency": "EUR",
  "interval": "monthly",
  "description": "Monthly subscription"
}
```

### Response
#### Success Response (200)
- **mandate_id** (string) - The unique identifier for the mandate.
- **url** (string) - The URL to redirect the user to authorize the mandate.

#### Response Example
```json
{
  "mandate_id": "mndt_xyz789uvw",
  "url": "https://link.prod.finverse.net/mandate/xyz789uvw"
}
```
```

--------------------------------

### INVALID_CLIENT_CREDENTIALS

Source: https://docs.finverse.com/index

This error occurs when client credentials fail authentication, often due to invalid API keys for the environment.

```APIDOC
## INVALID_CLIENT_CREDENTIALS

### Description
Client credentials failed authentication. This typically means the provided `client_id` or `client_secret` are invalid for the environment you are using.

### Method
POST

### Endpoint
/auth/customer/token, /link/token, /auth/token

### Request Body
- **client_id** (string) - Required - The client ID for authentication.
- **client_secret** (string) - Required - The client secret for authentication.

### Request Example
```json
{
  "client_id": "your_client_id",
  "client_secret": "your_client_secret"
}
```

### Response
#### Success Response (200)
Not applicable for error documentation.

#### Error Response (400 Bad Request)
```json
{
    "error": {
        "code": "INVALID_CLIENT_CREDENTIALS",
        "message": "The client credentials are invalid. Please verify client_id or client_secret inputs.",
        "request_id": "[request_id]",
        "type": "API_ERROR"
    }
}
```
```

--------------------------------

### Linking Errors (via Finverse Link UI)

Source: https://docs.finverse.com/index

Errors encountered during the institution linking process via the Finverse Link UI. These errors are communicated via redirect_uri and webhook_uri.

```APIDOC
## Linking errors (via Finverse Link UI)

### Description
Errors encountered during the institution linking process via the Finverse Link UI. These errors are communicated via `redirect_uri` (in the `location` header), and to the `webhook_uri` (if using webhooks).

Linking errors can be classified into 4 categories:
  * **"User action required" errors**
  * **Temporary errors**
  * **Persistent errors**
  * **"Link UI" errors**

Detailed documentation for each error category and specific error codes would follow here.
```

--------------------------------

### INCOME_ESTIMATE_NOT_FOUND Error Response

Source: https://docs.finverse.com/index

This error indicates that an income estimate could not be found for the request. It is specific to the income endpoint.

```json
{
  "error": {
    "code": 40004,
    "message": "Income estimate not found",
    "name": "INCOME_ESTIMATE_NOT_FOUND"
  }
}
```

--------------------------------

### Handle iframe messages in Parent Web App (JavaScript)

Source: https://docs.finverse.com/index

This code snippet demonstrates how to add an event listener to receive messages from a Finverse Link UI opened in an iframe. It handles 'close' and 'success' messages to manage the UI state and navigation. This is crucial for parent web applications operating in `iframe` UI mode.

```javascript
// add a listener so we get the message sent by the iframe
window.addEventListener('message', receiveMessage, false);
const receiveMessage = (message: any) => {
    if (message.data === 'close') {
        // do whatever is required to close the iframe. The linking did not succeeded due to user pressing the close button.
        setLinkOpen(false);
    }
    if (message.data === 'success') {
        // do whatever is required to close the iframe
        setLinkOpen(false);
        // Since the linking was successful display the next screen
        history.push('/user');
    }
};

```

--------------------------------

### Customer Authentication Token API

Source: https://docs.finverse.com/index

Generates a customer token for authenticating API calls. The token expires after 60 minutes and should be securely stored.

```APIDOC
## POST /auth/customer/token

### Description
Generates a customer token for authenticating with Finverse's API. This token is required for all subsequent API calls.

### Method
POST

### Endpoint
/auth/customer/token

### Parameters
#### Request Body
- **customer_app_id** (string) - Required - Your customer application ID.
- **client_id** (string) - Required - Your client ID.
- **client_secret** (string) - Required - Your client secret.
- **redirect_uri** (string) - Optional - Required for Data products. Your registered redirect URI.

### Request Example
```json
{
  "customer_app_id": "your_customer_app_id",
  "client_id": "your_client_id",
  "client_secret": "your_client_secret",
  "redirect_uri": "https://your.app.com/callback"
}
```

### Response
#### Success Response (200)
- **customer_token** (string) - The generated customer token.
- **expires_in** (integer) - The token's expiration time in seconds.

#### Response Example
```json
{
  "customer_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 3600
}
```
```

--------------------------------

### Handle LOGIN_IDENTITY_CREDENTIALS_NOT_STORED API Error

Source: https://docs.finverse.com/index

This error signifies that stored credentials required for background data refresh are missing. It is associated with the POST /login_identity/refresh endpoint and returns a 400 Bad Request status code.

```json
HTTP status code: 400 Bad Request
{
  "error": {
    "code": 40005,
    "message": "Login Identity Credentials are not stored",
    "name": "LOGIN_IDENTITY_CREDENTIALS_NOT_STORED"
  }
}
```

--------------------------------

### INCOME_ESTIMATION_NOT_SUPPORTED

Source: https://docs.finverse.com/index

Returned when income estimation is not supported by the institution.

```APIDOC
## INCOME_ESTIMATION_NOT_SUPPORTED

### Description
This error indicates that the institution does not support income estimation services.

### Method
GET

### Endpoint
- `/income`

### Parameters
None

### Request Example
None

### Response
#### Success Response (400)
This error response is returned as a 400 Bad Request.
- **error** (object)
  - **code** (integer) - 40004
  - **message** (string) - "Income estimation is not yet supported for this institution"
  - **name** (string) - "INCOME_ESTIMATON_NOT_SUPPORTED"

#### Response Example
```json
{
  "error": {
    "code": 40004,
    "message": "Income estimation is not yet supported for this institution",
    "name": "INCOME_ESTIMATON_NOT_SUPPORTED"
  }
}
```
```

--------------------------------

### BALANCE_HISTORY_UNAVAILABLE Error Response

Source: https://docs.finverse.com/index

This error indicates that balance history data is not available for the specified account ID. This could be due to account type limitations or a service-side issue.

```json
{
  "error": {
    "code": 40101,
    "message": "Balance history not available for this accountId",
    "name": "BALANCE_HISTORY_UNAVAILABLE"
  }
}
```

--------------------------------

### NOT_CANCELLABLE

Source: https://docs.finverse.com/index

Thrown when a requested resource, such as a payment link or payout, cannot be cancelled because it is currently in progress.

```APIDOC
## NOT_CANCELLABLE

### Description
The requested resource cannot be cancelled. This is typically because the payment link, payment method, or payment is currently undergoing processing and cannot be cancelled at this stage.

### Method
POST

### Endpoint
/payment_links/{id}/cancel, /payouts/{id}/cancel

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the resource to cancel.

### Response
#### Success Response (200)
Not applicable for error documentation.

#### Error Response (400 Bad Request)
```json
{
    "error": {
        "details": "Payment link cannot be cancelled (status: IN_PROGRESS)",
        "error_code": "NOT_CANCELLABLE",
        "message": "Cancellation not allowed",
        "request_id": "[request_id]",
        "type": "API_ERROR"
    }
}
```
```

--------------------------------

### INCOME_ESTIMATE_NOT_FOUND

Source: https://docs.finverse.com/index

Indicates that an income estimate could not be found for the request.

```APIDOC
## INCOME_ESTIMATE_NOT_FOUND

### Description
This error means that the requested income estimate was not found. This could be due to a lack of available data or a specific condition not being met.

### Method
GET

### Endpoint
- `/income`

### Parameters
None

### Request Example
None

### Response
#### Success Response (400)
This error response is returned as a 400 Bad Request.
- **error** (object)
  - **code** (integer) - 40004
  - **message** (string) - "Income estimate not found"
  - **name** (string) - "INCOME_ESTIMATE_NOT_FOUND"

#### Response Example
```json
{
  "error": {
    "code": 40004,
    "message": "Income estimate not found",
    "name": "INCOME_ESTIMATE_NOT_FOUND"
  }
}
```
```

--------------------------------

### Handle PAYOUT_REJECTED Errors in JSON

Source: https://docs.finverse.com/index

This JSON response signifies that a payout was rejected by the recipient's institution, potentially due to invalid account details or a frozen account. This applies to payouts, and the relevant endpoint is POST /payouts/scheduled.

```json
{
    "error": {
        "error_code": "PAYOUT_REJECTED",
        "message": "Payout rejected",
        "type": "PAYMENT_ERROR",
        "details": "Payout rejected by the receiving institution. Please verify that the recipient's account details are correct and try again, or contact the recipient to confirm their account is able to receive payment."
    }
}
```

--------------------------------

### Handle PAYMENT_MANDATE_AUTHORIZATION_INCOMPLETE Error

Source: https://docs.finverse.com/index

This error indicates that a debit authorization for a mandate payment cannot be completed due to missing information, such as customer consent or sender details. It is specific to mandate payments and the mandate authorization endpoint. The error details will specify the missing information required.

```json
{
    "error": {
        "error_code": "PAYMENT_MANDATE_AUTHORIZATION_INCOMPLETE",
        "message": "Mandate authorization is incomplete",
        "type": "PAYMENT_ERROR",
        "details": "We are missing the following information needed to authorize this Mandate: consent"
    }
}
```

--------------------------------

### ACCOUNT_NOT_FOUND Error Response

Source: https://docs.finverse.com/index

This error signifies that the specified account ID could not be found. This can occur if the account does not exist, has been deleted, or is inaccessible. It is relevant for endpoints that require an account ID.

```json
{
    "error": {
        "error_code": "ACCOUNT_NOT_FOUND",
        "message": "account_id cannot be found. Resource does not exist, has been deleted, or is no longer accessible.",
        "request_id": "{unique_id}",
        "type": "API_ERROR"
    }
}
```

--------------------------------

### User Action Required Errors

Source: https://docs.finverse.com/index

This section outlines specific error codes that occur when Finverse requires additional end-user actions or inputs to complete institution authentication. It includes common issues like invalid credentials, locked accounts, or MFA requirements, and provides guidance on how to resolve them.

```APIDOC
## User Action Required Errors

### Description
These errors occur when Finverse requires additional end-user actions or inputs to complete Institution authentication. They indicate issues such as invalid credentials, locked accounts, or Multi-Factor Authentication (MFA) requirements.

### Resolution Steps
*   The end-user may need to log in directly to their Institution to re-enable access to their account (e.g., reset password, unlock account).
*   To retry linking, the end-user should complete the `/relink` flow.

### Error Codes and Details

| Error Code (or `error`)
| Error Description (or `error_description`)
| Error Details (or `error_details`)
| Retryable in Refresh Flow
|---|---|---|---|
| `account_locked` | Your account has been locked | Please log in directly on your institution's site to unlock your account | NO
| `credentials_invalid` | The credentials you entered were incorrect | Your account may get locked out after several unsuccessful attempts | NO
| `credentials_not_found` | Could not find stored credentials | We do not have any stored credentials for this account. Please log in again to refresh your data. | NO
| `date_of_birth_invalid` | The Date of Birth you provided is incorrect. | The Date of Birth you provided is incorrect. Please try again. | YES
| `login_approval_rejected` | Login request rejected | Your institution sent a login request to your mobile phone app or number, but the request was rejected. | YES
| `login_approval_timeout` | Login approval not received | Your institution sent a login request to your mobile phone app or number, but did not receive a reply. | YES
| `mfa_not_supported` | Could not log in to institution | We cannot log in to your institution because your bank requires a 2FA/OTP input which we do not currently support. Please log in directly to your institution's site to edit your 2FA/OTP settings, then try again. | NO
| `online_access_disabled` | Online access disabled | We cannot connect to your institution because online (web) login is disabled. Please log in directly on your institution’s site or app and enable online login, then try again. | NO
| `online_access_disabled (Vietcombank)` | VCB Digibank web login disabled | We cannot connect to your institution because VCB Digibank web login is disabled. To unlock access, please log in to VCB's Mobile App, go to Settings (General Settings -> Login Settings), turn OFF 'Setting VCB Digibank login on web', then try again. | NO
| `online_access_disabled _contact_bank_support` | Online access disabled | We cannot connect to your institution because online (web) login is disabled. Please contact your institution’s customer support service to enable online login, then try again. | NO
| `otp_invalid` | The OTP you provided is incorrect. | The OTP you provided is incorrect. Please try again. | YES
| `otp_timeout` | One time password not entered | The one time password sent to your mobile phone expired. Please try again. | YES
| `otp_expired` | One time password expired due to another login attempt | The one time password has expired, please try again. | YES
| `password_update_required` | Password update required | Your institution requires you to update your password. Please log in directly on your institution's site to change your password, then try again. | NO
| `phone_number_invalid` | Phone number is invalid | The phone number you entered is incorrect or in an invalid format. Please try again. | NO
| `security_device_error` | Security device not registered | Please register your security device on your institution's site in order to log in to your account. | NO
| `username_rejected` | Could not log in to institution | The username is rejected by your institution. Please verify your username. You may also need to log in directly on your institution's site or app to enable online (web) login, then try again. | NO
| `username_rejected` | Could not log in to institution | The username is rejected by your institution. Please contact your institution to enable online login, then try again. | NO
| `user_action_required` | Action required on institution's site | Please log in directly on your institution's site to ensure online access is enabled, then try again. | NO
| `user_action_timeout` | Login timeout | Your login attempt timed-out during 2FA verification. Please try again. | YES
| `user_action_invalid` | Invalid user input | The institution reported that your input was invalid. Please try again. | YES
```

--------------------------------

### STATEMENT_NOT_FOUND Error Response

Source: https://docs.finverse.com/index

This error is returned when a specific statement ID cannot be found. This implies the statement does not exist, has been removed, or is inaccessible. It is relevant for fetching individual statements.

```json
{
    "error": {
        "error_code": "STATEMENT_NOT_FOUND",
        "message": "statement_id cannot be found. Resource does not exist, has been deleted, or is no longer accessible.",
        "request_id": "{unique_id}",
        "type": "API_ERROR"
    }
}
```

--------------------------------

### API Error: IDEMPOTENCY_KEY_IN_USE (JSON)

Source: https://docs.finverse.com/index

This JSON structure represents an `IDEMPOTENCY_KEY_IN_USE` error returned by the Finverse API. It indicates that an idempotency key has been reused with a request that does not match the original. This is common in payment-related endpoints.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "details": "",
        "error_code": "IDEMPOTENCY_KEY_IN_USE",
        "message": "The idempotency key provided is currently being used in another request. This occurs if your integration is making duplicate requests simultaneously. Please check our documentation and try again.",
        "request_id": "{request_id}",
        "type": "API_ERROR"
    }
}

```

--------------------------------

### ACCOUNT_NOT_FOUND

Source: https://docs.finverse.com/index

This error occurs when a specified account ID cannot be found for retrieval.

```APIDOC
## ACCOUNT_NOT_FOUND

### Description
This error is returned when an account ID provided in the request does not exist, has been deleted, or is otherwise inaccessible.

### Method
GET

### Endpoint
- `/accounts/{account_id}`
- `/account_numbers/{account_id}`
- `/balance_history/{accountId}`
- `/transactions/{account_id}`

### Parameters
#### Path Parameters
- **account_id** (string) - Required - The unique identifier of the account.

### Request Example
None

### Response
#### Success Response (400)
This error response is returned as a 400 Bad Request.
- **error** (object)
  - **error_code** (string) - "ACCOUNT_NOT_FOUND"
  - **message** (string) - A message indicating the account ID was not found.
  - **request_id** (string) - A unique identifier for the request.
  - **type** (string) - "API_ERROR"

#### Response Example
```json
{
    "error": {
        "error_code": "ACCOUNT_NOT_FOUND",
        "message": "account_id cannot be found. Resource does not exist, has been deleted, or is no longer accessible.",
        "request_id": "{unique_id}",
        "type": "API_ERROR"
    }
}
```
```

--------------------------------

### Handle PAYMENT_TEMPORARY_ERROR Errors in JSON

Source: https://docs.finverse.com/index

This JSON response indicates a temporary payment error, often due to the payment system timing out or being temporarily unavailable. This affects any payment, mandate, or payout endpoint. Please try again later.

```json
{
    "error": {
        "error_code": "PAYMENT_TEMPORARY_ERROR",
        "message": "Temporary error",
        "type": "PAYMENT_ERROR",
        "details": "Payment service is temporarily unavailable. Please try again later. (Error details: {gateway_error_code} {gateway_error_description})"
    }
}
```

--------------------------------

### PAYMENT_REJECTED

Source: https://docs.finverse.com/index

Indicates that a payment was rejected by the sender's financial institution, potentially due to insufficient funds or a closed account.

```APIDOC
## POST /payments

### Description
Initiates a new payment.

### Method
POST

### Endpoint
/payments

### Parameters
#### Request Body
- **amount** (number) - Required - The amount to pay.
- **currency** (string) - Required - The currency of the payment.
- **recipient_account** (object) - Required - Details of the recipient's account.
  - **account_number** (string) - Required - The recipient's account number.
  - **sort_code** (string) - Optional - The recipient's sort code.

### Request Example
```json
{
  "amount": 50.00,
  "currency": "USD",
  "recipient_account": {
    "account_number": "123456789"
  }
}
```

### Response
#### Success Response (201 Created)
- **payment** (object) - Information about the created payment.

#### Response Example
```json
{
  "payment": {
    "id": "pay_456",
    "status": "INITIATED"
  }
}
```

## GET /payments/{payment_id}

### Description
Retrieves details for a specific payment.

### Method
GET

### Endpoint
/payments/{payment_id}

### Parameters
#### Path Parameters
- **payment_id** (string) - Required - The ID of the payment to retrieve.

### Response
#### Success Response (200)
- **payment** (object) - Detailed information about the payment.

#### Response Example
```json
{
  "payment": {
    "id": "pay_456",
    "status": "REJECTED",
    "failure_reason": "Insufficient funds"
  }
}
```

## Error: PAYMENT_REJECTED

### Description
Payment rejected by sender's institution. This can occur if the sender's account is closed or has insufficient funds.

### Common causes
- Sender account closed.
- Sender account has insufficient funds.

### Response Example (400 Bad Request)
```json
{
    "error": {
        "error_code": "PAYMENT_REJECTED",
        "message": "Payment rejected",
        "type": "PAYMENT_ERROR",
        "details": "Payment rejected by your payment method. Please verify that you have sufficient funds available and try again, or contact your payment method's customer support. (Error details: {gateway_error_code} {gateway_error_description})"
    }
}
```
```

--------------------------------

### IDENTITY_UNAVAILABLE Error Response

Source: https://docs.finverse.com/index

This error occurs when no identity information can be retrieved for the requested Login Identity. Similar to other unavailability errors, it might be due to user type limitations or a service issue.

```json
{
  "error": {
    "error_code": "IDENTITY_UNAVAILABLE",
    "message": "No identity information is associated with the requested Login Identity. We may not be able to retrieve identity for this user type, or there may have been an error retrieving identity for this user (please review product_status for details).",
    "request_id": "{unique_id}",
    "type": "API_ERROR"
  }
}
```

--------------------------------

### Handle INVALID_CLIENT_CREDENTIALS Errors in API Requests

Source: https://docs.finverse.com/index

The INVALID_CLIENT_CREDENTIALS error indicates that the client credentials provided for authentication are incorrect or not valid for the target environment. This typically occurs when API keys or secrets are mistyped or belong to a different environment (e.g., using test keys in production). Ensure the `client_id` and `client_secret` are accurate for the environment you are accessing. Relevant endpoints include token acquisition.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "code": "INVALID_CLIENT_CREDENTIALS",
        "message": "The client credentials are invalid. Please verify client_id or client_secret inputs.",
        "request_id": "[request_id]",
        "type": "API_ERROR"
    }
}
```

--------------------------------

### Handle LOGIN_IDENTITY_ERROR_STATE API Error

Source: https://docs.finverse.com/index

This is a general error for other Login Identity-related issues, indicating an unspecified error state. It is returned with a 400 Bad Request status code and the specific message depends on the underlying cause.

```json
HTTP status code: 400 Bad Request
{
  "error": {
    "code": 40009,
    "message": "Error state",
      // message depends on the underlying error
    "name": "LOGIN_IDENTITY_ERROR_STATE"
  }
}
```

--------------------------------

### STATEMENT: ERROR

Source: https://docs.finverse.com/index

A general error that can occur when retrieving a specific statement.

```APIDOC
## STATEMENT: ERROR

### Description
This is a general error response indicating an issue occurred while attempting to retrieve a specific statement from the service.

### Method
GET

### Endpoint
- `/statements/{statement_id}`

### Parameters
#### Path Parameters
- **statement_id** (string) - Required - The unique identifier of the statement.

### Request Example
None

### Response
#### Success Response (400)
This error response is returned as a 400 Bad Request.
- **Appcode** (integer) - 500
- **ErrorText** (string) - "Error getting statement from service"

#### Response Example
```json
{
  "Appcode": 500, 
  "ErrorText": "Error getting statement from service"
}
```
```

--------------------------------

### Handle UNSUPPORTED_GRANT_TYPE Errors in Authentication

Source: https://docs.finverse.com/index

The UNSUPPORTED_GRANT_TYPE error indicates that an invalid or unsupported value was provided for the `grant_type` parameter during an authentication request. Each authentication endpoint may support specific grant types (e.g., `authorization_code`, `refresh_token`). Verify that the `grant_type` used is documented as valid for the specific endpoint being called, such as `/auth/customer/token`, `/link/token`, or `/auth/token`.

```json
HTTP status code: 400 Bad Request
{
    "error": {
        "error_code": "UNSUPPORTED_GRANT_TYPE",
        "message": "Invalid grant_type. Please review allowed parameter values in API documentation.",
        "request_id": "[request_id]",
        "type": "API_ERROR"
    }
}
```

--------------------------------

### BALANCE_HISTORY_UNAVAILABLE

Source: https://docs.finverse.com/index

Returned when balance history data is not available for a specific account.

```APIDOC
## BALANCE_HISTORY_UNAVAILABLE

### Description
This error indicates that balance history data cannot be retrieved for the specified account ID.

### Method
GET

### Endpoint
- `/balance_history/{accountId}`

### Parameters
#### Path Parameters
- **accountId** (string) - Required - The unique identifier of the account.

### Request Example
None

### Response
#### Success Response (400)
This error response is returned as a 400 Bad Request.
- **error** (object)
  - **code** (integer) - 40101
  - **message** (string) - "Balance history not available for this accountId"
  - **name** (string) - "BALANCE_HISTORY_UNAVAILABLE"

#### Response Example
```json
{
  "error": {
    "code": 40101,
    "message": "Balance history not available for this accountId",
    "name": "BALANCE_HISTORY_UNAVAILABLE"
  }
}
```
```
Tokens:
Raw