Migrating from Adyen

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

Adyen is a powerful payment platform used by large enterprises, but its complexity and general-purpose design mean travel businesses spend significant effort building travel-specific workflows on top of it. Felloh replaces the gateway and adds the travel layer — bookings, trust accounts, installment scheduling, and supplier disbursements — so you can focus on your product instead of payment infrastructure.

Concept mapping

Understand how Adyen concepts translate to Felloh before writing any code.

Direct equivalents

Different concepts

Felloh concepts with no Adyen equivalent

These are features you gain by moving to Felloh.

No Felloh equivalent

These Adyen features don't have a Felloh counterpart.

The booking model

The biggest conceptual shift is that every payment in Felloh is tied to a Booking. In Adyen, you submit a payment with a merchantReference — the gateway has no concept of what the payment is for. In Felloh, you create a booking first, then collect payments against it.

Adyen flow:
  Shopper → /payments (merchantReference) → Authorisation → Capture
  (you maintain the link to your booking system)

Felloh flow:
  Customer → Booking → Payment Link / Ecommerce / Scheduled Payment → Transaction
  (booking is a first-class object — payments are linked automatically)

This means you can remove any custom code that links Adyen payment references to your booking system. Felloh handles this relationship natively.

Choosing a payment method

In Adyen, you call the /payments or /sessions endpoint for most scenarios. In Felloh, you choose based on the scenario:

Code migration

Authentication

Adyen uses an API key passed as a header. Felloh uses a public/private key pair to generate a bearer token.

import { Client, CheckoutAPI } from '@adyen/api-library';

const client = new Client({
  apiKey: 'AQEjhmfuXNWTK...',
  environment: 'LIVE',
  liveEndpointUrlPrefix: 'your-prefix',
});

const checkout = new CheckoutAPI(client);

Creating a customer

Adyen doesn't have a dedicated customer creation API — shopper details are passed with each payment. Felloh has a dedicated customer resource.

// Adyen — shopper details are embedded in the payment request
const paymentRequest = {
  merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
  amount: { value: 50000, currency: 'GBP' },
  reference: 'TRIP-2026-001',
  shopperEmail: 'sarah@example.com',
  shopperName: {
    firstName: 'Sarah',
    lastName: 'Jones',
  },
  billingAddress: {
    street: '10 Downing Street',
    city: 'London',
    postalCode: 'SW1A 2AA',
    country: 'GB',
  },
  // ... payment method details ...
};

Creating a booking (new concept)

This has no Adyen equivalent — it's the step that replaces your custom booking-to-payment mapping.

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 payment session for Drop-in / Components
const session = await checkout.PaymentsApi.sessions({
  merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
  amount: { value: 50000, currency: 'GBP' },
  reference: 'TRIP-2026-001-DEP',
  returnUrl: 'https://example.com/checkout/result',
  shopperEmail: 'sarah@example.com',
  shopperReference: 'SHOPPER-001',
  metadata: {
    bookingRef: 'TRIP-2026-001',  // Stored as metadata
  },
});

// Use session.id and session.sessionData with Adyen Drop-in on frontend

Processing a refund

// Adyen refunds are asynchronous — you submit a modification
// and receive the result via webhook
const refund = await checkout.ModificationsApi.refundCapturedPayment(
  pspReference,
  {
    merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
    amount: { value: 20000, currency: 'GBP' },
    reference: 'REFUND-001',
  }
);
// Result comes asynchronously via REFUND notification

Scheduling a future payment

Adyen supports tokenised recurring payments, but you schedule the timing yourself. Felloh handles scheduling natively.

// Save the card on first payment
const initialPayment = await checkout.PaymentsApi.payments({
  merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
  amount: { value: 50000, currency: 'GBP' },
  reference: 'TRIP-2026-001-DEP',
  shopperReference: 'SHOPPER-001',
  shopperInteraction: 'Ecommerce',
  recurringProcessingModel: 'CardOnFile',
  storePaymentMethod: true,
  // ... payment method details ...
});

