Testing

How to approach testing your CrefoTrust integration.

Introduction

To ease the integration of CrefoTrust we provide special systems and services that allow for very targeted testing strategies. These system are only available on our testing environments of course.

Authentication

The test preparation endpoint currently does not require authentication. We reserve the right to change this at any time; known users will be contacted on short notice if anything changes.

The self-service flow is different: the user logs in or registers through the CrefoTrust test SSO. It does not use an API key in the browser.

Preparing A Test

The testing system gives you the opportunity to exactly specify what data CrefoTrust will get from it’s 3rd party integrations. So that you can exactly mimic the different scenarios and monitor the outcome to expect.

Here is an example code snippet. That should help you get started.

  const body = `{
    "selectedCompany": {
      "crefoId": "1673937671",
      "legalName": "testCompany",
      "legalForm": "GmbH",
      "addressLocality": "Köln",
      "addressCountry": "DE",
      "postalCode": "47800",
      "streetAddress": "Waldweg",
      "streetNumber": "12",
      "status": "aktiv",
      "representatives": [
        {
          "crefoId": "4561234567",
          "familyName": "Musterhaus",
          "givenName": "Werni",
          "postalCode": "12345",
          "birthdate": "1991-01-12",
          "birthplace": "Waren"
        },
        {
          "crefoId": "4561234569",
          "familyName": "Onade",
          "givenName": "Lem",
          "postalCode": "12346",
          "birthdate": "1978-11-10",
          "birthplace": "Waren"
        }
      ]
    },
    "searchResults": [
      {
        "crefoId": "1237654321",
        "legalName": "Company One",
        "legalForm": "GmbH",
        "addressLocality": "Köln",
        "addressCountry": "DE",
        "streetAddress": "Sollbrüggenstr.",
        "streetNumber": "14",
        "postalCode": "47800",
        "status": "aktiv",
        "representatives": [
          {
            "crefoId": "1231234567",
            "familyName": "P",
            "givenName": "Dirk",
            "postalCode": "47800",
            "birthdate": "1978-09-30",
            "birthplace": "Waren"
          }
        ]
      },
      {
        "crefoId": "1237654321",
        "legalName": "Company Three",
        "legalForm": "GmbH",
        "addressLocality": "Köln",
        "addressCountry": "DE",
        "streetAddress": "Sollbrüggenstr.",
        "streetNumber": "14",
        "postalCode": "47800",
        "status": "aktiv",
        "representatives": [
          {
            "crefoId": "1231234567",
            "familyName": "F",
            "givenName": "Dirk",
            "postalCode": "47799",
            "birthdate": "1978-09-30",
            "birthplace": "Waren"
          },
          {
            "crefoId": "42312884567",
            "familyName": "J",
            "givenName": "Dirk",
            "postalCode": "66555",
            "birthdate": "1978-10-31",
            "birthplace": "Waren"
          }
        ]
      }
    ]
  }`

  const url = 'https://env-coordinator.cust.dev-cluster.crefotrust.de:3001/prep';
  const resp = await fetch(url, {
    method: 'POST',
    body: body,
    headers: {
      'Content-Type': 'application/json',
    },
  });
  const json = await resp.json();

From the response you will get a verifierID and apiKey that must be used in subsequent calls to the CrefoTrust API as the authentication information. This ensures that your test is properly encapsulated and knows exactly the data you just send it.

Furthermore does the response contain a webhook which can be used in the order you create to engage the CrefoTrust process. This might be useful if you don’t have a backend system in place and want to see what data is send after the process completes. There is a corresponding GET endpoint which will give you the data, that the webhook received.

The involved types are listed here:

export interface Representative {
  crefoId: string;
  familyName: string;
  givenName: string;
  postalCode: string;
  addressLocality?: string;
  addressCountry?: string;
  birthdate: string;
  birthplace: string;
}

export interface Company {
  crefoId: string;
  legalName: string;
  legalForm: string;
  addressLocality: string;
  addressCountry: string;
  streetAddress: string;
  streetNumber: string;
  postalCode: string;
  status: string;
  representatives: Representative[];
}

//body type
export interface PrepReq {
  selectedCompany: Company;
  searchResults: Company[];
}

export interface PrepResp {
  verifierId: string;
  verifierApiKey: string;
  verifierName: string;
  selectedCompany: Company;
  webhook: string;
}

Bear in mind that the data you provide is kept only in memory. It will NOT be stored to disk or database. After a pod restarts, the data will be lost. So in order to smoothly and reliably run tests keep the setup and the actual test run in temporal proximity.

We might open source the testing code at some point in the future. When you need more code examples feel free to contact us and we will happily provide them to you.

Fixed Test-Data

To simplify testing, when it’s not necessary to have full control on the data that is known to CrefoTrust, you can rely on the fixed test data. It is used when no special /prep setup took place.

The file contains test companies and their representatives. For example:

Company crefoId Example representatives
AutoIdent VideoIdent Testcase GmbH 4386541530 Knut Kueste, Paul Mustermann, Mallory Mustermann

Use these test personas in the self-service flow or in API-created test orders. The fixed data is only valid in the test environments; never use it in production.

If you need full control over the company data, use the /prep endpoint described above instead. That data is kept in memory and overrides the fixed data for the test verifier.

Testing the self-service (easy onboarding) flow

The self-service link does not use an API key and does not create an order until the user logs in. See Self-Service (Easy Onboarding) for the link and reference formats.

Typical test:

https://self-service-cust.crefotrust.de/?usecase=<useCaseName>&verifierRef=<unique-reference>
  1. Open the link in a private browser window.
  2. Confirm that only the login/registration view appears. No order exists yet.
  3. Log in or register with a test user.
  4. Complete the identification with the fixed test data.
  5. Verify the webhook result contains meta.verifierRef with the reference.
  6. Verify the success URL contains the mapped reference and orderId.

Use a unique verifierRef per test. The input parameter is verifierRef; a top-level customerRef parameter is ignored. A plain value is stored as { "referenceId": "<value>" }; a URL-encoded JSON object is stored unchanged.

The failure URL is not a guaranteed callback. On abort, identification errors, or timeouts, the user may never reach it; use the webhook for reconciliation.

The webhook meta object will change in a future release. Only the top-level orderId and meta.verifierRef are stable; do not build on the other meta fields.

Running A Test

WARNING: The direct POST /api/orders create-order flow is currently known to be faulty. Prefer the self-service flow above for end-to-end tests. Contact CrefoTrust before relying on the direct order path.

To actually run a test, you construct an order specific to your use case (with the credentials that you want to receive from your customer). See the main documentation for details.

Then you send this order to the CrefoTrust endpoint either authenticating with the preparation response or your default authentication information. The rest is basically: you going through the CrefoTrust process instead of an actual user.

At one step in the process it is necessary to login or create an account with the Creditreform-SSO-system. The configured system is a test system as well, but it requires an opt-in step, verifying your email address, like the production SSO-system.

In order to proceed here, you can use a fake-mail-server we have set up for exactly this testing purposes: http://fake-mail-server.crefotrust.de/