Buyer onboarding

Buyers are the businesses you sell to – the ones that purchase goods or services and receive deferred payment terms. Before a buyer can use Tilta’s financing, whether at an online checkout or on an order agreed offline, they must have an active credit facility. This guide walks you through the three-step onboarding process and explains how to use Tilta’s pre-built onboarding UI to reduce development time.

How the credit facility works

A credit facility is a per-buyer credit line of up to €250,000, approved through Tilta’s automated underwriting engine. Once approved, the facility covers every financed order for that buyer. Tilta automatically renews each credit facility every three months – no action is required from you or the buyer to keep it active. If a buyer’s risk profile changes significantly, Tilta may adjust the facility limit at renewal.

Only buyers with an active credit facility can have their receivables financed. Attempting to create an invoice for a buyer without an active facility will return an error.

Onboarding process

Create the buyer

Start by creating the buyer record in Tilta. Submit the buyer’s company information using the POST /v1/buyers endpoint. Required fields vary by country and legal form, but the core set includes the company’s country of registration, VAT number, and contact details.You must also provide contact information for the buyer’s representative – the person who will interact with Tilta on behalf of the company. For larger enterprises with a dedicated accounts payable team, you can provide AP team contact details instead.

POST /v1/buyers
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "external_id": "buyer_de_001",
  "legal_name": "Buyer GmbH",
  "legal_form": "LIMITED_COMPANY",
  "business_address": {
    "street": "Kaufstraße",
    "house": "12",
    "postcode": "80331",
    "city": "Munich",
    "country": "DE"
  },
  "business_identifiers": [
    {
      "type": "VAT_ID",
      "value": "DE987654321",
      "country": "DE"
    }
  ]
}

external_id, legal_name, legal_form, and business_address are required. Add the buyer’s contact people separately with Create a contact – they are the recipients of Tilta’s automated emails.At this stage the buyer exists in Tilta but does not yet have a credit facility.

Use a stable, unique identifier for external_id – typically the buyer’s ID in your own system. This value is used throughout the API to reference the buyer and cannot be changed after creation.

Upload transaction history (optional but recommended)

Tilta’s underwriting engine uses third-party data to assess creditworthiness, but supplementing this with your platform’s own transaction history can meaningfully improve the credit facility limit offered to the buyer.Submit historical order data using POST /v1/buyers/{external_id}/orders. The body is an array of completed orders. Each record needs external_id, ordered_at, payment_method, payment_term, amount, and status, where status is either CLOSED (repaid) or CANCELLED.

POST /v1/buyers/{external_id}/orders
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

[
  {
    "external_id": "hist_order_001",
    "amount": {
      "net": 120000,
      "gross": 142800,
      "tax": 22800,
      "currency": "EUR"
    },
    "ordered_at": 1705312800,
    "payment_method": "TRANSFER",
    "payment_term": "DEFER_30D",
    "status": "CLOSED"
  },
  {
    "external_id": "hist_order_002",
    "amount": {
      "net": 85000,
      "gross": 101150,
      "tax": 16150,
      "currency": "EUR"
    },
    "ordered_at": 1708439400,
    "payment_method": "TRANSFER",
    "payment_term": "DEFER_30D",
    "status": "CLOSED"
  }
]

All monetary values are expressed in the smallest currency unit (e.g., euro cents). An order worth €1,200.00 net is represented as 120000.

You can upload up to 24 months of historical orders. More data generally leads to better underwriting outcomes, particularly for buyers with high order volumes or large average order values.

Request a credit facility

Once you have created the buyer and optionally uploaded transaction history, request a credit facility. This triggers Tilta’s automated underwriting process, which queries third-party data sources (commercial registers, credit bureaus, etc.) alongside any transaction history you provided.

POST /v1/buyers/{external_id}/facility
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "requested_amount": {
    "amount": 5000000,
    "currency": "EUR"
  }
}

Tilta will return a response indicating the facility has been requested. The underwriting process is typically near-instant for automated decisions. The facility status transitions to ACTIVE when approved.You can check facility status at any time by calling GET /v1/buyers/{external_id}/facility, or configure a webhook to receive a notification when the status changes.

