Migrating from Worldpay

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

Worldpay is a traditional payment gateway — it processes card transactions but leaves booking management, installment scheduling, trust accounts, and supplier payments to you. Felloh replaces the gateway and adds the travel-specific layer on top, so you can remove significant amounts of custom code.

Concept mapping

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

Direct equivalents

Different concepts

Felloh concepts with no Worldpay equivalent

These are features you gain by moving to Felloh.

The booking model

The biggest conceptual shift is that every payment in Felloh is tied to a Booking. In Worldpay, you send a payment request with an order code and amount — the gateway has no concept of what the payment is for. In Felloh, you create a booking first, then collect payments against it.

Worldpay flow:
  Order Code → Payment Request → Settlement
  (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 Worldpay transactions to your booking system. Felloh handles this relationship natively.

Choosing a payment method

In Worldpay, you submit a payment request (often via XML) or redirect to the Hosted Payment Page. In Felloh, you choose based on the scenario:

Code migration

Authentication

Worldpay uses HTTP Basic Auth with a merchant code, XML username, and password (or an API key for newer integrations). Felloh uses a public/private key pair to generate a bearer token.

import axios from 'axios';

// Worldpay — HTTP Basic Auth
const worldpayClient = axios.create({
  baseURL: 'https://secure.worldpay.com/jsp/merchant/xml/paymentService.jsp',
  auth: {
    username: 'MERCHANT_CODE',
    password: 'XML_PASSWORD',
  },
  headers: { 'Content-Type': 'application/xml' },
});

Creating a customer

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

// Worldpay — customer details are embedded in the order XML
const orderXml = `
<paymentService version="1.4" merchantCode="MERCHANT_CODE">
  <submit>
    <order orderCode="ORDER-001">
      <shopper>
        <shopperEmailAddress>sarah@example.com</shopperEmailAddress>
      </shopper>
      <!-- ... payment details ... -->
    </order>
  </submit>
</paymentService>
`;

Creating a booking (new concept)

This has no Worldpay 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

<?xml version="1.0" encoding="UTF-8"?>
<paymentService version="1.4" merchantCode="MERCHANT_CODE">
  <submit>
    <order orderCode="TRIP-2026-001-DEP">
      <description>Deposit for August trip</description>
      <amount currencyCode="GBP" exponent="2" value="50000"/>
      <orderContent>Deposit payment</orderContent>
      <paymentMethodMask>
        <include code="ALL"/>
      </paymentMethodMask>
      <shopper>
        <shopperEmailAddress>sarah@example.com</shopperEmailAddress>
      </shopper>
    </order>
  </submit>
</paymentService>

Processing a refund

<?xml version="1.0" encoding="UTF-8"?>
<paymentService version="1.4" merchantCode="MERCHANT_CODE">
  <modify>
    <orderModification orderCode="TRIP-2026-001-DEP">
      <refund>
        <amount currencyCode="GBP" exponent="2" value="20000"/>
      </refund>
    </orderModification>
  </modify>
</paymentService>

Scheduling a future payment

Worldpay doesn't have native payment scheduling. Most travel businesses build cron jobs that store tokenised cards and trigger payments on specific dates. Felloh replaces this entire pattern.

// You typically build this yourself:
// 1. Store the Worldpay token after initial payment
// 2. Create a scheduled_payments table in your database
// 3. Run a cron job daily to find due payments
// 4. Submit XML payment requests for each due payment
// 5. Handle failures, retries, and notifications

// Your cron job would submit something like:
const paymentXml = `
<paymentService version="1.4" merchantCode="MERCHANT_CODE">
  <submit>
    <order orderCode="TRIP-2026-001-BAL">
      <amount currencyCode="GBP" exponent="2" value="100000"/>
      <paymentDetails>
        <TOKEN-SSL tokenScope="shopper">
          <paymentTokenID>token-id-from-initial-payment</paymentTokenID>
        </TOKEN-SSL>
      </paymentDetails>
    </order>
  </submit>
</paymentService>
`;

Currency mapping

Worldpay uses standard ISO 4217 currency codes with an exponent. Felloh uses minor-unit currency codes where the amount is always in the smallest unit.

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

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

// Amount values stay the same — both use minor units
// Worldpay: <amount currencyCode="GBP" exponent="2" value="150000"/>
// Felloh:   { amount: 150000, currency: 'GBX' }

Webhook event mapping

Worldpay uses notification URLs (or the older Merchant Admin-configured callbacks). Felloh uses standard webhooks with HMAC-SHA256 signatures.

Migrating a notification handler

// Worldpay sends XML notifications
app.post('/notifications/worldpay', express.text({ type: 'text/xml' }), (req, res) => {
  // Parse XML notification
  const xml = req.body;

  // Extract order code and status
  // (simplified — real implementation uses an XML parser)
  if (xml.includes('<journal journalType="CAPTURED">')) {
    handlePaymentSuccess(orderCode);
  } else if (xml.includes('<journal journalType="REFUSED">')) {
    handlePaymentFailure(orderCode);
  } else if (xml.includes('<journal journalType="REFUNDED">')) {
    handleRefund(orderCode);
  }

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

What you can remove

One of the biggest benefits of migrating from Worldpay to Felloh is the amount of custom code you can delete. Here's what Felloh replaces:

Migration plan

A step-by-step approach to moving from Worldpay 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 Worldpay integration — identify all payment flows (HPP, direct API, tokenised, batch)
2. Create customers in Felloh — Worldpay 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 Hosted Payment Page redirects with Felloh payment links
2. Replace direct API / CSE integration with Felloh ecommerce sessions and the Felloh SDK
3. Replace token-based scheduled payments (cron jobs) with Felloh scheduled payments
4. Replace XML refund modifications with Felloh's two-stage refund process
5. Replace Worldpay notification handlers with Felloh webhook handlers
6. Remove XML building/parsing code — Felloh is JSON throughout

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 Worldpay and Felloh in parallel for a transition period — new bookings go through Felloh, existing Worldpay payments settle naturally
3. Monitor the Felloh Dashboard for transaction status
4. Decommission Worldpay integration and remove legacy code
5. Cancel Worldpay risk management add-ons (now covered by Fraud Shield)

Common migration questions

Can I run Worldpay and Felloh in parallel? Yes. Route new bookings to Felloh and let existing Worldpay transactions settle naturally. There's no conflict between the two.

Do I need to re-collect card details? Yes, for new payments. Worldpay 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 — card details are collected via Felloh's hosted payment pages or SDK, never touching your servers. If you were using Worldpay's direct API with CSE (Client-Side Encryption), the Felloh SDK provides equivalent security.

I use Worldpay's batch file processing. How does that translate? Replace batch files with individual Felloh scheduled payments. Each scheduled payment has a specific execution date and amount — Felloh handles the execution automatically. No batch files, no cron jobs.

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 is triggered.

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.