Skip to main content

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:

FieldSource
clientIdSAFECO_HYDRA_CLIENT_ID
clientProfileIdSAFECO_HYDRA_CLIENT_PROFILE_ID
callbackUrlSAFECO_HYDRA_CALLBACK_URL
cssUrlSAFECO_HYDRA_CSS_URL
storeInstrumentForReusefalse
instrumentTypecredit_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​

TypeDescription
credit_cardCredit/debit card payment
eftElectronic 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:

FieldExpected
status'success' (vs 'cancelled' or 'error')
instrumentIdMust 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 KeyDataSet By
session:{id}:hydra-session-tokenHydra session tokenhydra-url handler
session:{id}:hydra-instrument-idInstrument IDhydra-url handler
session:{id}:hydra-paymentFull instrument details (instrumentId, status, maskedInstrument, cardBrand)hydra-validate handler

Environment Config​

VariablePurpose
SAFECO_HYDRA_BASE_URLHydra API base URL
SAFECO_HYDRA_CLIENT_IDOAuth client ID
SAFECO_HYDRA_CLIENT_PROFILE_IDClient profile for hosted page
SAFECO_HYDRA_CALLBACK_URLCallback URL for iframe postMessage
SAFECO_HYDRA_CSS_URLCustom CSS for Hydra iframe styling

CSP Configuration​

Content Security Policy allows Hydra iframe sources:

  • *.hydra-crux.libertymutual.com
  • api-tst.us.libertymutual.com
  • api.us.libertymutual.com

Key Files​

FilePurpose
libs/apis/carriers/safeco/src/v3_1/application/services/safeco-hydra.service.tsHydra URL generation and instrument validation
libs/apis/carriers/safeco/src/v3_1/infrastructure/auth/hydra-oauth-token-manager.service.tsHydra OAuth token management
libs/apis/carriers/safeco/src/v3_1/application/dtos/safeco-hydra-request.dto.tsRequest DTO with HydraInstrumentType
libs/apis/carriers/safeco/src/v3_1/application/dtos/safeco-hydra-response.dto.tsResponse DTO
apps/apis/fastlane-api-gateway/src/app/handlers/safeco-hydra-url.handler.tsGateway handler for URL generation
apps/apis/fastlane-api-gateway/src/app/handlers/safeco-hydra-validate.handler.tsGateway handler for payment validation