Evrotrust (eIDV)

Capability: eIDV

Market: Europe (Bulgaria, North Macedonia)

Business Capabilities

Use this connector to run electronic identity verification through Evrotrust, an EU-qualified trust service provider (QTSP) used by the PCB banking profiles. The connector launches a verification session in the Evrotrust WebSDK, receives the result asynchronously through a callback, and lets the platform poll status and retrieve the verified identity data.

The connector lets you:

  • Start a verification session - returns a self-submitting HTML form that posts encrypted user data to the Evrotrust WebSDK and opens the identity flow for the end user.
  • Receive the verification result - Evrotrust calls back when the flow completes. The connector enriches the result with human-readable labels, forwards it to the platform through a webhook, and optionally redirects the user's browser.
  • Validate a reference id - check whether an Evrotrust-issued reference id is valid.
  • Fetch identity data - retrieve the full identification data of a completed verification.
  • Get verification status - poll the current status of a verification.

Exposed Endpoints

All endpoints are served under the base path /api/eidv/v1/evrotrust.

  • Initiate verification session: GET /verify
  • Verification callback (vendor to connector): GET /callback
  • Validate a reference id: GET /validate-ref-id/{referenceId}
  • Get identification data: GET /get-data/{referenceId}
  • Get verification status: GET /status

Evrotrust invokes the /callback endpoint, so exclude it from authentication.

Required Request Headers

  • DC-Client-Id (required) - Client profile identifier that selects the Evrotrust credentials and configuration to use, for example pcb-bg or pcb-mk.
  • DC-Webhook-Id (required on /verify) - Webhook destination for the callback result. Must match an id configured in evrotrustFtosRedirectUrls and webhookConfig.endpoints for the selected profile, for example bg-dev, bg-uat, or mk-dev.

Vault Configuration

The connector resolves configuration per client profile, selected by the DC-Client-Id header. Each profile requires the following values:

  • evrotrustVendorApiUrl - Base URL of the Evrotrust vendor API.
  • evrotrustVendorNumber - Evrotrust vendor number identifying the account.
  • evrotrustVendorApiKey - Secret API key. The connector SHA-256 hashes it and uses it as the HMAC key for vendor request authentication.
  • evrotrustAuthUrl - OAuth token endpoint base URL (/authorize/gettoken).
  • evrotrustClientId - OAuth client id (client-credentials grant).
  • evrotrustClientSecret - OAuth client secret.
  • evrotrustSdkUrl - Evrotrust WebSDK URL that the generated HTML form posts to.
  • evrotrustPublicKey - RSA public key (PEM) that encrypts the enc-data payload.
  • evrotrustCallbackUrl - Redirect/callback URL embedded in the encrypted verification data.
  • evrotrustFtosRedirectUrls - List of { id, url } that maps a DC-Webhook-Id to a browser redirect base URL.
  • evrotrustStatusLabels - Map of status code to human-readable label.
  • evrotrustUnsuccessReasonLabels - Map of unsuccess-reason code to human-readable label.

Platform infrastructure values (app.cma.url, app.idp.url, app.vault.secrets.engine) are set in application.properties.

Authentication

The connector handles two authentication mechanisms server-side. The caller never supplies a vendor token.

  • OAuth 2.0 client-credentials - for the WebSDK session, the connector obtains a websdk-scoped access token from evrotrustAuthUrl/authorize/gettoken using evrotrustClientId and evrotrustClientSecret. It caches tokens (keyed by client id, with a 30-second expiry skew) and reuses them until they expire.
  • HMAC-SHA256 - for vendor API calls (validate-ref-id, get-data, status), the connector signs the exact request body, keyed by SHA-256(evrotrustVendorApiKey), and sends it in the Authorization header.

The connector also RSA-encrypts the enc-data payload posted to the WebSDK (RSA/ECB/PKCS1Padding) with evrotrustPublicKey and hex-encodes it.

