Onboarding: White-Label Onboarding

Provide your customers with a fully branded onboarding experience that seamlessly integrates Debitura's debt collection services into your platform.

Overview

White-label onboarding allows your customers to complete Debitura's compliance and verification process without leaving your platform's look and feel. The experience is fully customized with your branding while maintaining Debitura's legal and compliance requirements.

What is White-Label Onboarding?

White-label onboarding is a branded, hosted onboarding flow that:

Looks like your platform - Custom logo, colors, fonts, and styling
Handles compliance - Collects required legal and business information
Manages verification - Completes KYC/KYB requirements
Signs agreements - Digital signature for Debitura's terms
Issues credentials - Provides bearer token upon completion

When to Use White-Label Onboarding

Choose white-label onboarding when:

You want customers to have a seamless branded experience
You need to collect detailed business information
Legal agreements must be signed
Compliance verification is required
Customer interaction is acceptable

Alternative: Use API-only onboarding for backend integrations without customer interaction.

Onboarding Flow

1. Create Client      2. Redirect        3. Customer         4. Webhook
   (Your Platform) ──► (Onboarding URL) ──► Completes Flow ──► (Your Backend)
                                              │
                                              └─► Bearer Token Issued

Flow Steps

Initiate - Your platform creates a client with onboarding_type: "white_label"
Redirect - Customer redirected to branded onboarding URL
Complete - Customer fills forms, signs agreement
Webhook - Your backend receives completion notification with bearer token
Ready - Customer can now create cases

Implementation Guide

Step 1: Configure Branding

Before initiating onboarding, configure your white-label settings:

POST /v1/referral-partners/settings/white-label

Request:

{
  "branding": {
    "logo_url": "https://yourplatform.com/logo.png",
    "primary_color": "#0066CC",
    "font_family": "Inter, sans-serif"
  },
  "return_url": "https://yourplatform.com/onboarding/complete",
  "webhook_url": "https://yourplatform.com/webhooks/debitura"
}

See Onboarding Customization for detailed branding options.

Step 2: Create Client with White-Label Option

POST /v1/referral-partners/clients

Request:

{
  "external_id": "customer_123",
  "company_name": "Acme Corporation AB",
  "country": "SE",
  "email": "ceo@acme.com",
  "onboarding_type": "white_label",
  "onboarding_metadata": {
    "language": "sv",
    "prefill_vat": "SE123456789001",
    "contact_person": "Anna Andersson"
  }
}

Response:

{
  "client_id": "cli_abc123",
  "status": "pending_onboarding",
  "onboarding_url": "https://onboarding.debitura.com/wl/xyz789abc012",
  "onboarding_expires_at": "2024-01-22T10:00:00Z",
  "created_at": "2024-01-15T10:00:00Z"
}

Step 3: Redirect Customer

Redirect your customer to the onboarding_url:

// Example: Next.js
router.push(client.onboarding_url);

// Example: React
window.location.href = client.onboarding_url;

// Example: Server-side redirect
res.redirect(client.onboarding_url);

Step 4: Handle Completion Webhook

Listen for the completion webhook:

