Hydra Payment Integration
Safeco uses Liberty Mutual's Hydra platform for secure payment collection. Payment details never touch Fastlane servers — they're captured in a Hydra-hosted iframe and tokenized into an instrumentId.
Flow
Hydra URL Generation
Endpoint: POST ${SAFECO_HYDRA_BASE_URL}/instruments/hosted-page/initiate
Request body:
| Field | Source |
|---|---|
clientId | SAFECO_HYDRA_CLIENT_ID |
clientProfileId | SAFECO_HYDRA_CLIENT_PROFILE_ID |
callbackUrl | SAFECO_HYDRA_CALLBACK_URL |
cssUrl | SAFECO_HYDRA_CSS_URL |
storeInstrumentForReuse | false |
instrumentType | credit_card or eft |
Auth: Bearer token from HydraOAuthTokenManagerService (OAuth client_credentials grant at Liberty Mutual's OAuth endpoint).
Response: Returns instrumentHostedPageUrl (the iframe URL) and instrumentId (the token for the payment instrument).
Instrument Types
| Type | Description |
|---|---|
credit_card | Credit/debit card payment |
eft | Electronic Funds Transfer (ACH bank account) |
The portal's SafecoHydraPaymentBlock renders the iframe. The customer enters payment details directly in Hydra's hosted page.
PostMessage Validation
When the customer completes payment, Hydra sends a postMessage back to the portal. The validateHydraPostMessage() utility checks:
| Field | Expected |
|---|---|
status | 'success' (vs 'cancelled' or 'error') |
instrumentId | Must be present |
paymentMethod | 'CreditCard' or 'EFT' |
Server-Side Validation
Endpoint: GET ${SAFECO_HYDRA_BASE_URL}/instruments/${instrumentId}
The gateway calls Hydra's API to verify the instrument is valid before proceeding to bind. Success requires status === 'Approved'.
Session Storage
Payment data is stored in Redis across three keys:
| Redis Key | Data | Set By |
|---|---|---|
session:{id}:hydra-session-token | Hydra session token | hydra-url handler |
session:{id}:hydra-instrument-id | Instrument ID | hydra-url handler |
session:{id}:hydra-payment | Full instrument details (instrumentId, status, maskedInstrument, cardBrand) | hydra-validate handler |
Environment Config
| Variable | Purpose |
|---|---|
SAFECO_HYDRA_BASE_URL | Hydra API base URL |
SAFECO_HYDRA_CLIENT_ID | OAuth client ID |
SAFECO_HYDRA_CLIENT_PROFILE_ID | Client profile for hosted page |
SAFECO_HYDRA_CALLBACK_URL | Callback URL for iframe postMessage |
SAFECO_HYDRA_CSS_URL | Custom CSS for Hydra iframe styling |
CSP Configuration
Content Security Policy allows Hydra iframe sources:
*.hydra-crux.libertymutual.comapi-tst.us.libertymutual.comapi.us.libertymutual.com
Key Files
| File | Purpose |
|---|---|
libs/apis/carriers/safeco/src/v3_1/application/services/safeco-hydra.service.ts | Hydra URL generation and instrument validation |
libs/apis/carriers/safeco/src/v3_1/infrastructure/auth/hydra-oauth-token-manager.service.ts | Hydra OAuth token management |
libs/apis/carriers/safeco/src/v3_1/application/dtos/safeco-hydra-request.dto.ts | Request DTO with HydraInstrumentType |
libs/apis/carriers/safeco/src/v3_1/application/dtos/safeco-hydra-response.dto.ts | Response DTO |
apps/apis/fastlane-api-gateway/src/app/handlers/safeco-hydra-url.handler.ts | Gateway handler for URL generation |
apps/apis/fastlane-api-gateway/src/app/handlers/safeco-hydra-validate.handler.ts | Gateway handler for payment validation |