Dashboard
Guides
GuidesAPI Reference

Checking payment eligibility

Suggest Edits

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.

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 --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"
  },
}

The sender_account object contains two fields:

  • holder_id: The RUT (Rol Único Tributario) of the account holder
  • institution_id: The ID 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.

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

{
    "eligible_payment": true,
    "error": null
}

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

{
    "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:

{
  "amount": 1000,
  "currency": "clp",
  "metadata": {
    "order": "#987654321"
  },
  "customer_email": "[email protected]",
  "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 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.

🚧

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.

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.
{
  "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"
  }
}
  1. 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.

{
  "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"
  }
}
  1. Minimum amount limit error: Fintoc checks if the amount is lower thant the minimum allowed by the institution. 

{
  "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"
  }
}
  1. Maximum amount limit error: Fintoc checks if the amount is lower thant the minimum allowed by the institution.

{
  "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.

Updated 9 days ago