app.post('/webhooks/debitura', async (req, res) => {
  const { event, data } = req.body;

  if (event === 'client.onboarding_completed') {
    const {
      client_id,
      external_id,
      bearer_token,
      onboarding_completed_at
    } = data;

    // Store bearer token
    await db.clients.update(external_id, {
      debitura_client_id: client_id,
      bearer_token_encrypted: await encrypt(bearer_token),
      onboarding_status: 'completed',
      onboarding_completed_at
    });

    // Notify customer (optional)
    await sendEmail(external_id, 'onboarding_complete');

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

Step 5: Handle Return

When customer completes onboarding, they're redirected to your return_url:

// Example: /onboarding/complete?client_id=cli_abc123&status=completed

app.get('/onboarding/complete', async (req, res) => {
  const { client_id, status } = req.query;

  if (status === 'completed') {
    // Show success message
    res.render('onboarding-success', {
      message: 'Your account is ready!',
      next_steps: [
        'Create your first case',
        'Explore debt collection features'
      ]
    });
  } else if (status === 'cancelled') {
    // Customer cancelled
    res.render('onboarding-cancelled');
  }
});

Onboarding Content

Information Collected

During onboarding, customers provide:

Company Information:

Legal company name
Registration number
VAT number (if applicable)
Business address
Industry/sector

Contact Details:

Primary contact person
Email address
Phone number
Billing contact (if different)

Legal Compliance:

Beneficial ownership (if required)
Business verification documents
Digital signature on terms

Payment Information:

Bank account for payouts
Billing preferences
Currency preferences

Onboarding Steps

The white-label flow includes:

Welcome - Introduction to debt collection service
Company Details - Business information entry
Verification - Document upload and KYC/KYB
Banking - Payout account configuration
Legal Agreement - Terms and conditions
Completion - Summary and confirmation

Onboarding States

Status Lifecycle

pending_onboarding → in_progress → completed
                              ↓
                          cancelled
                              ↓
                          expired

Status Meanings

Status	Description	Actions Available
`pending_onboarding`	Created, not started	Send reminder, cancel
`in_progress`	Customer started flow	Monitor progress
`completed`	Successfully finished	Bearer token issued
`cancelled`	Customer abandoned	Restart onboarding
`expired`	URL expired (7 days)	Generate new URL

Check Onboarding Status

GET /v1/referral-partners/clients/{client_id}/onboarding-status

Response:

{
  "status": "in_progress",
  "progress": {
    "current_step": 3,
    "total_steps": 5,
    "steps_completed": ["welcome", "company", "verification"]
  },
  "started_at": "2024-01-15T11:00:00Z",
  "expires_at": "2024-01-22T10:00:00Z"
}

Managing Onboarding

Resend Onboarding Link

If customer lost the link:

POST /v1/referral-partners/clients/{client_id}/resend-onboarding

Response:

{
  "onboarding_url": "https://onboarding.debitura.com/wl/new_xyz789",
  "expires_at": "2024-01-22T10:00:00Z",
  "sent_to": "ceo@acme.com"
}

Cancel Onboarding

If customer decides not to proceed:

POST /v1/referral-partners/clients/{client_id}/cancel-onboarding

Effect:

Onboarding URL becomes invalid
Client status changes to cancelled
No bearer token issued

Restart Onboarding

For expired or cancelled onboardings:

POST /v1/referral-partners/clients/{client_id}/restart-onboarding

Response:

{
  "onboarding_url": "https://onboarding.debitura.com/wl/restart_abc123",
  "expires_at": "2024-01-29T10:00:00Z"
}

Webhook Events

Subscribe to onboarding lifecycle events:

onboarding_started

{
  "event": "client.onboarding_started",
  "data": {
    "client_id": "cli_abc123",
    "external_id": "customer_123",
    "started_at": "2024-01-15T11:00:00Z"
  }
}

onboarding_completed

{
  "event": "client.onboarding_completed",
  "data": {
    "client_id": "cli_abc123",
    "external_id": "customer_123",
    "bearer_token": "tok_live_xyz789",
    "onboarding_completed_at": "2024-01-15T11:30:00Z"
  }
}

onboarding_cancelled

{
  "event": "client.onboarding_cancelled",
  "data": {
    "client_id": "cli_abc123",
    "external_id": "customer_123",
    "cancelled_at": "2024-01-15T11:15:00Z",
    "reason": "user_cancelled"
  }
}

User Experience Best Practices

Before Onboarding

Prepare customers:

Explain what information they'll need
Estimate time required (typically 10-15 minutes)
Note that documents may be needed
Mention digital signature requirement

Required documents:

Company registration certificate
ID of beneficial owners (if applicable)
Bank account verification

During Onboarding

Your platform should:

Clearly indicate customer is in onboarding process
Show progress indication
Provide support contact information
Handle return gracefully

After Onboarding

Welcome customers:

Confirm successful completion
Provide next steps
Offer onboarding call (optional)
Share documentation links

Localization

Onboarding supports multiple languages:

{
  "onboarding_metadata": {
    "language": "sv" // Swedish
  }
}

Supported languages:

en - English
sv - Swedish
da - Danish
no - Norwegian
fi - Finnish
de - German

Content is automatically translated including:

Form labels and instructions
Validation messages
Legal agreements
Email communications

Testing

Sandbox Testing

Test onboarding in sandbox environment:

POST https://api.sandbox.debitura.com/v1/referral-partners/clients

Sandbox behavior:

No real verification performed
Documents not actually checked
No legal agreements required
Bearer token issued immediately after flow

Test Scenarios

Happy Path - Complete full flow
Abandonment - Start but don't finish
Expiration - Let URL expire
Cancellation - Cancel mid-flow
Restart - Complete after restart

Troubleshooting

Issue: Customer says onboarding link doesn't work

Solutions:

Check if URL expired (7 days)
Verify status is pending_onboarding
Resend link via API

Issue: Webhook not received after completion

Solutions:

Verify webhook URL in settings
Check webhook endpoint is accessible
Review webhook logs in Debitura portal

Issue: Customer completed but status shows in_progress

Solutions:

Wait up to 5 minutes for processing
Check if verification documents pending review
Contact Debitura support

Next Steps

Onboarding Customization - Detailed branding options
Integration Examples - Code examples
Troubleshooting - Common issues

Overview​

What is White-Label Onboarding?​

When to Use White-Label Onboarding​

Onboarding Flow​

Flow Steps​

Implementation Guide​

Step 1: Configure Branding​

Step 2: Create Client with White-Label Option​

Step 3: Redirect Customer​

Step 4: Handle Completion Webhook​

Step 5: Handle Return​

Onboarding Content​

Information Collected​

Onboarding Steps​

Onboarding States​

Status Lifecycle​

Status Meanings​

Check Onboarding Status​

Managing Onboarding​

Resend Onboarding Link​

Cancel Onboarding​

Restart Onboarding​

Webhook Events​

onboarding_started​

onboarding_completed​

onboarding_cancelled​

User Experience Best Practices​

Before Onboarding​

During Onboarding​

After Onboarding​

Localization​

Testing​

Sandbox Testing​

Test Scenarios​

Troubleshooting​

Next Steps​

Overview

What is White-Label Onboarding?

When to Use White-Label Onboarding

Onboarding Flow

Flow Steps

Implementation Guide

Step 1: Configure Branding

Step 2: Create Client with White-Label Option

Step 3: Redirect Customer

Step 4: Handle Completion Webhook

Step 5: Handle Return

Onboarding Content

Information Collected

Onboarding Steps

Onboarding States

Status Lifecycle

Status Meanings

Check Onboarding Status

Managing Onboarding

Resend Onboarding Link

Cancel Onboarding

Restart Onboarding

Webhook Events

onboarding_started

onboarding_completed

onboarding_cancelled

User Experience Best Practices

Before Onboarding

During Onboarding

After Onboarding

Localization

Testing

Sandbox Testing

Test Scenarios

Troubleshooting

Next Steps