Migrating from Stripe

A practical guide for travel businesses migrating from Stripe to Felloh. This covers concept mapping, code migration patterns, and a step-by-step migration plan so you can move with confidence.

Felloh is purpose-built for travel payments. While Stripe is a general-purpose payment platform, Felloh's data model centres around bookings — the natural unit of work for travel businesses. This means some Stripe concepts map directly, some map differently, and some don't apply at all.

Concept mapping

This is the most important section. Understand how Stripe concepts translate to Felloh before writing any code.

Direct equivalents

These concepts map cleanly between the two platforms.

Different concepts

These Stripe concepts exist in Felloh but work differently.

No Felloh equivalent

These Stripe features don't have a Felloh counterpart because they're outside the travel payment domain.

The booking model

The most important conceptual shift is that every payment in Felloh is tied to a Booking. In Stripe, you can create a PaymentIntent with no context — just an amount and a customer. In Felloh, you always need a booking first.

Stripe flow:
  Customer → PaymentIntent → Charge
  (payment exists independently)

Felloh flow:
  Customer → Booking → Payment Link / Ecommerce / Scheduled Payment → Transaction
  (payment is always linked to a booking)

This means your migration needs to ensure that every payment has a corresponding booking. For most travel businesses, this is already how you think about payments — Felloh just makes it explicit.

Because every payment is tied to a booking, Felloh provides automatic reconciliation out of the box. Every payment — cards, open banking, and bank transfers — is automatically matched to its booking using 3-point verification, from initiation through to settlement in your bank account. This eliminates the manual spreadsheet work your finance team does today to match Stripe's bulk settlement payouts to individual bookings.

Felloh also provides automatic surcharging — when a customer enters their card details, Felloh detects whether it's a consumer, corporate, or international card and applies the correct compliant surcharge in real time. The customer sees the surcharge before confirming payment and can switch payment method if they prefer. This protects your margins on expensive card types without manual fee calculations or compliance guesswork.

Choosing a payment method

In Stripe, you always create a PaymentIntent. In Felloh, you choose based on the scenario:

Code migration

Authentication

Stripe uses a single secret key. Felloh uses a public/private key pair to generate a bearer token.

import Stripe from 'stripe';
const stripe = new Stripe('sk_live_...');

Creating a customer

const customer = await stripe.customers.create({
  name: 'Sarah Jones',
  email: 'sarah@example.com',
  address: {
    line1: '10 Downing Street',
    city: 'London',
    postal_code: 'SW1A 2AA',
    country: 'GB',
  },
});

Creating a booking (new concept)

This has no Stripe equivalent — it's the step you add to your flow.

const response = await axios({
  method: 'post',
  url: 'https://api.felloh.com/agent/bookings',
  headers: {
    'Content-Type': 'application/json',
    Authorization: `Bearer ${token}`,
  },
  data: {
    organisation: 'your-organisation-id',
    booking_reference: 'TRIP-2026-001',
    gross: 150000,            // £1,500.00 in pence
    currency: 'GBX',
    customer_email: 'sarah@example.com',
    customer_name: 'Sarah Jones',
    departure_date: '2026-08-15',
    return_date: '2026-08-22',
  },
});

Collecting a payment

// Create a PaymentIntent
const paymentIntent = await stripe.paymentIntents.create({
  amount: 50000,              // £500.00 in pence
  currency: 'gbp',
  customer: customer.id,
  metadata: {
    booking_ref: 'TRIP-2026-001',  // Stored as metadata
  },
});

// Use paymentIntent.client_secret with Stripe Elements on the frontend

Processing a refund

const refund = await stripe.refunds.create({
  payment_intent: 'pi_...',
  amount: 20000,              // £200.00 partial refund
});
// Refund is processed immediately

Scheduling a future payment

// Save the card via SetupIntent
const setupIntent = await stripe.setupIntents.create({
  customer: customer.id,
  payment_method_types: ['card'],
});

// Later, charge off-session
const paymentIntent = await stripe.paymentIntents.create({
  amount: 100000,
  currency: 'gbp',
  customer: customer.id,
  payment_method: 'pm_...',
  off_session: true,
  confirm: true,
});

Currency mapping