Verification Flow

  1. The caller sends GET /verify with DC-Client-Id, DC-Webhook-Id, and query parameters. The connector appends a random _<8 hex> suffix to externalReference (Evrotrust caps it at 32 characters) to make each attempt unique, persists a session (unique reference mapped to the original reference, redirect URL, webhook id, and client id), and returns a self-submitting HTML form.
  2. The browser posts the form to the Evrotrust WebSDK, and the user completes identity verification.
  3. Evrotrust calls GET /callback. The connector looks up the session, builds a webhook payload (returning the original externalReference, without the suffix), resolves status and unsuccess-reason labels, dispatches the webhook (evrotrustFtosWebhook), deletes the session, and, if a redirect URL was stored, responds 303 See Other to send the user's browser back.
  4. The caller retrieves results through /status and /get-data/{referenceId}.

Request Structures and Samples

GET /api/eidv/v1/evrotrust/verify

Query parameters:

  • externalReference (required) - Platform-side identifier (max 23 characters). The connector appends _<8 hex> before sending it to Evrotrust; the callback webhook returns the original value.
  • lang - UI language (default en).
  • userPid - User's personal identification number.
  • userCountry - ISO country code, for example BG.
  • userDocumentType - Evrotrust document type code.
  • colorData - URL-encoded JSON object with branding colors.
  • redirectUrl - Query-string suffix appended to the configured redirect base URL.
Copy 
GET /api/eidv/v1/evrotrust/verify?externalReference=cust-4821&lang=bg&userCountry=BG&userDocumentType=1
                DC-Client-Id: pcb-bg
        DC-Webhook-Id: bg-dev

The response is 200 OK with content type text/html: a self-submitting form that the browser renders and posts to the Evrotrust WebSDK.

Copy 
<!DOCTYPE html><html><body>
                <form id="f" method="POST" action="https://websdk.evrotrust.com/...">
                <input type="hidden" name="vendor-number" value="123456">
                <input type="hidden" name="token" value="******">
                <input type="hidden" name="enc-data" value="9af3c1...hex...">
                </form>
                <script>document.getElementById('f').submit();</script>
        </body></html>

GET /api/eidv/v1/evrotrust/callback

Evrotrust calls this endpoint with the query parameters external_reference_id, reference_id, status, unsuccess_reason, and error. The connector forwards the enriched payload to the platform webhook:

Copy 
{
    "externalReferenceId": "cust-4821",
    "referenceId": "1a2b3c4d-5e6f-...",
    "status": 2,
    "statusLabel": "Verified",
    "unsuccessReason": null,
    "unsuccessReasonLabel": null,
    "error": null
}

The connector responds 200 OK (webhook dispatched) or 303 See Other (redirect to the URL stored at session initiation). If it finds no stored session (already processed or expired), it responds 200 OK and skips the dispatch.

GET /api/eidv/v1/evrotrust/validate-ref-id/{referenceId}

Copy 
{ "valid": true }

GET /api/eidv/v1/evrotrust/status

Supply at least one of referenceId or externalReferenceId.

Copy 
{
    "referenceId": "1a2b3c4d-...",
    "status": 2,
    "statusLabel": "Verified"
}

Error Codes

400 Bad Request - validation error:

Copy 
{
    "status": 400,
    "title": "Constraint Violation",
    "instance": "/eidv/v1/evrotrust/verify",
    "timestamp": "2025-04-29T15:34:22Z",
    "errors": [
        { "pointer": "initiateSession.externalReference", "detail": "must not be null" }
    ]
}

Other notable responses:

  • 400 Bad Request - Missing DC-Webhook-Id header; externalReference longer than 23 characters; invalid colorData JSON; no redirect URL configured for the given DC-Webhook-Id; /status called with neither referenceId nor externalReferenceId.
  • 303 See Other - Callback with a stored redirect URL, which sends the user's browser back to the platform.