> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fintoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Checking payment eligibility

Pre-validating a payment intent helps reduce the chance of payments failing due to transfer limits. There are two ways to check a payment's eligibility:

* Using the `payment_intents/check_eligibility` endpoint to check eligibility before showing a user the accepted payment methods.
* Including a `sender_account` object when creating a Checkout Session or Payment Intent to check when a user selects Fintoc as a payment method.

When creating a payment intent, you can include a `sender_account` object in your request. This object allows you to specify the sender's account details, enabling our system to perform more accurate validations based on general transfer limits and previous transactions through Fintoc. **This feature is only available in Chile**.

<Danger>
  **This validation only checks payments made through Fintoc.**

  If you’ve already received payments from users on this recipient account, we recommend not using this feature as it could mistakenly block valid payments.
</Danger>

## Using the `payment_intents/check_eligibility` endpoint

If you want to check a payment's eligibility before showing a user the accepted payment methods, you can use the following endpoint:

```curl cURL theme={null}
curl --request POST \
     --url https://api.fintoc.com/v1/payment_intents/check_eligibility \
     --header 'Authorization: sk_test_9c8d8CeyBTx1VcJzuDgpm4H' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "amount": 1000,
  "currency": "clp",
  "sender_account": {
      "holder_id": "195669317",
      "institution_id": "cl_banco_estado"
  },
  "recipient_account": {
     "holder_id": "774981128",
     "institution_id": "cl_banco_estado",
     "type": "checking_account",
     "number": "1251353"
  }
}
```

The `sender_account` object contains two fields:

* `holder_id`: The RUT (Rol Único Tributario) of the account holder
* `institution_id`: The [ID](/v2023-11-15/docs/payments/overview-payment-initiation/payment-initiation-countries-and-institutions#available-sender-banks) of the bank institution

Mixing these fields will help you validate certain limits:

* If you only send the `institution_id` and no `holder_id`, Fintoc will only validate bank-specific limits for maximum and minimum transfer amounts.
* If you send both, Fintoc will perform all validations for the payment intent.

If the payment is eligible, this endpoint will respond with the following object:

```json JSON theme={null}
{
    "eligible_payment": true,
    "error": null
}
```

If it isn't valid it will respond with one of the error responses like this:

```json JSON theme={null}
{
    "eligible_payment": false,
    "error": {
      "type": "new_contact_error",
      "message": "The amount exceeds the maximum amount permitted for new contacts. For #{institution_name}, the maximum permissible amount is $250,000. This restriction ends at 2024-08-20T16:08:28Z",
      "code": "new_contact_maximum_amount_limit_error",
      "param": "amount",
      "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}
```

## Including a `sender_account` object

When making a POST request to creating a Checkout Session, include the `sender_account` object in your JSON payload. Here's an example:

```json theme={null}
{
  "amount": 1000,
  "currency": "clp",
  "metadata": {
    "order": "#987654321"
  },
  "customer_email": "customer@example.com",
  "payment_method_options": {
    "payment_intent": {
      "sender_account": {
        "holder_id": "12345678-9",
        "institution_id": 'cl_banco_estado'
      }
    }
  },
}

```

The `sender_account` object contains two fields:

* `holder_id`: The RUT (Rol Único Tributario) of the account holder
* `institution_id`: The [ID](/v2023-11-15/docs/payments/overview-payment-initiation/payment-initiation-countries-and-institutions#available-sender-banks) of the bank institution

Mixing these fields will help you validate certain limits:

* If you only send the `holder_id` and no `institution_id`, Fintoc will use general limits for new contacts allowing more payments to go through without incorrectly canceling any.
* If you only send the `institution_id` and no `holder_id`, Fintoc will only validate bank-specific limits for maximum and minimum transfer amounts.
* If you send both, Fintoc will perform all validations for the payment intent.

<Warning>
  **Use the Same Holder ID**

  When setting up the widget to pre-fill a username, use the same holder\_id as for pre-validating payments. This ensures consistency and helps prevent payment failures.
</Warning>

## Validation Process

When you include the `sender_account` information, our system performs several checks to validate the payment intent:

1. **Institution-specific limits**: We check if the payment amount is within the allowed limits for the specified institution.
2. **New contact limits**: For first-time transfers or transfers within 24 hours of the first transfer, institutions apply stricter limits.
3. **Maximum transfer amounts**: We ensure the payment doesn't exceed the maximum allowed transfer amount for the specified bank.

## Error Responses

If a validation fails, you'll receive one of the following error responses:

1. **New contact maximum amount limit error**: Fintoc first checks if the `holder_id` has made a transfer. If not, it then checks if the amount exceeds the institution's limit.

```json theme={null}
{
  "error": {
    "type": "new_contact_error",
    "message": "The amount exceeds the maximum amount permitted for new contacts. For #{institution_name}, the maximum permissible amount is $250,000. This restriction ends at 2024-08-20T16:08:28Z",
    "code": "new_contact_maximum_amount_limit_error",
    "param": "amount",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

```

2. **New contact payment number limit error**: Fintoc first checks if the `holder_id` has made their first transfer during the same day. If they have, it then checks if the institution allows for more than one transfer to a new contact.

```json theme={null}

{
  "error": {
    "type": "new_contact_error",
    "message": "The maximum number of transfers for new contacts in #{institution_name} was reached. This restriction ends at 2024-08-20T16:08:28Z",
    "code": "new_contact_payment_number_limit_error",
    "param": "sender_account",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

```

3. **Minimum amount limit error**: Fintoc checks if the amount is lower thant the minimum allowed by the institution.

```json theme={null}

{
  "error": {
    "type": "amount_error",
    "message": "The amount is lower than the minimum amount permitted for payments by #{institution_name}. Please enter an amount greater than $1000.",
    "code": "minimum_amount_limit_error",
    "param": "amount",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

```

4. **Maximum amount limit error**: Fintoc checks if the amount is lower thant the minimum allowed by the institution.

```json theme={null}

{
  "error": {
    "type": "amount_error",
    "message": "The amount exceeds the maximum amount permitted for payments by #{institution_name}. Please enter an amount less than $70000000.",
    "code": "maximum_amount_limit_error",
    "param": "amount",
    "doc_url": "https://docs.fintoc.com/reference/errors"
  }
}

```

## Best Practices

1. Always include the `sender_account` information when creating a Checkout Session to ensure the most accurate validations.
2. Handle error responses gracefully in your application, providing clear feedback to your users about why a payment couldn't be processed.
3. Make adjustments to your order so users are able to pay. These could be changing the payment amount if possible or setting up reminders for future payments.