Skip to main content

Onboarding: Customization

Complete reference for customizing the white-label onboarding experience to match your brand and requirements.

Overview​

Customize every aspect of the white-label onboarding flow to create a seamless branded experience. From visual styling to content localization, make the Debitura onboarding feel like a natural part of your platform.

Customization Levels​

Level 1: Basic Branding​

  • Logo
  • Primary color
  • Font family

Level 2: Advanced Styling​

  • Full color palette
  • Custom CSS
  • Typography system

Level 3: Content Customization​

  • Custom copy and messaging
  • Localized content
  • Help text and tooltips

Level 4: Flow Customization​

  • Optional steps
  • Pre-filled data
  • Custom fields

Configuring White-Label Settings​

Initial Setup​

Configure your white-label settings before creating clients:

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

Basic Configuration:

{
  "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"
}

Advanced Configuration:

{
  "branding": {
    "logo_url": "https://yourplatform.com/logo.png",
    "logo_height": 40,
    "favicon_url": "https://yourplatform.com/favicon.ico",
    "primary_color": "#0066CC",
    "secondary_color": "#004A99",
    "success_color": "#00B050",
    "error_color": "#DC3545",
    "text_color": "#1A1A1A",
    "background_color": "#FFFFFF",
    "font_family": "Inter, -apple-system, sans-serif",
    "heading_font_family": "Inter, sans-serif",
    "border_radius": "8px"
  },
  "urls": {
    "return_url": "https://yourplatform.com/onboarding/complete",
    "cancel_url": "https://yourplatform.com/onboarding/cancelled",
    "privacy_policy_url": "https://yourplatform.com/privacy",
    "terms_url": "https://yourplatform.com/terms"
  },
  "webhooks": {
    "url": "https://yourplatform.com/webhooks/debitura",
    "events": ["onboarding_started", "onboarding_completed", "onboarding_cancelled"]
  },
  "localization": {
    "default_language": "en",
    "supported_languages": ["en", "sv", "da", "no"]
  }
}

Update Settings​

Modify settings at any time:

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

Request:

{
  "branding": {
    "primary_color": "#FF6600"
  }
}

Changes apply to new onboarding flows immediately.

Branding Options​

Logo Configuration​

{
  "branding": {
    "logo_url": "https://yourplatform.com/logo.png",
    "logo_height": 40,
    "logo_dark_url": "https://yourplatform.com/logo-dark.png"
  }
}

Logo Requirements:

  • Format: PNG, SVG, or JPG
  • Recommended height: 32-48px
  • Transparent background recommended
  • Max file size: 500KB
  • Served over HTTPS

Optional dark mode logo:

  • Provide logo_dark_url for dark mode support
  • Falls back to main logo if not provided

Color Palette​

{
  "branding": {
    "primary_color": "#0066CC",
    "secondary_color": "#004A99",
    "accent_color": "#FF6600",
    "success_color": "#00B050",
    "warning_color": "#FFA500",
    "error_color": "#DC3545",
    "info_color": "#17A2B8",
    "text_color": "#1A1A1A",
    "text_secondary_color": "#6C757D",
    "background_color": "#FFFFFF",
    "background_secondary_color": "#F8F9FA",
    "border_color": "#DEE2E6"
  }
}