If underwriting cannot be completed automatically – for example, if the buyer’s data is insufficient or a manual review is triggered – Tilta will notify you via webhook. The buyer will not be able to use payment terms until the facility is approved.

Pre-built onboarding UI

If you do not want to build a custom onboarding form from scratch, Tilta offers a pre-built Buyer Onboarding UI that handles data collection and submission. The UI automatically pre-fills any data you already provided when creating the buyer, reducing the amount the buyer needs to enter manually.

The pre-built Onboarding UI is only available for buyers who do not yet have an active credit facility. Once a facility is approved, the UI is no longer accessible.

To use the pre-built UI, first create an onboarding session for the buyer:

POST /v1/buyers/{external_id}/sessions/onboarding
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "success_url": "https://yourplatform.com/checkout/success",
  "error_url": "https://yourplatform.com/checkout/error"
}

The response includes two values:

Field	Description
`token`	A short-lived JWT used to initialise the Web Element widget
`url`	A fully qualified URL to Tilta’s hosted onboarding form

Delivery options

Web Element (embedded widget)
Hosted redirect

Use the JWT token to embed the onboarding experience directly within your platform’s UI. The Web Element renders inside your page – the buyer never leaves your site.Initialise the widget using Tilta’s JavaScript SDK:

import { createWidget } from '@tilta/onboarding-sdk';

const widget = createWidget({
  token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...', // JWT from session response
  containerId: 'tilta-onboarding-container',
  onSuccess: () => {
    // Buyer has completed onboarding – proceed to checkout
    window.location.href = '/checkout';
  },
  onCancel: () => {
    // Buyer cancelled – handle accordingly
  }
});

widget.mount();

Alternatively, open it as a modal overlay:

import { createModal } from '@tilta/onboarding-sdk';

const modal = createModal({
  token: 'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
  onSuccess: () => {
    modal.close();
    proceedToCheckout();
  }
});

modal.open();

The Web Element is the recommended approach for platforms that want to maintain a consistent look and feel. You can apply your platform’s brand colours through the SDK’s theming options.

Redirect the buyer’s browser directly to the url returned by the session endpoint. Tilta’s hosted form handles the entire onboarding journey, then redirects the buyer back to your success_url or error_url when complete.

// Redirect the Buyer to Tilta's hosted onboarding form
const response = await fetch(`/v1/buyers/${buyerId}/sessions/onboarding`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}` },
  body: JSON.stringify({
    success_url: 'https://yourplatform.com/checkout/success',
    error_url: 'https://yourplatform.com/checkout/error'
  })
});

const { url } = await response.json();
window.location.href = url;

The Hosted Redirect is the fastest implementation path. It requires no frontend SDK integration and works in any web environment. Use it when you want to minimise integration effort or when embedding an iframe is not appropriate.

Credit facility renewals

Tilta renews each active credit facility automatically every three months. The renewal uses the same underwriting signals as the initial approval and may result in an increased, maintained, or decreased credit limit based on updated data. Neither you nor the buyer need to take any action to trigger a renewal. If a renewal results in a significant change to the facility limit, Tilta will notify you via webhook so you can update any UI elements that display the available credit amount.

API reference summary

Endpoint	Method	Purpose
`/v1/buyers`	`POST`	Create a new buyer
`/v1/buyers/{external_id}/orders`	`POST`	Upload historical order data
`/v1/buyers/{external_id}/facility`	`POST`	Request a credit facility
`/v1/buyers/{external_id}/facility`	`GET`	Retrieve facility status and limit
`/v1/buyers/{external_id}/sessions/onboarding`	`POST`	Create a pre-built onboarding session

Get Started

Integration

Onboarding

Orders & Payments

Notifications & Communication

Platform & Reference

Buyer onboarding

How the credit facility works

Onboarding process

Pre-built onboarding UI

Delivery options

Credit facility renewals

API reference summary

​How the credit facility works

​Onboarding process

​Pre-built onboarding UI

​Delivery options

​Credit facility renewals

​API reference summary

How the credit facility works

Onboarding process

Pre-built onboarding UI

Delivery options

Credit facility renewals

API reference summary