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!

Create your first loan on our sandbox! No real money involved, so make as many tests as you want.

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. Create your 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 the use case, borrowers can be either:

• For marketplaces: buyers or sellers on an invoice you would like to finance with Defacto
• For fintechs & other platforms: end-users are your borrowers

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 facilitate the 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 accepted 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. Generate 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.

After that you can request your first loan!

3. Request 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, using the invoice_creation_payload field from the previously generated invoice
• Prefer providing a unique salt_id value for each requested loan to avoid accidental duplicates

Execute the request to create your first loan.

4. Accept the loan conditions

The loan creation request will return the proposed loan conditions, including the fees , 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.

• To check the loan status GET /loan/{loan_id}, and to the loan activity log GET /loan/{loan_id}/events.
• To check the loan payment and repayment GET /payments
• To check the amount available on your credit line for future loans GET /credit_lines

Next Steps

• 💻 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 smoothen 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.