Source: https://docs.debitura.com/referral-partners/concepts/white-label-ui

# Branding and hosted pages

Debitura's branded onboarding experience for your clients.

<a id="overview"></a>

## 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](https://docs.debitura.com/referral-partners/concepts/responsibility-matrix.md).)

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](https://docs.debitura.com/referral-partners/concepts/responsibility-matrix.md) for the full breakdown.

<a id="when-its-used"></a>

## 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 |

<a id="url-structure"></a>

## URL Structure

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

```text
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}
```

<a id="adding-return-urls"></a>

## Adding Return URLs

Redirect clients back to your platform after completing a flow:

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

URL Encoding Required

If your return URL contains query parameters, encode it:

```javascript
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.

<a id="branding"></a>

## 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:

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

<a id="handling-signing-flows"></a>

## Handling Signing Flows

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

```json
{
  "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.

<a id="revoked-links"></a>

## 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](https://docs.debitura.com/referral-partners/getting-started/environments.md#reset-test-clients). 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.

<a id="important-notes"></a>

## 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](https://support.debitura.com/en/articles/13907378-referral-partners-white-label-customization-and-branding-options) for the full list of customization options available during partner onboarding.