Self-Service (Easy Onboarding)

Use CrefoTrust self-service links to onboard users without creating orders through the API.

Introduction

The CrefoTrust self-service gives a Verifier a hosted flow for identity verification. The Verifier does not need to create orders through the API and does not need an API key for this path. CrefoTrust creates the order in the background after the user logs in or registers.

For each case the Verifier creates one link and gives it to the user. The user completes the identification, CrefoTrust sends the result to the Verifier’s webhook, and the browser is redirected to the Verifier’s success or failure page.

Environments

Environment Self-service base URL
Test / integration https://self-service-cust.crefotrust.de
Production https://self-service.crefotrust.de

The test environment uses the test data described in Testing. Do not use real personal data in tests.

The link uses the usecase name provided by CrefoTrust and a reference:

{SELF_SERVICE_BASE}/?usecase={useCaseName}&verifierRef={reference}

Optional company context:

{SELF_SERVICE_BASE}/?usecase={useCaseName}&verifierRef={reference}&crefoId={crefoId}

Example:

https://self-service-cust.crefotrust.de/?usecase=some_use_case&verifierRef=CASE-2026-000123&crefoId=2011234567

Warning: the entry URL is user-controlled. The user can change, remove, or replace crefoId and any other query parameter before opening the link. crefoId only preselects a company; it does not bind the identification to that company and is not proof that the verified company is the intended one. The receiving webhook must check the submitted company data against the originally targeted company and handle deviations; see Webhook.

Important: the query parameter is usecase (lowercase). The older useCase spelling is not read by the self-service entry.

Reference formats

The input parameter is always verifierRef.

A plain value:

?usecase=some_use_case&verifierRef=CASE-2026-000123

is stored as:

{ "referenceId": "CASE-2026-000123" }

A URL-encoded JSON object:

?usecase=some_use_case&verifierRef=%7B%22customerRef%22%3A%22CASE-2026-000123%22%7D

is stored unchanged:

{ "customerRef": "CASE-2026-000123" }

customerRef is not a top-level query parameter. It is only an example key inside the JSON value, or the name of a redirect parameter configured by CrefoTrust.

Rules:

  • Use a unique reference per case.
  • URL-encode the value; JSON must be encoded as a whole.
  • Do not use personal data, secrets, or credentials as the reference. It is visible to the user, in browser history, and in logs.
  • A reference value is a map of strings; CrefoTrust supports up to 10 keys and 1024 characters per value. Keep the practical URL length short.
  • crefoId is optional and only applies to company cases.

Flow

  1. The user opens the link.
  2. The user logs in to the CrefoTrust self-service or registers.
  3. CrefoTrust creates the order after authentication.
  4. The user completes the identification.
  5. CrefoTrust calls the Verifier webhook.
  6. The browser is redirected to the success or failure URL.

The order is not created when the link is opened; authentication is required first. This matters when testing: a freshly opened link that only shows the login page has not created an order yet.

Webhook

CrefoTrust calls:

POST {YOUR_WEBHOOK}/{orderId}

The payload contains the released credentials and the reference under meta.verifierRef:

{
  "orderId": "6d1f5f0e-8c4f-4a1f-9d6e-0f3f5f7c9a11",
  "meta": {
    "verifier": "<verifierId>",
    "verifierRef": {
      "referenceId": "CASE-2026-000123"
    }
  }
}

WARNING: The webhook meta object will change in a future release. For now, only rely on the top-level orderId and meta.verifierRef. Do not build on the placement or shape of the other meta fields; we will announce the migration before the change is deployed.

Requirements:

  • Respond quickly with a 2xx status.
  • Process idempotently, at minimum by orderId.
  • Validate the caller using the agreed custom header and/or a network allowlist. The payload is not signed.
  • Treat the payload as personal/confidential data.
  • Verify the company against the case: the crefoId in the entry URL is user-controlled, so do not assume that the submitted company is the one that was targeted. Compare the company data in the payload (org.crefoId, org.legalName, and address) with the company stored for the case. Define how to handle deviations — for example reject the result, flag it for manual review, or start a new case — and never approve automatically on a mismatch. Treat missing company data as a deviation as well.
  • If the webhook fails, the user is redirected to the failure URL; the webhook is not automatically retried.

Success and failure URLs

CrefoTrust configures the success and failure URLs in the use case. The browser return includes orderId and the reference parameters configured in redirect.additionalQueryParams.

For the plain format, map the scalar field:

{
  "success": "https://customer.example/cases/success",
  "failure": "https://customer.example/cases/failure",
  "additionalQueryParams": [
    { "name": "orderId", "field": "id", "required": false },
    {
      "name": "verifierRef",
      "field": "options.verifierRef.referenceId",
      "required": false
    }
  ]
}

For the JSON format, map the specific key:

{
  "name": "customerRef",
  "field": "options.verifierRef.customerRef",
  "required": false
}

Example return URL:

https://customer.example/cases/success?verifierRef=CASE-2026-000123&orderId=6d1f5f0e-8c4f-4a1f-9d6e-0f3f5f7c9a11

Important:

  • The failure URL is not a guaranteed callback. On abort, identification errors, timeouts, or other terminal failures, the user may never reach it.
  • Do not treat orderId or the reference from the URL as proof of authorization. Enforce authorization in your own application.
  • The webhook is authoritative for reconciliation.
  • Set a restrictive Referrer-Policy on the success/failure pages; the reference is in the URL.

Testing

Use the test environment and the static or prepared test data described in Testing. The fixed test data is available at /static_mocks.json.

Test checklist:

  • Open the link with a unique plain verifierRef.
  • Log in or register with a test user.
  • Confirm the order is created after authentication.
  • Complete the identification with the agreed test data.
  • Verify the webhook meta.verifierRef matches the reference.
  • Verify the success URL contains the mapped reference and orderId.
  • Verify the webhook custom header and idempotency.
  • Verify the failure/abort behavior when the failure URL is reached.
  • Do not use personal/secret data as the reference.

Security

  • The reference is user-controlled input and must not be used as an authorization credential.
  • The entry URL is user-controlled. crefoId and verifierRef can be changed or removed by the user and are not binding; verify the webhook result against your stored case data.
  • Use an opaque reference; do not put names, email addresses, tax IDs, or secrets in the URL.
  • Keep the webhook protected with the agreed custom header and/or network allowlist.
  • The webhook payload is not signed.
  • Treat the reference as data that may appear in browser history, access logs, proxy logs, and Referer headers.