Finfra Documentation

Finfra is a lending infrastructure platform. This documentation is for your business and product team it explains how Finfra works conceptually, and walks through the full integration journey step by step. For exact endpoint parameters, see the API Reference.

Core Concepts

Three primary objects make up the Finfra data model. Everything else relates to or extends one of these.

Environments

Finfra provides two isolated environments. Which one your API calls hit depends entirely on the API key you use there is no separate URL switch required in your code.

What is a borrower?

A borrower is any person or business entity that you onboard onto Finfra's platform to receive credit. Before a borrower can take out a loan, they must complete KYC (Know Your Customer) verification this is a legal requirement for lending operations in Indonesia.

Think of the borrower object as the central record that links together identity documents, credit history, consent records, and loans.

Borrower types

When creating a borrower, you must specify one of two types. The type drives a different KYC workflow and document set, so providing the correct value is critical.

Borrower status lifecycle

A borrower moves through a set of statuses as they progress through the onboarding and KYC process.

What is a loan?

A loan is a credit product issued to an approved borrower. Finfra manages the full loan lifecycle: origination, agreement signing, disbursement, and repayment tracking.

Loans are always tied to exactly one borrower. A borrower can have multiple loans, but each loan is independent.

Loan types

Finfra supports two loan repayment structures.

Loan status lifecycle

A loan moves through the following statuses from creation to full repayment.

Documents & KYC

KYC (Know Your Customer) is the process of verifying a borrower's identity before lending to them. Finfra handles this in two parts: document upload and biometric verification.

Document upload flow

Uploading a document is always a two-step process:

1. Create a document object call POST /api/documents to register the document and get a presigned upload URL.
2. Upload the file PUT the file binary directly to the presigned URL returned in step 1.

Supported KYC providers

Finfra integrates with multiple identity data providers. You specify which to use via the data-source header on relevant endpoints.

Authentication

Before you can call any Finfra endpoint, you need a JWT access token. You get one by exchanging your Basic credentials (clientId + clientSecret) via the token endpoint.

# Encode credentials
CREDS=$(echo -n 'clientId:clientSecret' | base64)

# Get token
TOKEN=$(curl -s -X POST \
  https://sandbox-partner-service.elp.finfra.io/api/auth/token/v2 \
  -H "Authorization: Basic $CREDS" \
  | jq -r '.access_token')

KYC flow

The KYC flow onboards a new borrower and verifies their identity. Follow these steps in order skipping any step will result in the borrower being stuck in PENDING status.

Loan origination

Once a borrower is APPROVED, you can create a loan for them. Choose between a single-payment loan or a BNPL installment loan based on your product.

Disbursement

Once the loan agreement is signed, you can initiate disbursement. Finfra will transfer funds directly to the borrower's registered bank account.

Repayment

Finfra supports two repayment collection methods: a hosted payment link or a virtual account (bank transfer). Both methods notify you via webhook when a payment is received.

Webhooks & callbacks

Finfra does not require polling. Instead, Finfra pushes status changes to your registered HTTPS endpoint using callbacks. You must expose a public HTTPS endpoint and register it in your Finfra dashboard.

Callback types

Securing callbacks

All callbacks from Finfra include a finfra-auth-key header. Validate this header on every incoming request before processing it to prevent spoofed callbacks.

app.post('/callbacks/finfra', (req, res) => {
  // Validate the auth key
  const key = req.headers['finfra-auth-key'];
  if (key !== process.env.FINFRA_CALLBACK_KEY) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  // Process the event
  const { type, status, data } = req.body;
  console.log(`Event: ${type}, status: ${status}`);

  res.status(200).json({ received: true });
});