Sign in
latestSwagger 2.02026-08-2181213270.0 KB

0a9c1f8784f2

Loan

Request a new loan.

If you haven't visited the guide: how to make your first loan? we recommend you to visit it first.

Key Parameters: As the loan request is a complex operation, it has many parameters. The most important ones are:

  • borrower
  • amount
  • to_pay_at
  • to_repay_at
  • salt_id: ⚠️ In order to avoid accidental duplication in requested loans we recommend you to set the <code>salt_id</code> parameter to a unique value for each request.

Timeout after: 30 seconds (status code will be 504 in such a case)

For loan related to invoices, at the moment, we don't support multiple-invoices financing.

  • You can either request a loan for an existing invoice, in which case you should set <code>invoice_ids</code>.
  • Or you can create the invoice and request a loan with a single call to this API.
  • If you pass an invoice in <code>invoices</code>, the base64-encoded value of the PDF of the invoice is required under the <code>document</code> property. You can for example use <a href='https://base64.guru/converter/encode/pdf'>base64guru</a>.

Behavior

When you send this API request, our system will:

  1. Create a loan (you will get its id in the response)
  2. Start evaluating your loan request. Here you should choose between 2 behaviors: a. (default) Getting the decision asynchronously. The status of the returned loan will always be PENDING_VALIDATION. Webhooks will tell you if it goes approved or declined. In can happen from a few seconds after the request up to a few days after it. b. Getting the decision synchronously. This is recommended if this endpoint is called directly from a frontend. To activate this option, set <code>"wait_for_validation": true</code>. In such a case, the returned loan status will be: i. if the loan is automatically accepted by Defacto -> the status of the loan will be TO_VALIDATE if you set <code>"auto_validate": false</code>, or one of: VALIDATED, SCHEDULED, INITIATED, TO_REPAY. Fore more information on this, see section "Why the status of the loan in the response vary?" below. ii. if the loan is automatically declined by Defacto -> the status of the loan will be DECLINED and the <code>denial_reason</code> will be set. iii. if the loan validation takes longer than 20s (max response time is 2 business days) -> the status of the loan will be PENDING_VALIDATION. It is therefore very important to think about how to communicate with the end-user. While its not an issue for validated loans, it can get frustrating for declined loans. Users must be alerted of loans that gets declined few hours after their request.
  3. If the loan is accepted by Defacto, it will then move forward and its status will be updated regularly. Subscribe to webhooks to get live notifications of this.

Why the status of the loan in the response vary? The status vary because our system is asynchronous and the steps moving the loan forward may be executed immediately or not depending on the current load on our system.

What should I do if the status of the loan is TO_VALIDATE? TO_VALIDATE means that Defacto accepted the loan as is. The next step is to get the user consent for this loan offer. When obtained, call <code>POST /loan/{loan_id}/validate</code>.

Most of the time the user does not want to do this manual consent. To avoid requiring this, you can set <code>"auto_validate": true</code> in your request. When setting this option, please ensure that its very explicit for the user that the loan may be automatically accepted and paid so that they won't be able to cancel it. Users can cancel the loan only before Defacto sends the money to the beneficiary, which happens 24 to 48 hours before the <code>"to_pay_at"</code> date.

post/loans

Request body

amountinteger required

Loan amount in cents. Maximum: 200,000 €.

auto_validateboolean

Automatically validate the loan

borrower_financial_product_idstring uuid nullable

Specify your borrower financial product to use. This field is required only if you propose multiple financial products (which is rare)

currency'EUR' | 'GBP'

ISO 4217 currency code.

installment_plan_type'INSTALLMENTS' | 'IN_FINE'

Type of installment plan to create for the loan. Only 'INSTALLMENTS' or 'IN_FINE' possible for now (see 'installments' to specify a custom installment plan).

invoice_idsstring[]

Invoices already uploaded that the loan should finance

loan_to_referencesstring[]

References in the transfer of the loan payment, on the account receiving the money

loan_type'CREDIT_CARD_FINANCING' | 'FUNDING_OBLIGATION_CONSOLIDATION' | 'INVENTORY_FINANCING' | 'INVOICE_BASED_FINANCING' | 'WALLET_FINANCING'

[DEPRECATED] if you are using this field, please switch to borrower_financial_product_id.Type of loan to request. For example, INVOICE_BASED_FINANCING to finance invoices. Depending on the value of this field, another field with a name matching this value may be to complete. For example, for INVOICE_BASED_FINANCING either invoice_ids or invoices should be set. For WALLET_FINANCING or CREDIT_CARD_FINANCING, no specific field needs to be set. For INVENTORY_FINANCING, at least one document must be provided in the documents field.

metadataobject nullable

This object is yours, it enables you to add custom data.

notification_emailsstring[]
purpose'CONTRACTUAL_LOAN_REPAYMENT' | 'CONTRACTUAL_RECOLLECTION' | 'PREFERED_LOAN_REPAYMENT' | 'PREFERED_RECOLLECTION_PLAN' | 'null' nullable
repayment_from_referencesstring[]

References in the transfer of the loan repayment, on the account sending the money

salt_idstring nullable

Unique key to ensure idempotency of the creation request.

to_pay_atstring date-time required

Loan disbursement estimated date

to_repay_atstring date-time required

Loan reimbursement estimated date

wait_for_validationboolean

Configure the behaviour of the endpoint. When false, the returned loan will always be PENDING_VALIDATION or DECLINED, never accepted right away. When true (recommended if called from a frontend), the API will wait up to 30 seconds to get the final decision for the financing, so the returned loan may be approved right away.

Response

Created