Hybrid Integration Guide

This guide extends the Authorization Flow and Loyalty & Integration Guide.
It describes a hybrid setup where integrators index merchants and products via API, and use the webframe for checkout and purchase flows.

🔄 Overview

Some partners prefer to combine API-driven discovery with an embedded checkout experience.
In this hybrid approach:

• The partner crawls or caches merchant and product data via the API.
• The checkout and payment flow still happens inside the Funtrips Webframe, preserving the secure session and consistent UI.

This gives you:

• Full control over how products are displayed in your own app or catalog.
• A seamless and secure checkout flow handled by Funtrips.

sequenceDiagram
    autonumber
    participant UserApp as User App (Mobile/Web)
    participant PartnerBE as Partner Backend
    participant FTAuth as Funtrips Auth
    participant FTAPI as Funtrips API
    participant FTWeb as Funtrips Webframe

    %% 1) Server-to-server auth
    PartnerBE->>FTAuth: POST /oauth/token (client_credentials)
    FTAuth-->>PartnerBE: 200 { backend_bearer }

    %% 2) Backend indexing (optional but common)
    PartnerBE->>FTAPI: GET /v1/merchants (Auth: backend_bearer)
    FTAPI-->>PartnerBE: 200 merchants
    PartnerBE->>FTAPI: GET /v1/merchants/{merchant}/products (Auth: backend_bearer)
    FTAPI-->>PartnerBE: 200 products

    %% 3) Start a session for webframe
    PartnerBE->>FTAPI: POST /v1/session (Auth: backend_bearer)
    FTAPI-->>PartnerBE: 200 { session_code, frame_url?session_code=... }

    %% 4) Open webframe (deep link to product/merchant)
    UserApp->>FTWeb: Open frame_url (includes session_code)

    %% 5) Webframe redeems code (no PKCE)
    FTWeb->>FTAPI: POST /v1/oauth/token 
    FTAPI-->>FTWeb: 200 { public_bearer }

    %% 6) Webframe loads content & checkout using public bearer
    FTWeb->>FTAPI: GET /v1/... (Auth: public_bearer)
    FTAPI-->>FTWeb: 200 content/availability
    FTWeb->>FTAPI: POST /v1/merchants/{merchant}/checkouts (Auth: public_bearer)
    FTAPI-->>FTWeb: 201 { checkout }

    %% 7) (Optional) Partner polls checkout status
    PartnerBE->>FTAPI: GET /v1/checkouts/{checkout_id} (Auth: backend or public, as applicable)
    FTAPI-->>PartnerBE: 200 { status }

🗂️ 1. Crawl or Cache Merchant & Product Data

Using your backend bearer (Client Credentials), you can query:

• List merchants: GET /v1/merchants
• List products for a merchant: GET /v1/merchants/merchant/products
• Get product details: GET /v1/merchants/merchant/products/product

You can use these endpoints to:

• Build your own local index or search results.
• Keep your catalog in sync with Funtrips updates.
• Display localized content (the API supports the locale parameter).

🪄 2. Open the Webframe to a Product Page

Once you have a merchant alias, you can deep-link users directly into the Funtrips Webframe:

https://app.funtrips.io/frame/merchants/{merchant.alias}

🧑‍💻 3. Session & Authentication Flow (Recap)

The hybrid model still uses the session code flow from the Authorization Guide:

1. Authenticate server-to-server with client credentials.
2. Create a session via POST /v1/session, including the external user ID.
3. Use the returned code to open the webframe URL:

https://app.funtrips.io/frame/merchants/{merchant.alias}?session_code={code}

4. Funtrips exchanges this code internally for the user’s public bearer.

📅 4. Data Freshness & Sync Strategy

To ensure your merchant and product data remains up to date:

• Use last_updated from the meta block in list responses.
• Periodically re-sync based on that timestamp.
• Cache aggressively for static data (merchant info, descriptions, images).
• Fetch dynamic data (calendar prices, availability) on demand when the user interacts.

🎯 5. Why Hybrid?

Hybrid integration is ideal when you want:

• Custom in-app presentation of merchants/products.
• Secure, plug-and-play checkout with zero PCI scope.
• Loyalty and session management handled automatically.

🧠 6. Summary

You stay in control of content and navigation, while Funtrips ensures security and transaction reliability.