post_loans

post

https://api-sandbox.getdefacto.com/loans

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 salt_id 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 invoice_ids.
Or you can create the invoice and request a loan with a single call to this API.
If you pass an invoice in invoices, the base64-encoded value of the PDF of the invoice is required under the document property. You can for example use base64guru.

Behavior

When you send this API request, our system will:

Create a loan (you will get its id in the response)
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 "wait_for_validation": true. 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 "auto_validate": false, 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 denial_reason 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.
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 POST /loan/{loan_id}/validate.

Most of the time the user does not want to do this manual consent. To avoid requiring this, you can set "auto_validate": true 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 "to_pay_at" date.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

amount

integer

required

Loan amount in cents

attachments

array of objects

Attach context and/or files to your loan request. Depending on the type of loan you are requesting some extra context may be required. Check with the Defacto team if you are not sure of which to share. You can provide additional structured data with the attachment you attach. The field to fulfill is the one corresponding to the specified attachment_type. For example if you use attachment_type = credit_card_expenses you should fulfill the attachment.credit_card_expenses object.

attachments

auto_validate

boolean

Defaults to false

Automatically validate the loan

borrower

object | null

Entity legally contracting the loan

borrower_financial_product_id

uuid | null

Defaults to null

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

currency

string

enum

Defaults to EUR

ISO 4217 currency code.

Allowed:

documents

array of objects

Attach documents to your loan request. Depending on the type of loan you are requesting some documents may be required. Check with the Defacto team if you are not sure of which documents to share. You can provide additional structured data with the document you attach. The field to fulfill is the one corresponding to the specified document_type. For example if you use document_type = invoice you should fulfill the document.invoice object.

documents

installment_plan_type

string

enum

Defaults to 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).

Allowed:

installments

array of objects | null

Defaults to null

List of installments to create for the loan. Only used when installment_plan_type is set to 'INSTALLMENTS'. installments must respect that 1) the sum of installments equals the amount of the loan and 2) the last installment date is equal to 'to_repay_at'.

installments

invoice_ids

array of uuids

Invoices already uploaded that the loan should finance

invoice_ids

invoices

array of objects

length ≤ 1

Invoices to create that the loan finances

invoices

loan_to

object

required

Bank account receiving the money of the loan

loan_to_references

array of strings

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

loan_to_references

loan_type

string

enum

Defaults to INVOICE_BASED_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.

Allowed:

metadata

object | null

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

notification_emails

array of strings

notification_emails

repayment_from_references

array of strings

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

repayment_from_references

salt_id

string | null

Defaults to null

Unique key to ensure idempotency of the creation request.

to_pay_at

date-time

required

Loan disbursement estimated date

to_repay_at

date-time

required

Loan reimbursement estimated date

wait_for_validation

boolean

Defaults to false

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

201