Skip to content

Velocity Integration

Overview

This user story covers the integration with the Velocity Credential Agent to issue credentials on the Velocity Network, ensuring proper formatting, status synchronization, and error handling.

User Stories

Integrate with Velocity Credential Agent

As a platform administrator,
I want to integrate with the Velocity Credential Agent,
So that credentials can be issued on the Velocity Network and candidates can claim them through their digital wallets.

Acceptance Criteria: - Given the platform is configured with Velocity SDK credentials - When a credential is created (manually or via batch) - Then the system should connect to the Velocity Credential Agent API - And the credential should be formatted according to Velocity Network standards - And the credential should be successfully issued on the Velocity Network - And the system should receive a credential offer ID from Velocity - And the credential status should be tracked in the platform database - And error handling should be in place for failed issuance attempts - And the integration should work for both manual and batch credential issuance

Handle Credential Status Updates

As a platform administrator,
I want to receive and process credential status updates from the Velocity Network,
So that the platform reflects the current status of all issued credentials.

Acceptance Criteria: - Given a credential has been issued on the Velocity Network - When the credential status changes (offered, claimed, expired, revoked) - Then the system should receive status updates from Velocity - And the platform database should be updated with the new status - And users should see the updated status in the credential dashboard - And appropriate notifications should be sent for status changes - And the system should handle webhook notifications from Velocity - And status updates should be processed in real-time where possible

Implement Error Handling and Retry Logic

As a platform administrator,
I want to implement robust error handling and retry mechanisms,
So that temporary failures don't prevent credential issuance and the system remains reliable.

Acceptance Criteria: - Given a credential issuance request fails - When the failure is due to a temporary issue (network timeout, service unavailable) - Then the system should automatically retry the request - And the system should use exponential backoff for retry attempts - And the system should limit the number of retry attempts (maximum 3) - And permanent failures should be logged and reported to administrators - And users should be notified of failed credential issuance - And failed credentials should be marked for manual review - And the system should provide detailed error messages for troubleshooting

Configure Velocity SDK Settings

As a platform administrator,
I want to configure Velocity SDK settings through environment variables,
So that the integration can be properly configured for different environments (sandbox, production).

Acceptance Criteria: - Given I need to configure the Velocity integration - When I set the required environment variables - Then the system should validate all required configuration: - VNF_SDK_API_KEY - SDK access key - VNF_SDK_ENVIRONMENT - sandbox or production - VNF_SDK_DID - Organization DID - VNF_SDK_PRIVATE_KEY - Private key for signing - VNF_AGENT_URL - Credential agent endpoint - VNF_REGISTRAR_URL - Registrar endpoint - VNF_CREDENTIAL_AGENT_URL - Credential operations endpoint - And the system should fail to start if required configuration is missing - And the system should validate the configuration on startup - And configuration changes should not require code changes - And sensitive configuration should be properly secured

Monitor Integration Health

As a platform administrator,
I want to monitor the health of the Velocity integration,
So that I can identify and resolve issues before they impact users.

Acceptance Criteria: - Given the Velocity integration is running - When I check the integration health - Then I should see status indicators for: - Velocity Credential Agent connectivity - Velocity Registrar connectivity - API response times - Error rates - Recent successful/failed operations - And the system should provide health check endpoints - And alerts should be sent for integration failures - And historical performance data should be available - And the health status should be visible in the admin dashboard

Support Credential Offer Generation

As a staffing company user,
I want to generate credential offers that candidates can claim,
So that candidates can receive their employment credentials in their digital wallets.

Acceptance Criteria: - Given a credential has been created - When I issue the credential - Then the system should generate a credential offer via Velocity - And the offer should include a QR code for mobile wallet scanning - And the offer should include a deep link for direct wallet access - And the offer should include an email link for web-based claiming - And the offer should have a configurable expiration time - And the offer should be trackable for claim status - And multiple offer formats should be supported (QR, email, SMS)

Technical Notes

Velocity SDK Implementation

Based on the Velocity SDK Implementation Guide, the integration should:

  • Replace the current manual API approach with the Velocity SDK
  • Use the VelocityService as the main integration point
  • Implement proper error handling and retry logic
  • Support both single and batch credential operations
  • Provide comprehensive logging and monitoring

Environment Configuration

Critical environment variables (Tier 1 - Essential): 

VNF_SDK_API_KEY=                    # SDK access key from VCL
VNF_SDK_ENVIRONMENT=sandbox         # sandbox/production
VNF_AGENT_URL=                      # Credential agent endpoint
VNF_SDK_DID=                        # Organization DID
VNF_SDK_PRIVATE_KEY=                # Signing key

Performance Requirements

  • Support 1000-2000 transactions per hour
  • Handle 1000 concurrent users
  • Process CSV batches of 500+ credentials
  • Response times under 2 seconds for credential operations

Dependencies

  • Velocity Credential Agent (provided by VCL)
  • Organization registration with Velocity Network
  • Proper SDK credentials and configuration
  • Background job processing system

Priority

High - Essential for credential issuance functionality, required for first project drop

References