PinLetters

Describes the rational behind the “PinLetters” concept, the technicalities to obtain short codes and pins for further processing as well as the integration with the “normal” CrefoTrust process.

Introduction

“PinLetters” or sometimes referenced as “VC-Ident-Process”, is an umbrella term and consists of a special API, a process, and a new credential (an authorization token).

Via an API, a registered Verifier can obtain “Short Codes” and “PINs” for a list of known Crefonummers (crefoIDs). Each shortCode-and-PIN-combination (pinOrder) allows the person receiving this information to acquire an “Agent Credential”, which authorizes the person to act as an agent for the company the PIN and shortCode have been generated for.

Getting ShortCode/PIN

The API is designed to provide shortCode-and-PIN-combinations (pinOrders) en batch. Your request body contains a list (array) of Crefonummer (crefoIds) for which pinOrders (shortCode-PIN-combinations) should be generated. To create only one pinOrder your request’s list contains only one crefoID.

Additionally you have to define which use case the user will enter, when later using the shortCode/PIN to engage with CrefoTrust and therefor send him or her to the correct service after completion. Use cases are created by the CrefoTrust team and you reference them in the request’s body by name.

The Swagger documentation is here.

Endpoint

Produktion:

POST https://pin.crefotrust.de/api/v2/order

Integration:

POST https://pin-cust.crefotrust.de/api/v2/order

Authentication

To authenticate your request you have to provide these two values as part of your request headers.

x-crefotrust-key: [API_KEY]

x-verifier-id: [VERIFIER_ID]

Body

{
  "crefoIds": [
    "1231234567",
    "2341234567",
    "1234" //an invalid crefoId
  ],
  "useCase": "ubo"
}

Response

Status

  • 200 OK
  • 400 Invalid
  • 401 Unauthorized

Body

The response’s body contains a matching list of elements. The order of the elements in the response is not guaranteed to match the order of elements in the request.

For each requested crefoId one element is returned. This element represents either a successful creation of a pinOrder or an error case.

Example:

[
  {
    "crefoId": "1231234567",
    "baseTargetUrl": "https://pin.crefotrust.de/myesg",
    "targetUrl": "https://pin.crefotrust.de/myesg/AbF2s92",
    "shortCode": "AbF2s92",
    "pin": "223311",
    "status": "success",
    "validUntil": "2023-05-03T12:34:55Z"
  },
  {
    "crefoId": "2341234567",
    "baseTargetUrl": "https://pin.crefotrust.de/myesg",
    "targetUrl": "https://pin.crefotrust.de/myesg/auy11aF",
    "shortCode": "auy11aF",
    "pin": "562311",
    "status": "success",
    "validUntil": "2023-05-03T12:34:55Z"
  },
  {
    "crefoId": "34",
    "error": "Invalid Crefo",
    "status": "failure"
  }
]

Send The Letter

Commonly the next step is taking the shortCode (or the targetUrl encoded as an QR Code) and PIN and print it on a letter (including some instructions). This letter is then send to the company’s address with the receipient for which an agent credential should be created. You are free to send the information by Email or even display it on the users profile page.

Receiving The Letter

After the letter arrives the designated company agent uses the provided instructions to open the CrefoTrust PinLetter URL in a web browser. Either by typing in the generic one (e.g. https://pin.crefotrust.de), where the user has to enter the shortCode and PIN. Or better, by scanning the QR code (representing the targetUrl), where the shortCode is included in the URL and only the PIN has to be provided by the user.

Either way the user has to type in the PIN provided by the letter.

Create an Account

After verifying the correctness of the provided information, the user is forwarded to the “normal” CrefoTrust process, which requires the user to authenticate with a Creditreform SSO Account. The user might login to an existing account or create a new one.

Processing and Forwarding

After the user has logged-in / registered, the CrefoTrust app validates all information around this order and creates and stores an Agent Credential if everything looks good. Usually the Credential is then send to an internal Webhook, which creates an “UNTERNEHMENSAGENT” role in Creditreform SSO. Alternatively a different webhook can be configured for your user case. Please ask us, if you need help to setup your own webhook.

When the credentials have been successfully sent, the user is redirected to the success redirect, which is configurable on the use case as well.

Presets and UseCases

CrefoTrust needs some information on how to handle a pinOrder (and a regular order for that matter) and provides here some flexibility for the Verifier.

The verifier has the option to specify useCases for different usage scenarios. Each useCase can have a different webkook, different redirects, and different credentials requested.

The actual endpoints to setup and alter use case definitions are in a pre-alpha state and will likely change in future versions. For now it’s best to contact us for the setup of additional use cases.