Stripe uses standard ISO 4217 currency codes in lowercase. Felloh uses minor-unit currency codes.

Both platforms use minor units for amounts (pence/cents), so the numeric values are the same — only the currency code changes.

const STRIPE_TO_FELLOH_CURRENCY = {
  gbp: 'GBX',
  usd: 'USX',
  eur: 'EUX',
};

function convertCurrency(stripeCurrency) {
  const fellohCurrency = STRIPE_TO_FELLOH_CURRENCY[stripeCurrency.toLowerCase()];
  if (!fellohCurrency) {
    throw new Error(`Unsupported currency: ${stripeCurrency}`);
  }
  return fellohCurrency;
}

// Amount values stay the same — both use minor units
// Stripe: { amount: 150000, currency: 'gbp' }
// Felloh: { amount: 150000, currency: 'GBX' }

Webhook event mapping

If you have existing Stripe webhook handlers, map them to Felloh events.

Migrating a webhook handler

app.post('/webhooks/stripe', express.raw({ type: 'application/json' }), (req, res) => {
  const sig = req.headers['stripe-signature'];
  const event = stripe.webhooks.constructEvent(req.body, sig, webhookSecret);

  switch (event.type) {
    case 'payment_intent.succeeded':
      handlePaymentSuccess(event.data.object);
      break;
    case 'payment_intent.payment_failed':
      handlePaymentFailure(event.data.object);
      break;
    case 'charge.refunded':
      handleRefund(event.data.object);
      break;
  }

  res.json({ received: true });
});

Migration plan

A step-by-step approach to moving from Stripe to Felloh without disrupting live operations.

Phase 1 — Set up and validate

1. Create a Felloh account and generate sandbox API keys from the Sandbox Registration Form
2. Set up authentication — implement token generation and caching
3. Create a test booking and payment link to verify your integration works
4. Connect the MCP server (optional) — useful for exploring the API interactively during migration

Phase 2 — Migrate customer and booking data

1. Export customers from Stripe — use the Stripe API or Dashboard export
2. Create customers in Felloh — map Stripe customer fields to Felloh fields
3. Create bookings for any active reservations — this is the new step that doesn't exist in Stripe
4. Map your existing booking references to Felloh bookings using the booking_reference field

Phase 3 — Migrate payment flows

1. Replace PaymentIntent creation with the appropriate Felloh payment method:
   • Checkout/PaymentLinks → create-payment-link
   • Elements/embedded → create-ecommerce
   • Off-session/saved cards → create-scheduled-payment
2. Replace refund logic with Felloh's two-stage process
3. Update webhook handlers to use Felloh event types
4. Update your frontend if using Stripe Elements — replace with the Felloh SDK

Phase 4 — Test in sandbox

1. Run through every payment flow in the Felloh sandbox
2. Test edge cases: declined payments, partial refunds, expired tokens
3. Verify webhook delivery and handling
4. Confirm customer-facing emails and receipts are correct

Phase 5 — Go live

1. Switch to production API keys
2. Run Stripe and Felloh in parallel for a transition period if needed — new bookings go through Felloh, existing Stripe subscriptions complete naturally
3. Monitor the Felloh Dashboard for transaction status
4. Decommission Stripe integration once all active payments have settled

Common migration questions

Can I run Stripe and Felloh in parallel? Yes. Route new bookings to Felloh and let existing Stripe payment schedules complete. There's no conflict between the two.

Do I need to re-collect card details? Yes, for new payments. Stripe card tokens are not transferable to Felloh. Customers will enter their card details on their first Felloh payment, and the card is automatically tokenised for future use.

What about PCI compliance? Felloh handles PCI compliance the same way Stripe does — card details are collected via Felloh's hosted payment pages or SDK, never touching your servers.

Can I use the Felloh MCP server during migration? Absolutely. Connect the MCP server to your AI editor and use it to explore the API, create test bookings, and debug your integration interactively.

What if I use Stripe Connect for marketplace payouts? Felloh's equivalent is Disbursements with Beneficiaries. The model is different — designed for paying travel suppliers rather than marketplace sellers — so this part of the migration needs the most planning. Speak to your Felloh account manager for guidance.