Integration guide

Integration guide

TRIDENT Wallet Verification API

Sandbox Integration Guide

1. Purpose

This guide provides an introductory overview of how Government services and authorized relying parties can request and verify digital credentials presented through the TRIDENT Wallet.

Relying parties integrate with the TRIDENT Wallet Verification API, which manages the credential presentation journey with the Wallet and returns a verified, structured result to the requesting application.

The presentation flow follows OpenID for Verifiable Presentations — OpenID4VP.

This guide focuses on the integration model and the main information exchanged. Environment-specific URLs, credentials, schemas, and API collections are provided through the TRIDENT Integration Portal.

2. Integration Model

The TRIDENT Wallet Verification API provides a common integration layer between:

  • the relying party application;
  • the citizen’s TRIDENT Wallet;
  • trusted credential issuers; and
  • the TRIDENT trust and governance services.

The relying party defines what information is required for an approved service or use case.

TRIDENT creates the corresponding presentation request, delivers it to the Wallet, validates the returned credentials, and provides the relying party with the verification result.

This model allows relying parties to use wallet credentials without implementing the complete OpenID4VP protocol and credential-verification logic independently.

3. Main Participants

User

The citizen who holds digital credentials in the TRIDENT Wallet and decides whether to present the requested information.

Relying Party

The Government agency or authorized third-party application requesting credential information for an approved purpose.

TRIDENT Wallet

The citizen’s mobile application used to receive, store, and present digital credentials.

TRIDENT Wallet Verification API

The service that creates presentation transactions, manages the OpenID4VP exchange, verifies the returned credentials, and provides the result to the relying party.

Credential Issuer

The trusted authority that issued the credential.

Examples may include:

  • EBC as the issuer of the TRIDENT PID;
  • Government agencies issuing sector-specific credentials; and
  • authorized issuers using TRIDENT Shared Credential Services.

4. Integration Prerequisites

Before using the Verification API, the relying party must be registered and enabled in the TRIDENT ecosystem.

Its integration configuration includes:

  • relying party identity;
  • approved services and intended uses;
  • permitted credential types;
  • permitted attributes or verification results;
  • callback or response URLs;
  • authentication credentials;
  • applicable trust configuration; and
  • audit and data-protection requirements.

A relying party should request only the information required for its approved use case.

5. High-Level Verification Flow

  1. The user starts a service in the relying party application.
  2. The relying party creates a verification transaction through the TRIDENT Wallet Verification API.
  3. The request identifies the credential types and attributes required for the service.
  4. TRIDENT returns a Wallet presentation link or QR code associated with the transaction.
  5. The user opens or scans the request using the TRIDENT Wallet.
  6. The Wallet identifies the relying party and displays:
    • who is requesting the information;
    • the purpose of the request; and
    • the credential attributes requested.
  7. The user authenticates to the Wallet and approves or rejects the presentation.
  8. The Wallet returns the approved credential presentation through the OpenID4VP flow.
  9. TRIDENT validates the presentation and produces a verification result.
  10. The relying party receives or retrieves the result and continues its service journey.

6. OpenID4VP Presentation Request

The Verification API creates an OpenID4VP Authorization Request on behalf of the relying party.

At a logical level, the request includes:

  • the relying party identifier;
  • the requested credential types;
  • the required attributes;
  • a unique transaction nonce;
  • the response mode;
  • the response endpoint;
  • the intended use of the information; and
  • any required holder-binding or assurance conditions.

Credential requirements may be expressed through:

  • a DCQL query, defining the required credentials and claims; or
  • a predefined request profile associated with the relying party’s use case.

The relying party does not need to construct the complete OpenID4VP message directly when using the TRIDENT Verification API.

7. Starting the Wallet Journey

The Verification API supports the main remote presentation patterns.

Cross-Device Journey

The relying party displays a QR code on a desktop, kiosk, or another device.

The user scans the QR code using the TRIDENT Wallet on their mobile phone.

The QR code references the presentation request rather than containing the complete credential request.

Same-Device Journey

The user accesses the relying party service and the TRIDENT Wallet on the same mobile device.

The relying party launches the Wallet presentation journey through the supported application or browser mechanism.

Both journeys use the same verification transaction and return the result through the Verification API.

8. User Review and Selective Disclosure

Before presenting any information, the Wallet informs the user about:

  • the identity of the relying party;
  • the purpose of the request;
  • the credentials involved; and
  • the specific attributes requested.

The user can then approve or reject the presentation.

Where supported by the credential format and request profile, selective disclosure allows the Wallet to present only the attributes required for the service.

For example, a relying party may request:

  • confirmation that the user is over 18, rather than the complete date of birth;
  • the user’s parish, rather than the complete address; or
  • the user’s name and identity status, rather than the complete PID.

The relying party remains responsible for requesting only information that is necessary for its approved purpose.

9. Wallet Response

