Create a buyer onboarding session
curl --request POST \
--url https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"success_url": "<string>",
"error_url": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({success_url: '<string>', error_url: '<string>'})
};
fetch('https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding"
payload = {
"success_url": "<string>",
"error_url": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'success_url' => '<string>',
'error_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"token": "<string>",
"url": "<string>"
}{
"code": "BAD_REQUEST",
"error": "Request validation failed. 1 issue found.",
"issues": [
{
"code": "INVALID_TYPE",
"path": "body.registered_at",
"message": "Invalid type"
}
]
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "No Entity found",
"code": "NOT_FOUND"
}Buyers
Create an onboarding session
Generate a short-lived onboarding session for a buyer. Returns a JWT and hosted URL to launch Tilta white-labeled credit application flow for the buyer.
POST
/
v1
/
buyers
/
{external_id}
/
sessions
/
onboarding
Create a buyer onboarding session
curl --request POST \
--url https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"success_url": "<string>",
"error_url": "<string>"
}
'const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({success_url: '<string>', error_url: '<string>'})
};
fetch('https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding"
payload = {
"success_url": "<string>",
"error_url": "<string>"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.tilta.io/v1/buyers/{external_id}/sessions/onboarding",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'success_url' => '<string>',
'error_url' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}{
"token": "<string>",
"url": "<string>"
}{
"code": "BAD_REQUEST",
"error": "Request validation failed. 1 issue found.",
"issues": [
{
"code": "INVALID_TYPE",
"path": "body.registered_at",
"message": "Invalid type"
}
]
}{
"error": "Unauthorized",
"code": "UNAUTHORIZED"
}{
"error": "No Entity found",
"code": "NOT_FOUND"
}Before a buyer can use Tilta payment terms, they must complete the onboarding flow – a white-labeled, Tilta-hosted experience where they confirm their business details and consent to the credit application. This endpoint creates a short-lived session that gives the buyer secure, authenticated access to that flow.
Integration options
Redirect integration
Redirect the buyer’s browser to the
url returned in the response. Tilta hosts the full onboarding experience and
redirects back to your success_url or error_url when the buyer finishes. This is the quickest way to get started with
zero frontend code changes.Embedded Web Element
Use the
token to initialize the Tilta JS SDK and embed the onboarding UI directly within your platform’s checkout or
account page. Provides a seamless white-labeled experience without leaving your site.Onboarding sessions are short-lived. If the buyer does not start the onboarding flow within the session’s validity window, you
must create a new session. Do not cache or reuse session tokens across requests.
Onboarding is only relevant for buyers who do not yet have a credit facility. Call Retrieve
facility first – if it returns a facility, the buyer has already been through
onboarding.
Authorizations
Your Tilta API key, sent as Bearer <key>.
Path Parameters
Unique identifier of a buyer.
Maximum string length:
100Pattern:
^[a-zA-Z0-9-_]+$