🧩 Integrating already existing wallet

🧩 Overview

In this model, you (the partner) remain the system of record for all balances and transactions. Funtrips integrates your loyalty system to synchronize earned or redeemed tokens when customers book or complete experiences through our platform.

We never store or process the user’s balance ourselves — we act as a gateway that reports changes and reads balances from your wallet.

🧭 Integration goals

• Keep the partner’s wallet authoritative for balance and history.
• Allow Funtrips to award tokens when users complete eligible bookings.
• Optionally, let Funtrips redeem tokens as partial payment or loyalty discounts.
• Maintain zero PII exposure — only stable user references are exchanged.

🔖 Required capabilities on your side

To integrate, your loyalty system must provide the following endpoints:

📘

Important: Each user in your system must have a stable external_user_id that can be used across all API calls.

📘

The example endpoint are for illustration purposes only, real endpoints can differ but should be functionally similar. The documentation of these endpoints can be shared with the queueup integration team.

🔐 Authentication model

Funtrips prefers authentication with your API using client credentials (OAuth2). You provide us with a backend bearer token with enough permissions to execute the above capabilities.

Other forms of authentication are possible in collaboration with the queueup integration team

🔄 Integration flow

sequenceDiagram
  autonumber
  participant User
  participant FuntripsApp as Funtrips App
  participant FuntripsBE as Funtrips Backend
  participant Wallet as Partner Wallet API

  %% --- Earn flow ---
  User->>FuntripsApp: Completes booking
  FuntripsApp->>FuntripsBE: Booking confirmed (external_user_id)
  FuntripsBE->>Wallet: POST /wallet/transactions (type=credit, idempotency-key)
  Wallet-->>FuntripsBE: 202 Accepted (Retry-After)
  FuntripsBE->>Wallet: GET /wallet/users/{external_user_id}/balance
  Wallet-->>FuntripsBE: 200 OK (updated balance)
  Note over FuntripsBE,Wallet: Tokens credited for booking

  %% --- Redeem flow ---
  User->>FuntripsApp: Applies loyalty tokens at checkout
  FuntripsApp->>FuntripsBE: Redeem request (amount, external_user_id)
  FuntripsBE->>Wallet: POST /wallet/transactions (type=debit, idempotency-key)
  Wallet-->>FuntripsBE: 200 OK (balance updated)
  FuntripsBE-->>FuntripsApp: Redemption applied

  %% --- Refund / reversal flow ---
  FuntripsBE->>Wallet: POST /wallet/transactions (type=debit, reason=refund)
  Wallet-->>FuntripsBE: 200 OK (reversal accepted)
  FuntripsBE->>Wallet: POST /wallet/transactions (type=credit, reason=redemption_reversal)
  Wallet-->>FuntripsBE: 200 OK (tokens returned)
  Note over FuntripsBE,Wallet: Refund or cancellation handled

Booking or event triggers a loyalty update

When a user completes a transaction in Funtrips (for example, confirms a booking), our backend will:

1. Identify the user by your external_user_id
2. POST a credit transaction to your /wallet/transactions endpoint.
3. Include idempotency headers to ensure safe retries.
4. Optionally, poll /wallet/users/id/balance to confirm the new balance.

Refunds or cancellations

When a booking is refunded or canceled, Funtrips sends a debit transaction to your API with the same reference_id. You can reject the call if your rules don’t allow negative balances.

🧠 User identification

• Funtrips never receives or transmits PII (e.g. email, names).
• The only identifier we need is your external_user_id — consistent, stable, and unique within your system.
• During booking, we receive this ID from your backend when a user session is started.

🔁 Reconciliation

Funtrips expects to periodically verify balances and transaction integrity by:

• Pulling /wallet/users/id/transactions for auditing.
• Using timestamps or paging tokens for incremental sync.
• Handling 202/Retry-After gracefully during delays.