API Reference

Make your first loan in 5 minutes

Getting started with Defacto sandbox

Overview

This guide explains how to create your first loan using Defacto's sandbox API.
Test freely – no real money involved.
Sandbox URL: https://api-sandbox.getdefacto.com

1. Authenticate

Get your token via the authentication guide.
Add this header to all your requests:

Authorization: Bearer <your-token>

2. Onboard your borrower

Option 1 – Fake borrower

GET /sandbox/business-generator

Payload:

{
  "is_borrower": true
}

Then register it, using the payload from the above business-generator response:

POST /borrowers

Option 2 – Real company data

Accept T&Cs:

POST /borrower/{borrower_id}/sign

Or use signed_at when creating the borrower.

Notes

  • Contract URL is returned in response or via GET /borrowers
  • Don’t store it – it’s temporary
  • Borrower must be APPROVED (check via GET /borrower/{id})

3. Generate an invoice (sandbox only)

POST /sandbox/invoice-generator

➡️ Save the full invoice_creation_payload from the response.

4. Request a loan

POST /loans

Required fields:

  • invoices: Use the payload from invoice generation
  • salt_id: Unique string to avoid duplicates
  • auto_validate: (optional) set to true to skip manual validation
  • to_account: Must match the invoice

Example:

{
  "invoices": [ { ... } ],
  "salt_id": "unique_loan_id_123",
  "auto_validate": true
}

Save the loan_id from the response

5. Validate loan (if not auto-validated)

POST /loan/{loan_id}/validate

6. Follow the payment

GET /payments?loan_id=<LOAN_ID>

7. Repayment

In sandbox: repayment is automatic.
In production: you must trigger repayment.

To get repayment info:

GET /loan/{loan_id}

Response includes:

  • IBAN: repayment_to.account_number
  • Reference: repayment_to_references

⚠️ Only repay when loan status is TO_REPAY.

8. Monitor loan status

  • Loan details:
GET /loan/{loan_id}
  • Loan events:
GET /loan/{loan_id}/events
  • Credit line:
GET /credit_lines

9. Extras

  • Sandbox URL: https://sandbox.getdefacto.com
  • Webhooks: optional for real-time updates
  • Use the error simulator to test failed flows