Pre-validating Payments

Pre-validating a payment intent helps reduce the chance of payments failing due to transfer limits. 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.

Including a sender_account object

When making a POST request to create a payment intent, include the sender_account object in your JSON payload. Here's an example:

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

The institution_id is optional. If you don't include it, Fintoc will use general limits, allowing more payments to go through without incorrectly canceling any.

🚧

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. Bank-specific limits: We check if the payment amount is within the allowed limits for the specified bank.
2. New contact limits: This is only available when Fintoc collects payments on your behalf. Direct Payments do not support validation for new contact limits, as Fintoc does not have access to the merchant's bank account information to validate.
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. Minimum amount limit error: Fintoc checks if the amount is lower thant the minimum allowed by the institution.

{
  "error": {
    "type": "amount_limit_error",
    "message": "The amount is lower than the minimum amount permitted for payments by the institution. Please enter an amount greater than $[amount].",
    "code": "minimum_amount_limit_error"
  }
}

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

{
  "error": {
    "type": "amount_limit_error",
    "message": "The amount exceeds the maximum amount permitted for payments by the institution. Please enter an amount less than $[amount].",
    "code": "maximum_amount_limit_error"
  }
}

Best Practices

1. Always include the sender_account information when creating a payment intent 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.