Annual Plan Quote to Purchase Flow

This workflow shows the recommended deferred hosted-payment sequence for an annual policy purchase. Use it with the API Integration Guide and Payment Integration Guide when wiring annual quote, annual staging, hosted payment, and policy binding requests.

Sequence Diagram


sequenceDiagram
    autonumber
    actor Traveler as Traveler
    participant PartnerApp as Partner app
    participant PartnerBackend as Partner backend
    participant TiiGraphQL as Travel Insured GraphQL API
    participant PaymentApp as Travel Insured payment app
    participant HostedForm as Hosted payment form

    Traveler->>PartnerApp: Enter annual coverage and traveler details
    PartnerApp->>PartnerBackend: Submit annual quote request inputs
    PartnerBackend->>TiiGraphQL: annualPlanQuote
    TiiGraphQL-->>PartnerBackend: Available annual products, coverage options, and premiums
    PartnerBackend-->>PartnerApp: Present eligible annual plans and coverage
    Traveler->>PartnerApp: Select annual product and provide purchaser details
    PartnerApp->>PartnerBackend: Submit selected annual product and purchaser details
    PartnerBackend->>TiiGraphQL: stageAnnualPolicyPurchase
    TiiGraphQL-->>PartnerBackend: planGuid and staged annual purchase details
    PartnerBackend->>PaymentApp: Create embedded payment session with planGuid
    PaymentApp-->>PartnerBackend: paymentSessionId, embedToken, expiresAt
    PartnerBackend-->>PartnerApp: Return safe payment session values
    PartnerApp->>HostedForm: Mount hosted payment form with embedToken
    Traveler->>HostedForm: Enter card details
    HostedForm->>PaymentApp: Tokenize and submit card data
    PaymentApp-->>PartnerApp: Payment status event
    PartnerApp->>PartnerBackend: Confirm successful payment status
    PartnerBackend->>TiiGraphQL: policyBindRequest
    TiiGraphQL-->>PartnerBackend: Plan number, policy document links, and bound policy status
    PartnerBackend-->>PartnerApp: Return confirmation details
    PartnerApp-->>Traveler: Show annual policy confirmation
Single Trip Quote to Purchase flow from quote creation through hosted payment and policy binding.

Text Sequence Equivalent

Step	Initiator	Request or event	Result
1	Traveler	Enters annual coverage and traveler details in the partner experience	Partner app has the information needed to request an annual quote
2	Partner backend	Calls `annualPlanQuote` on the Travel Insured GraphQL API	Eligible annual products, coverage options, and quoted premiums are returned
3	Traveler	Selects an annual product and provides purchaser details	Partner app can stage the selected annual policy purchase
4	Partner backend	Calls `stageAnnualPolicyPurchase`	Travel Insured returns the staged annual purchase details, including `planGuid`
5	Partner backend	Creates an embedded payment session with the Travel Insured payment app	Safe client values such as `paymentSessionId`, `embedToken`, and `expiresAt` are returned
6	Partner app	Mounts the hosted payment form using the safe session values	Traveler sees the secure Travel Insured-hosted card-entry form
7	Traveler	Enters card details in the hosted payment form	Card data is tokenized and submitted without touching partner servers
8	Payment app	Sends a safe payment status event to the partner app	Partner app can notify the backend that payment succeeded
9	Partner backend	Calls `policyBindRequest` after successful payment	Travel Insured returns the plan number, policy document links, and bound policy status
10	Partner app	Displays confirmation details	Traveler receives annual policy purchase confirmation

Implementation Notes

Keep partner API credentials on the server. Never send Authorization or x-api-key values to the browser.
Use annualPlanQuote before staging so the traveler can review eligible annual products, coverage options, and premium amounts before purchase.
Use annual product codes returned by annualPlanQuote; do not reuse single-trip product codes.
Keep traveler IDs stable between annualPlanQuote and stageAnnualPolicyPurchase, especially when the quote includes a tripSegment.
Include contactInfo for the primary traveler and product.effectiveDate when staging annual plans.
Use stageAnnualPolicyPurchase to create the planGuid required by the hosted payment session.
Pass only safe payment session values, such as paymentSessionId and embedToken, from your backend to your browser application.
Call policyBindRequest only after a successful payment status is confirmed by your backend.
Treat all identifiers and status events received by the browser as untrusted until your backend verifies the transaction state server-side.