API Reference

How to handle the new status PENDING_VALIDATION on loans?

👋 Hello there!

Defacto just introduced a new status on the loans: PENDING_VALIDATION. This means some loans will be validated manually by the Defacto team within 2 business days. Our goal is to validate all PENDING_VALIDATION the same day as they were requested.

Our goal is to maximize the instant and automated validation of the loans in order to provide the best UX (aiming at 95%). In a certain set of cases, validation will be necessary (ie. fraud prevention)

see updated loan state machine documentation

The goal is to support this change on partners’ end by the end of June 2023.

What does NOT change?

Behavior on automatically approved or automatically declined loans

  • automatically approved âžœ status of the loan in the response is VALIDATED, SCHEDULED or INITIATED
  • automatically declined âžœ API response is 400 error, status of the loan in the response is DECLINED

What is the impact on the UX?

As a borrower, my loan request could be pending validation for up to 2 days, before orchestration

  • I need to be aware of this situation
  • I need to be updated when it’s validated / if it’s declined and why

What is the impact on your product?

Additional version of the confirmation screen at the end of loan request flow for this new use case

  • example of Defacto UX
example of Defacto UX

example of Defacto UX

New pending_validation label on the financing view

Add new label for the PENDING_VALIDATION status

  • Translations Defacto uses
    • FR: en cours de validation
    • EN: pending validation
    • ES: en proceso de validación
    • DE: in Validierung

Edit and cancel loan can be available when the loan is pending validation (if already implemented)

  • No change required on these features.
  • Just need to make the buttons available when loan.status === 'PENDING_VALIDATION'

Communicate approval / denial by email (or notification on your app) to the customer

  • When loan is declined
    • Subscribe to webhook Loan.DECLINED
    • When you receive the webhook, send email if the loan status in your DB is PENDING_VALIDATION
  • When loan is approved
    • Subscribe to webhook Loan.TO_VALIDATE (or Loan.VALIDATED which is the next one and usually happens a few ms later)
    • On webhook reception, notify user if the loan status in your DB is PENDING_VALIDATION

Update loan status in your DB

  • No change should be required because loans in PENDING_VALIDATION status will be returned by the POST /loans API. This never happens in the background so webhooks are not adding value here.

Fine-tuning possibilities

  • On frontend, add tooltip for the new pending_validation label to explain that the validation takes up to 2 business days
  • For the edit feature, when the loan is pending validation, in addition to the field already editable, make it possible to edit amount and to_pay_at