After user approval, the Wallet returns an OpenID4VP response containing a vp_token.

The response is cryptographically bound to the verification transaction through values such as the transaction nonce.

Depending on the configured profile, the Wallet response may be sent using:

  • direct_post; or
  • direct_post.jwt for an encrypted response.

The Verification API receives and processes this response before making the result available to the relying party.

10. Verification Performed by TRIDENT

The Verification API applies the controls required by the applicable credential and trust profiles.

These may include:

  • transaction and nonce validation;
  • response integrity validation;
  • credential format validation;
  • issuer signature verification;
  • issuer trust validation;
  • credential validity-period checks;
  • credential status or revocation checks, where applicable;
  • holder or device-binding validation, where required;
  • confirmation that the presented credential matches the request;
  • confirmation that only authorized attributes were returned; and
  • validation of combined presentations when more than one credential is used.

A technically valid credential does not by itself determine the business outcome. The relying party remains responsible for applying its service-specific eligibility and decision rules.

11. Verification Result

The Verification API provides the relying party with a structured result associated with the original transaction.

The result may contain:

  • transaction identifier;
  • transaction status;
  • overall verification outcome;
  • credential types presented;
  • verified attributes or derived results;
  • credential issuer information;
  • trust-validation outcome;
  • credential status;
  • holder-binding outcome, where applicable;
  • presentation timestamp;
  • validation warnings; and
  • error information when verification is unsuccessful.

An illustrative result may represent:

Verification status: VERIFIED

Credential:
TRIDENT Mobile National ID

Issuer:
Electoral and Boundaries Commission

Verified information:
- Given name
- Family name
- Over 18: true
- Identity status: valid

The API may provide normalized attributes to simplify relying party integration across the credential formats enabled in the TRIDENT ecosystem.

12. Combined Credential Presentation

A single use case may require information from more than one credential.

For example, a Government service may request:

  • identity information from the TRIDENT PID; and
  • professional status from a credential issued by another authorized institution.

The Verification API can represent these requirements in one presentation transaction.

TRIDENT verifies each credential and, where required, confirms that the credentials belong to the same Wallet holder before returning the combined result.

13. Main Integration Operations

At a high level, a relying party uses the Verification API to perform four operations.

Create a Verification Transaction

Define the use case and the credential information required.

Obtain the Wallet Presentation Request

Receive the Wallet launch link or QR code associated with the transaction.

Receive or Retrieve the Result

Use a callback notification or transaction-status operation to determine when the presentation has been completed.

Process the Verified Information

Apply the relying party’s business rules using the verified result returned by TRIDENT.

Detailed endpoint paths, payload schemas, authentication requirements, and error codes are defined in the Verification API reference.

14. Transaction Status

A verification transaction may use statuses such as:

  • PENDING
  • AWAITING_USER
  • RECEIVED
  • VERIFIED
  • REJECTED
  • EXPIRED
  • FAILED

The relying party should handle incomplete, rejected, expired, and unsuccessful transactions without assuming that a credential presentation has taken place.

15. Security and Data Protection

Wallet integrations should apply the following principles:

  • Purpose limitation: request credentials only for a defined service purpose.
  • Data minimization: request only the required attributes.
  • Selective disclosure: use derived or limited information where possible.
  • Relying party authentication: allow the Wallet to identify the requester.
  • User transparency: explain who is requesting the information and why.
  • Transaction protection: use fresh nonces and short transaction lifetimes.
  • Secure communication: protect API, callback, and presentation endpoints.
  • Controlled retention: retain presentation data only according to the approved policy.
  • Auditability: record the request, relying party, purpose, outcome, and relevant technical events.
  • Separation of duties: distinguish technical credential verification from the relying party’s business decision.

Raw credentials and personal attributes should not be logged unless specifically required and protected under the applicable retention and security policy.

16. Sandbox Use Cases

The Sandbox Verification API allows participants to explore scenarios such as:

  • presenting a TRIDENT PID to identify a citizen;
  • confirming that a citizen is over a required age;
  • presenting selected address information;
  • validating a credential issued through TRIDENT Shared Credential Services;
  • presenting credentials from more than one trusted issuer;
  • using a credential to access a Government procedure;
  • testing selective disclosure; and
  • integrating a relying party application with a wallet-based journey.

The credentials, attributes, issuers, and business rules available in the Sandbox are reference implementations used to demonstrate the future TRIDENT Wallet ecosystem.

Final definitions remain subject to the competent Barbados authorities and the applicable TRIDENT governance process.

17. Expected Integration Result

After completing the integration, an authorized relying party will be able to:

  • create credential-verification transactions;
  • launch same-device or cross-device Wallet journeys;
  • request approved credentials and attributes;
  • receive OpenID4VP presentations through TRIDENT;
  • obtain a normalized verification result;
  • apply selective-disclosure and data-minimization patterns; and
  • integrate verified Wallet information into its digital services.