Your brand.
Our infrastructure.

# Didit White Label — integrate in 5 minutes

You are integrating Didit's White Label (custom branding + custom domain)
into <my_stack>. White Label is a CONFIGURATION on top of any workflow —
not a separate API endpoint. Follow these steps exactly. Every URL,
header, and field below is canonical — do not paraphrase or "improve" them.

## 1. Provision an account
- Sign up: https://business.didit.me (no credit card required).
- Or provision programmatically: POST https://apx.didit.me/auth/v2/programmatic/register/
  (returns an API key bound to the workspace + application).

## 2. Configure White Label in the console
White Label settings live at Console -> White Label -> Style Editor. Five
groups, every one is customizable:

- Colors           — buttons, text, panels, backgrounds (every color element)
- Typography       — upload a brand font, set heading + body weights
- Logos            — square + rectangular variants, served on every screen
- Layout           — border radius for panels, buttons, inputs
- Login screen     — show or skip the user-login step entirely
- Custom domain    — host the verification UI on your own subdomain
                     (e.g. verify.acme.com) instead of verify.didit.me

Custom-domain setup:
1. Console -> White Label -> Custom Domain -> Add domain
2. We return a CNAME target. Point your subdomain CNAME at it.
3. Click Verify. We provision a TLS certificate via Let's Encrypt /
   ACME (automatic renewal, no action required from you).
4. Domain becomes live within minutes.

Custom email-from:
- Console -> White Label -> Email -> set the "From" name + reply-to address.
- DKIM / SPF records returned for you to add to DNS.

## 3. Enable White Label on each workflow
The customization does NOT auto-apply. You enable it per workflow:

1. Console -> Workflows -> open the workflow you want to brand.
2. Click Settings (gear icon).
3. Under Options, find "Include custom style".
4. Enable the toggle. Save.

Workflows without the toggle keep the default Didit branding — useful for
sandbox flows you do not want to brand yet.

## 4. Use the white-labeled workflow from your stack
Once the workflow has white-label enabled, you call it the same way as any
other Didit workflow:

POST https://verification.didit.me/v3/session/
Authorization header:  x-api-key: <your-api-key>
Body:
  - workflow_id   (required, your white-labeled workflow id)
  - vendor_data   (optional, your own user id)
  - callback      (optional, URL we redirect to after the flow)

Response: { session_url } — redirect the user there. The UI they see is
your brand (your logo, your colors, your typography), on your domain
(verify.acme.com), with your "From" name on every email we send to the
user mid-flow.

## 5. Webhooks
- Register a webhook destination once via
  POST https://verification.didit.me/v3/webhook/destinations/
  Body: url, subscribed_events: ["session.verified", "session.review_started",
                                  "session.declined", "session.kyc_expired"]
- Response includes secret_shared_key — store it.
- Every webhook delivery carries an X-Signature-V2 header you MUST verify
  before trusting the payload.  HMAC-SHA256 verification MUST run against the raw body bytes (the raw payload as Didit sent it) BEFORE any JSON parsing — re-serialising the parsed body changes whitespace and key order, which invalidates the signature.Algorithm:
    1. sortKeys(payload) recursively
    2. shortenFloats (truncate trailing zeros after the decimal point)
    3. JSON.stringify the result
    4. HMAC-SHA256 with the secret_shared_key
    5. Hex-encode, compare to the X-Signature-V2 header.

## 6. Hard rules - do not change
- Base URL for /v3/* endpoints is verification.didit.me (NOT apx.didit.me).
- Auth header is x-api-key (lowercase, hyphenated).
- Webhook signature header is X-Signature-V2 (NOT X-Signature).
- Status casing matches exactly: "Approved", "Declined", "In Review",
  "Not Finished" (title-cased, space-separated).
- White Label is a configuration on a workflow — there is NO standalone
  /v3/white-label/ endpoint. Do not invent one.
- Removing visible Didit branding does NOT remove your obligations as the
  controller of the user journey. You still surface your privacy notice,
  link Didit's Verification Privacy Notice + End User Terms, and collect
  explicit consent before document + biometric capture where the law
  requires it. See https://docs.didit.me/console/white-label for the full
  controller-side checklist.

## 7. Reseller / OEM positioning
White Label is the same product your agency, integrator, or compliance-
consulting firm uses to resell Didit under your own name to your own
customers:

- Pricing: $0.20 per session on top of the underlying module price (e.g.
  full Know Your Customer (KYC) bundle at $0.33 + $0.20 white label = $0.53 per session, or
  standalone ID at $0.15 + $0.20 = $0.35).
- 500 free verifications per month stay applied to your own meter,
  regardless of how many resold tenants you have.
- One contract with Didit, one invoice — your customers see only your
  brand and your support address.
- Custom email-from + custom domain mean your customers never see Didit
  branding mid-flow. We still surface the legally-required disclosures
  per the controller-side checklist above.

## 8. Pricing reference (public)
- White Label add-on: $0.20 per session, on top of the underlying module
  price. A full KYC bundle goes from $0.33 to $0.53 per white-labeled
  session; a standalone $0.15 ID Verification goes to $0.35.
- 500 free verifications every month, forever, on every account — applies
  regardless of whether the flow is white-labeled.
- No setup fee, no certificate cost, no per-domain charge.

## 9. Verify your integration
- Sandbox starts on signup at https://business.didit.me - no separate flag.
- Test custom domain locally by adding a /etc/hosts entry pointing your
  brand subdomain at our CNAME target before DNS is live.
- Switch to live: flip the application's environment toggle in console.

When in doubt: https://docs.didit.me/console/white-label