Color format: Hex codes (e.g., #0066CC)

Usage:

  • primary_color - Buttons, links, headers
  • secondary_color - Secondary buttons, accents
  • success_color - Success messages, completed steps
  • error_color - Validation errors, warnings
  • text_color - Main text content
  • background_color - Page background

Typography​

{
  "branding": {
    "font_family": "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
    "heading_font_family": "Inter, sans-serif",
    "font_size_base": "16px",
    "line_height": "1.5"
  }
}

Font options:

  • Use system fonts for best performance
  • Or reference Google Fonts: "Roboto, sans-serif"
  • Fallback fonts recommended

System font stack example:

"-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif"

Styling Options​

{
  "branding": {
    "border_radius": "8px",
    "button_border_radius": "6px",
    "input_border_radius": "4px",
    "shadow_style": "medium"
  }
}

Border radius:

  • 0px - Square corners
  • 4px - Subtle rounding
  • 8px - Standard rounded (default)
  • 16px - Highly rounded

Shadow styles:

  • none - No shadows
  • subtle - Light shadows
  • medium - Standard depth (default)
  • strong - Pronounced shadows

Content Customization​

Custom Messaging​

Override default text throughout the flow:

{
  "content": {
    "welcome": {
      "title": "Welcome to {{platform_name}}",
      "subtitle": "Set up your debt collection in minutes",
      "description": "We've partnered with Debitura to bring professional debt collection to your business."
    },
    "completion": {
      "title": "You're all set!",
      "message": "Your {{platform_name}} account is ready for debt collection.",
      "next_steps": [
        "Return to {{platform_name}}",
        "Create your first case",
        "Explore collection features"
      ]
    }
  }
}

Available variables:

  • {{platform_name}} - Your platform name
  • {{company_name}} - Customer's company name
  • {{contact_name}} - Contact person name

Help Text​

Customize tooltips and help messages:

{
  "content": {
    "help_text": {
      "company_registration": "Your official company registration number as registered with your country's business registry.",
      "vat_number": "VAT number is optional but helps with invoicing and compliance.",
      "bank_account": "Debt collection payments will be transferred to this account."
    }
  }
}

Email Templates​

Customize automated emails sent during onboarding:

{
  "emails": {
    "onboarding_invitation": {
      "subject": "Complete your {{platform_name}} setup",
      "from_name": "{{platform_name}} Team",
      "reply_to": "support@yourplatform.com"
    },
    "onboarding_reminder": {
      "subject": "Don't forget to complete your setup",
      "enabled": true,
      "send_after_hours": 24
    },
    "onboarding_completed": {
      "subject": "Welcome to {{platform_name}}!",
      "enabled": true
    }
  }
}

Localization​

Language Configuration​

Support multiple languages:

{
  "localization": {
    "default_language": "en",
    "supported_languages": ["en", "sv", "da", "no", "fi"],
    "auto_detect": true
  }
}

Language detection:

  • auto_detect: true - Detect from browser settings
  • auto_detect: false - Always use default language

Per-Client Language​

Set language when creating client:

{
  "onboarding_metadata": {
    "language": "sv"
  }
}

Supported languages:

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

Custom Translations​

Override specific translations:

{
  "translations": {
    "sv": {
      "welcome.title": "Välkommen till {{platform_name}}",
      "button.continue": "Fortsätt",
      "button.back": "Tillbaka"
    }
  }
}

Flow Customization​

Optional Steps​

Configure which steps are required:

{
  "flow": {
    "steps": {
      "company_details": { "required": true },
      "verification": { "required": true },
      "beneficial_ownership": { "required": false },
      "banking": { "required": true },
      "agreement": { "required": true }
    }
  }
}

Conditional requirements:

{
  "flow": {
    "steps": {
      "beneficial_ownership": {
        "required": true,
        "condition": "country === 'SE' || country === 'DK'"
      }
    }
  }
}

Pre-filled Data​

Pre-populate fields to reduce friction:

{
  "external_id": "customer_123",
  "company_name": "Acme Corporation",
  "onboarding_metadata": {
    "prefill": {
      "vat_number": "SE123456789001",
      "country": "SE",
      "email": "contact@acme.com",
      "phone": "+46701234567",
      "address": {
        "street": "Kungsgatan 1",
        "city": "Stockholm",
        "postal_code": "111 43",
        "country": "SE"
      }
    }
  }
}

Pre-fillable fields:

  • Company information
  • Contact details
  • Address
  • VAT number
  • Industry

Note: Users can still edit pre-filled values.

Custom Fields​

Add custom fields to collect additional data:

{
  "flow": {
    "custom_fields": [
      {
        "id": "account_manager",
        "label": "Account Manager",
        "type": "text",
        "required": false,
        "step": "company_details"
      },
      {
        "id": "referral_source",
        "label": "How did you hear about us?",
        "type": "select",
        "options": [
          { "value": "search", "label": "Search engine" },
          { "value": "referral", "label": "Referral" },
          { "value": "other", "label": "Other" }
        ],
        "step": "welcome"
      }
    ]
  }
}

Field types:

  • text - Single line text input
  • textarea - Multi-line text
  • select - Dropdown menu
  • checkbox - Boolean value
  • number - Numeric input
  • date - Date picker

URL Configuration​

Return URLs​

{
  "urls": {
    "return_url": "https://yourplatform.com/onboarding/complete",
    "cancel_url": "https://yourplatform.com/onboarding/cancelled",
    "error_url": "https://yourplatform.com/onboarding/error"
  }
}

Query parameters appended:

  • client_id - Client identifier
  • status - Completion status
  • session_id - Onboarding session ID

Example return:

https://yourplatform.com/onboarding/complete?client_id=cli_abc123&status=completed&session_id=sess_xyz789
{
  "urls": {
    "privacy_policy_url": "https://yourplatform.com/privacy",
    "terms_url": "https://yourplatform.com/terms",
    "support_url": "https://yourplatform.com/support",
    "contact_email": "support@yourplatform.com"
  }
}

Links appear in onboarding footer.

Advanced Customization​

Custom CSS​

Inject custom CSS for fine-grained control:

{
  "branding": {
    "custom_css": ".btn-primary { box-shadow: 0 4px 6px rgba(0,0,0,0.1); }"
  }
}

Limitations:

  • Max 10KB of CSS
  • Cannot override layout structure
  • Scoped to onboarding flow only

Use cases:

  • Adjust spacing
  • Fine-tune colors
  • Custom animations

JavaScript Events​

Listen to onboarding events:

// On your return_url page
window.addEventListener('message', (event) => {
  if (event.data.type === 'debitura_onboarding_completed') {
    console.log('Client ID:', event.data.client_id);
    // Handle completion
  }
});

Testing Customization​

Preview Mode​

Preview your customization before going live:

GET /v1/referral-partners/settings/white-label/preview

Response:

{
  "preview_url": "https://onboarding.debitura.com/preview/xyz789",
  "expires_at": "2024-01-15T12:00:00Z"
}

Use test data to complete the flow and verify appearance.

Responsive Testing​

Test on different devices:

  • Desktop browsers
  • Mobile devices (iOS/Android)
  • Tablets
  • Different screen sizes

Best Practices​

Visual Design​

  • Use your brand colors consistently
  • Ensure sufficient color contrast (WCAG AA)
  • Test logo visibility on different backgrounds
  • Keep fonts readable (min 14px)

Content​

  • Write clear, concise instructions
  • Use customer-friendly language
  • Avoid legal jargon where possible
  • Provide helpful error messages

User Experience​

  • Pre-fill data when possible
  • Make optional fields clearly marked
  • Show progress indication
  • Provide exit/cancel option

Technical​

  • Use HTTPS for all resource URLs
  • Optimize logo file size
  • Test in multiple browsers
  • Monitor webhook reliability

Common Customization Patterns​

Pattern 1: Minimal Branding​

Just logo and color:

{
  "branding": {
    "logo_url": "https://yourplatform.com/logo.png",
    "primary_color": "#0066CC"
  }
}

Pattern 2: Full White-Label​

Complete brand immersion:

{
  "branding": {
    "logo_url": "https://yourplatform.com/logo.png",
    "primary_color": "#0066CC",
    "secondary_color": "#004A99",
    "font_family": "YourBrandFont, sans-serif"
  },
  "content": {
    "welcome": {
      "title": "Welcome to {{platform_name}}",
      "subtitle": "Professional debt collection, made simple"
    }
  },
  "urls": {
    "privacy_policy_url": "https://yourplatform.com/privacy",
    "terms_url": "https://yourplatform.com/terms"
  }
}

Pattern 3: Localized Experience​

Multi-language support:

{
  "localization": {
    "default_language": "en",
    "supported_languages": ["en", "sv", "da"],
    "auto_detect": true
  },
  "translations": {
    "sv": {
      "welcome.title": "Välkommen"
    }
  }
}

Troubleshooting​

Issue: Logo not displaying

Solutions:

  • Verify URL is accessible
  • Check HTTPS is used
  • Ensure file size under 500KB
  • Verify image format (PNG/SVG/JPG)

Issue: Colors not applying

Solutions:

  • Use hex format: #0066CC
  • Clear cache and test again
  • Check color is valid hex code

Issue: Custom CSS not working

Solutions:

  • Check CSS is valid
  • Verify size under 10KB
  • Review browser console for errors

Next Steps​