// Later, charge the saved card (you schedule this via your own cron)
const recurringPayment = await checkout.PaymentsApi.payments({
  merchantAccount: 'YOUR_MERCHANT_ACCOUNT',
  amount: { value: 100000, currency: 'GBP' },
  reference: 'TRIP-2026-001-BAL',
  shopperReference: 'SHOPPER-001',
  shopperInteraction: 'ContAuth',
  recurringProcessingModel: 'CardOnFile',
  paymentMethod: {
    storedPaymentMethodId: 'stored-payment-method-id',
  },
});

Currency mapping

Adyen uses standard ISO 4217 currency codes with amounts in minor units. Felloh uses minor-unit currency codes. The numeric values are the same — only the code changes.

const ADYEN_TO_FELLOH_CURRENCY = {
  GBP: 'GBX',
  USD: 'USX',
  EUR: 'EUX',
};

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

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

Webhook event mapping

Adyen uses webhook notifications with HMAC-SHA256 signatures. Felloh uses the same signing approach but with different event types and payload structures.

Migrating a notification handler

import { hmacValidator } from '@adyen/api-library';

app.post('/webhooks/adyen', express.json(), (req, res) => {
  const validator = new hmacValidator();
  const notifications = req.body.notificationItems;

  for (const item of notifications) {
    const notification = item.NotificationRequestItem;

    // Validate HMAC signature
    if (!validator.validateHMAC(notification, hmacKey)) {
      continue;
    }

    switch (notification.eventCode) {
      case 'AUTHORISATION':
        if (notification.success === 'true') {
          handlePaymentSuccess(notification);
        } else {
          handlePaymentFailure(notification);
        }
        break;
      case 'REFUND':
        handleRefund(notification);
        break;
      case 'CHARGEBACK':
        handleChargeback(notification);
        break;
    }
  }

  res.send('[accepted]');
});

What you can remove

Migrating from Adyen to Felloh lets you remove significant custom code.

Migration plan

A step-by-step approach to moving from Adyen to Felloh.

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. Audit your current Adyen integration — identify all payment flows (sessions, Drop-in, direct API, recurring, Pay by Link)
2. Create customers in Felloh — Adyen doesn't have a customer database, so pull customer data from your booking system
3. Create bookings for any active reservations
4. Map your existing booking references to Felloh bookings using the booking_reference field

Phase 3 — Migrate payment flows

1. Replace Adyen sessions / Drop-in with Felloh payment links or ecommerce sessions
2. Replace Pay by Link with Felloh payment links
3. Replace recurring / ContAuth payments with Felloh scheduled payments
4. Replace refund modifications with Felloh's two-stage refund process
5. Replace Adyen notification handlers with Felloh webhook handlers
6. Remove capture logic — Felloh handles capture automatically
7. Remove shopper reference management — Felloh tokenises cards automatically

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 payment pages work correctly

Phase 5 — Go live

1. Switch to production API keys
2. Run Adyen and Felloh in parallel for a transition period — new bookings go through Felloh, existing Adyen recurring payments settle naturally
3. Monitor the Felloh Dashboard for transaction status
4. Decommission Adyen integration and remove legacy code
5. Cancel Adyen RevenueProtect add-on (now covered by Fraud Shield)

Common migration questions

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

Do I need to re-collect card details? Yes, for new payments. Adyen stored payment methods 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 — card details are collected via Felloh's hosted payment pages or SDK, never touching your servers. If you were using Adyen's Drop-in or Components, the Felloh SDK provides equivalent security.

I use Adyen's manual capture flow. How does that translate? Felloh handles capture automatically. There's no separate capture step — when a customer completes a payment, it's captured immediately. This simplifies your code and removes the risk of forgetting to capture authorised payments.

What about 3DS (Strong Customer Authentication)? Felloh handles 3DS automatically on payment links and ecommerce sessions. You can configure 3DS rules in Fraud Shield — for example, setting velocity thresholds for when 3DS challenges are triggered.

I use Adyen for Platforms. What's the Felloh equivalent? Felloh's equivalent is Disbursements with Beneficiaries. The model is designed for paying travel suppliers from trust accounts rather than marketplace-style splits. Speak to your Felloh account manager for guidance on migrating platform payouts.

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.