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.

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

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. To opt-in to this validation, send the institution_id.
2. New contact limits: For first-time transfers or transfers within 24 hours of the first transfer, institutions apply stricter limits. For Direct Payments, this validation will occur by looking at previous payments by the same user. If your users have paid outside of Fintoc's payment flow, we highly suggest you opt-out of this feature. To opt-in to this validation, send the holder_id and institution_id.
3. Maximum transfer amounts: We ensure the payment doesn't exceed the maximum allowed transfer amount for the specified bank. To opt-in to this validation, send the holder_id.

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 payment before and when. 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 this institution, the maximum permissible amount is $[amount]. This restriction ends at [timestamp]",
    "code": "new_contact_maximum_amount_limit_error"
  }
}

2. New contact payment number limit error: Fintoc first checks if the holder_id has made their first payment 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 was reached. This restriction ends at [timestamp]",
    "code": "new_contact_payment_number_limit_error"
  }
}

3. 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"
  }
}

4. 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.