This guide will walk you through the creation of your first loan with the Defacto REST API.

📘

There is no real money involved in the sandbox environment!

This guide walks you through the creation of your first loan with the Defacto API.

For this first loan, you will use our sandbox. In this environment, there is no real money involved! You can therefore make as many tests as you want, you cannot send real money to the wrong person.

When you will be confident in your integration, get in touch with us to get access to real money.

In this guide, we assume that you already followed the Authentication section and are able to authenticate with our API.

In this guide, to make you first loan you will:

  • Create a borrower
  • Get the PDF of the contract of the borrower
  • Generate an invoice
  • Request a loan for this invoice
  • Review the loan conditions that we offer
  • Validate the loan conditions
  • Follow the status of the loan, its payment and repayment

📘

All API requests can be done directly from our documentation

To do so, take a look at one endpoint's documentation, fill-in the request parameters and click "Try it".

An example is given in Authentication with the /hello endpoint.

1. Creating a first borrower

Defacto can only lend money to borrowers who accepted our terms and conditions (T&Cs).

If your company is the legal borrower of all the loans that you do on Defacto, you can ignore this step.

Otherwise, you should continue to follow this section. Depending on your use case, the borrowers of the loans that you will do will either:

  • always be the buyers of the invoices that you finance with Defacto
  • always be the sellers of the invoices that you finance with Defacto
  • sometimes be the buyer and sometimes the seller. When you are in this case, you usually use Defacto for more than one of your products.

If you are not sure about your use case here, feel free to get in touch with intercom at the bottom right corner of this page.

Keep this information in mind! You will always need to register the borrowers prior to requesting loans.

To ease testing, we provide a business generation API endpoint at POST /sandbox/business-generator. It creates a fake business that you can then use as a borrower. For this example, set the is_borrower parameter to true.

Send a POST /borrowers request to create the borrower with the data from the business generator.

If you want to use your own data, make sure to fill the signed_at parameter. It is with this field that you tell Defacto that the borrower approved our T&Cs. If you don't fill it, we will not create a credit line for this borrower, thus preventing loan applications. In such a case, you would need to use POST /borrower/{borrower_id}/sign.

🎉 Your first borrower is registered 🎉

📘

Getting the contract of the borrower

A link to the contract of the borrower is given in the response of both the borrower creation request and GET /borrowers endpoint.

Be careful, this is a temporary link that you cannot store into your database.

2. Generating an invoice

To create your first loan, you will need an invoice to finance. Please note that the creation of invoice does not depend on the borrower. You can create first an invoice before creating the borrower.

📘

Get testing data with our fake invoice generator

You can use our invoice generator at POST /sandbox/invoice-generator.

If you created a borrower at the previous step, the seller of the invoice must be the borrower.
Otherwise, you should be the seller.

Make sure you set this when you create the fake invoice.

After that you can request your first loan!

3. Requesting your first loan

Use the POST /loans endpoint to do so. Quick recommendations to help you build a correct request:

  • The to_account of the loan should be the same as the to_account of the invoice
  • The to_pay_at and to_repay_at dates will be ignored and the loan will both be paid and repaid immediately after your approval (this will be discussed in more detail later)
  • Don't set invoice_ids but only invoices with the previously generated invoice

Execute the request to create your first loan.

4. Accepting the loan conditions

The loan creation request will return the proposed loan conditions, including the interest rate, the borrower, beneficiary, the dates of payment, repayment and so on.

If you agree with the conditions, you can validate it. Use POST /loan/{loan_id}/validate to do so.

For your next API requests, you will not have to validate the loan conditions manually. We wanted you to do it at least once. On loan creation, you can automatically validate them by setting "auto_validate": true in your request payload.

After validation, we will take care of the rest. Especially in this example where we simulate the payment and repayment of the loan.

5. Loan payment is initiated and the loan repayment is scheduled

To get the payments linked to the approved loan: GET /payments?loan_id=<LOAN_ID>

6. Repay the loan

To repay the loan, you should send a credit transfer to Defacto. You will need two information:

  1. The IBAN to send the money to
  2. The reference to attach to the credit transfer

To get these values, GET /loan/{loan_id}.

  • Make sure that status is TO_REPAY before repaying.
  • Get the destination IBAN under repayment_to.account_number
  • Get the reference under repayment_to_references

📘

Manual repayment by SCT should be done on the live environment only! Not sandbox.

On the sandbox environment, repayment are automated. So, you will only need to repay us manually on the production environment.

7. Checking the status of the loan, its payment, repayment and the amount available on your credit line

Now that you have created your first loan, you can check the status of many objects.

Most of the resources of our API are designed around state machines with well-defined states and transitions. You can discover them all under the Concepts section on the left.

Next Steps

  • Make tests with your own invoice data ➜ refer to Testing the API with your own data
  • 💻 You can check out our Web Application where you'll find the invoices and loans that you created
  • 👀 Take a look at the main building blocks of our API: Errors, Pagination, Standards
  • 🔔 You can give a look at our Webhooks. They can help you react to status changes in real time, for example to send emails to your customers, or to create Slack integrations (we do this to monitor new loan requests and payment statuses for example).
  • 🗣 You can send us your feedbacks about your integration! Our goal is to smooth integration as much as possible, so feel free to reach out.

👍

We help you bulletproof your integration with our API

We provide a mechanism to simulate errors in our system so that you can test that your integration is able to handle errors coming from us.

To do so, click the link below.