Branding and hosted pages

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 and your primary colour. They serve both integrations: on the Starter Integration, the solutionUrl you open leads here (plus the KYC form and invoice correction); on the Full Integration, you send users here with the URLs your API calls return.

You deliver the onboarding and approval URLs

Debitura does not email the onboarding URL when you create a client, and on the Full Integration does not email the approval URL from a 409. You deliver those URLs, in-app, by redirect or via your own emails. (On the Starter Integration, Debitura emails one approval invitation; see Who does what.)

Debitura does send two kinds of email to the users on your client's account:

• Welcome email, right after the client signs the SDCA in the onboarding flow. It contains a link to set a password and uses your welcome email template. No welcome email is sent if you have no template configured.
• Contract-signing reminders, while production cases from the client wait in PendingContractSigning: up to three, about 4 hours after the first such case and then 48 hours and 7 days after the previous reminder. Your reminder template is used if one is configured. While the SDCA is unsigned, the reminder's link opens the onboarding flow for that client. Test cases do not trigger reminders.

See Who does what for the full 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/onboarding/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; shown in the header of every page
Primary colour	Hex code (e.g., #EF683C), returned as backgroundColorCode; Debitura green if not set

The hosted pages use only your logo and this one colour. A font colour or font family on your account is not applied to the pages.

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.