White-Label UI

Debitura's branded onboarding experience for your clients.

Overview

The white-label referral UI handles client-facing flows that require user interaction:

• Onboarding — New clients complete company details and sign agreements
• Linking approval — Existing clients approve connection to your platform
• Contract signing — Sign or refresh the Standard Debt Collection Agreement (SDCA)
• Power of Attorney — Sign jurisdiction-specific PoA documents

These flows are hosted by Debitura but branded with your logo, colors, and fonts.

Debitura does not send emails

For all referral partner flows, Debitura never emails onboarding, approval, or signing URLs to your clients. You are responsible for delivering every URL — in-app, by redirect, or via your own emails. See the Responsibility Matrix for the full ownership breakdown.

When It's Used

The white-label UI is triggered when:

Scenario	API Response	Action
New client needs onboarding	202 Accepted	Present onboarding URL
Existing client needs to approve link	409 ClientExistsNeedsLinking	Present approval URL
Case blocked by missing contract	422 with solutionUrl	Present signing URL
Case blocked by missing PoA	422 with solutionUrl	Present PoA signing URL

URL Structure

URLs are returned by the Referral Partner API and Customer API:

https://referral.debitura.com/companydetails/{linkId}
https://app.debitura.com/referralpartner/approve?token={approvalToken}
https://referral.debitura.com/ContractUpgrade/Sign/{linkId}
https://referral.debitura.com/PowerOfAttorney/Sign/{linkId}?collectionPartnerId={partnerId}

Adding Return URLs

Redirect clients back to your platform after completing a flow:

{baseUrl}?returnUrl=https://yourapp.com/done

URL Encoding Required

If your return URL contains query parameters, encode it:

const returnUrl = encodeURIComponent('https://yourapp.com/done?status=complete');
const fullUrl = `${onboardingUrl}?returnUrl=${returnUrl}`;

After completion, the user sees a "Go Back to Your App" button that links to your return URL.

Branding

Your white-label appearance is configured during partner onboarding:

Element	Configuration
Logo	Uploaded to Debitura
Background color	Hex code (e.g., #EF683C)
Font color	Optional override
Font family	Optional override

Verify your branding via the /me endpoint:

{
  "companyName": "Your Platform",
  "logoUrl": "https://debiturapublicassets.blob.core.windows.net/...",
  "backgroundColorCode": "#EF683C"
}

Handling Signing Flows

When a case is blocked by a missing signature, the API returns 422 with a solutionUrl:

{
  "businessErrors": [
    {
      "type": "MissingPowerOfAttorney",
      "message": "Power of attorney not signed with partner X.",
      "solutionUrl": "https://referral.debitura.com/sign-poa/..."
    }
  ]
}

Recommended handling:

1. Show a clear in-app message: "Action required before submitting this case"
2. Open the solutionUrl (or redirect the client)
3. After signing completes, retry the case submission

This can happen at any time—first case in a new jurisdiction, contract updates, or PoA renewal. Build it as a reusable flow.

Revoked Links

Every white-label URL carries a client link id, and Debitura re-checks that link on each request. A link that has been archived or deleted no longer authorises anything: the onboarding pages, the contract signing and contract-upgrade pages, the Power of Attorney and JPA signing pages, the KYC page, and the PDF routes all stop serving content for it.

A link is archived when the client is withdrawn (POST /clients/{externalTenantId}/withdraw), and, in the test environment, when a test client is reset. Re-linking a previously withdrawn client creates a new link with new URLs — the old ones stay dead.

What your client sees. A revoked, deleted, unknown, or malformed link all produce the same result: the user is redirected to the generic "Invalid or Missing Link" page, which asks them to contact the platform that referred them. Debitura deliberately does not distinguish these cases, so the page never reveals whether a given link ever existed. A form the client had already opened before the link was revoked is denied on submission too, before any of its content is processed.

What this means for your integration:

• Deliver URLs freshly rather than storing them for long periods, and never email a link that may since have been withdrawn.
• After a withdrawal or a test-client reset, call POST /clients again to obtain a current URL — do not re-use the previous one.
• Treat "client landed on the Invalid or Missing Link page" as a signal to re-issue, not as a Debitura outage.

Important Notes

• Link requests expire after 7 days by default if not approved. The window is configurable per partner (ApprovalTtlDays, clamped 1–30 days).
• Test environment uses testreferral.debitura.com instead of referral.debitura.com.

Business context: See White-label customization and branding options for the full list of customization options available during partner onboarding.