Migrating from Global Payments

A practical guide for travel businesses migrating from Global Payments (formerly Realex Payments / Global Iris) to Felloh. This covers concept mapping, code migration patterns, and a step-by-step migration plan so you can move with confidence.

Global Payments is a traditional acquirer and gateway popular with UK and Irish travel businesses. Many integrations date back to the Realex Payments era and use XML-based APIs, Hosted Payment Pages (HPP), or the RealControl merchant portal. Felloh replaces the gateway and adds travel-specific features — bookings, trust accounts, installment scheduling, automatic reconciliation, and AI agent integration — letting you modernise in one move.

Concept mapping

Understand how Global Payments concepts translate to Felloh before writing any code.

Direct equivalents

Different concepts

Felloh concepts with no Global Payments equivalent

These are features you gain by moving to Felloh.

No Felloh equivalent

The booking model

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

Global Payments flow:
  ORDER_ID → auth request → settle
  (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 Global Payments transaction references or order IDs to your booking system. Felloh handles this relationship natively.

Choosing a payment method

In Global Payments, you submit an auth request (server-to-server XML), redirect to the Hosted Payment Page, or charge a stored card via receipt-in. In Felloh, you choose based on the scenario:

Code migration

Authentication

Global Payments uses a merchant ID, account, and shared secret to generate a SHA-1 hash for each request (or an API key for the newer Unified Payments API). Felloh uses a public/private key pair to generate a bearer token.

import crypto from 'crypto';

// Global Payments — SHA-1 hash per request (Realex XML API)
const merchantId = 'your-merchant-id';
const secret = 'your-shared-secret';
const timestamp = new Date().toISOString().replace(/[-:T.Z]/g, '').slice(0, 14);
const orderId = 'ORDER-001';
const amount = '50000';
const currency = 'GBP';

// SHA-1 hash: timestamp.merchantid.orderid.amount.currency
const toHash = `${timestamp}.${merchantId}.${orderId}.${amount}.${currency}`;
const sha1 = crypto.createHash('sha1').update(toHash).digest('hex');
const hash = crypto.createHash('sha1').update(`${sha1}.${secret}`).digest('hex');

Creating a customer

Global Payments has a payer management system (payer-new, payer-edit) used primarily for recurring payments. Felloh has a dedicated customer resource used across all payment flows.

<?xml version="1.0" encoding="UTF-8"?>
<request type="payer-new" timestamp="20260406120000">
  <merchantid>your-merchant-id</merchantid>
  <orderid>payer-setup-001</orderid>
  <payer type="Business" ref="PAYER-001">
    <firstname>Sarah</firstname>
    <surname>Jones</surname>
    <email>sarah@example.com</email>
    <address>
      <line1>10 Downing Street</line1>
      <city>London</city>
      <postcode>SW1A 2AA</postcode>
      <country code="GB">United Kingdom</country>
    </address>
  </payer>
  <sha1hash>calculated-hash</sha1hash>
</request>

Creating a booking (new concept)

This has no Global Payments 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"?>
<request type="auth" timestamp="20260406120000">
  <merchantid>your-merchant-id</merchantid>
  <account>internet</account>
  <orderid>TRIP-2026-001-DEP</orderid>
  <amount currency="GBP">50000</amount>
  <card>
    <number>4263970000005262</number>
    <expdate>1228</expdate>
    <chname>Sarah Jones</chname>
    <type>VISA</type>
    <cvn>
      <number>123</number>
      <presind>1</presind>
    </cvn>
  </card>
  <autosettle flag="1"/>
  <sha1hash>calculated-hash</sha1hash>
</request>

Processing a refund

<?xml version="1.0" encoding="UTF-8"?>
<request type="rebate" timestamp="20260406120000">
  <merchantid>your-merchant-id</merchantid>
  <account>internet</account>
  <orderid>TRIP-2026-001-DEP</orderid>
  <pasref>original-pasref</pasref>
  <authcode>original-authcode</authcode>
  <amount currency="GBP">20000</amount>
  <refundhash>rebate-password-hash</refundhash>
  <sha1hash>calculated-hash</sha1hash>
</request>

Scheduling a future payment

Global Payments supports stored card payments via receipt-in, but you schedule the timing yourself. Felloh handles scheduling natively.

<!-- Step 1: Store the card (after initial payment) -->
<request type="card-new" timestamp="20260406120000">
  <merchantid>your-merchant-id</merchantid>
  <orderid>card-store-001</orderid>
  <card>
    <ref>card-ref-001</ref>
    <payerref>PAYER-001</payerref>
    <number>4263970000005262</number>
    <expdate>1228</expdate>
    <chname>Sarah Jones</chname>
    <type>VISA</type>
  </card>
  <sha1hash>calculated-hash</sha1hash>
</request>

<!-- Step 2: Charge the stored card (via your cron job) -->
<request type="receipt-in" timestamp="20260716120000">
  <merchantid>your-merchant-id</merchantid>
  <account>internet</account>
  <orderid>TRIP-2026-001-BAL</orderid>
  <amount currency="GBP">100000</amount>
  <payerref>PAYER-001</payerref>
  <paymentmethod>card-ref-001</paymentmethod>
  <autosettle flag="1"/>
  <sha1hash>calculated-hash</sha1hash>
</request>

Currency mapping

Global Payments 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 GP_TO_FELLOH_CURRENCY = {
  GBP: 'GBX',
  USD: 'USX',
  EUR: 'EUX',
};

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

// Amount values stay the same — both use minor units
// Global Payments: <amount currency="GBP">150000</amount>
// Felloh:          { amount: 150000, currency: 'GBX' }

Webhook event mapping

Global Payments posts results to a response URL (configured in RealControl or passed in the HPP request). Felloh uses standard webhooks with HMAC-SHA256 signatures.

Migrating a response handler

import crypto from 'crypto';

app.post('/response/globalpayments', express.text({ type: 'text/xml' }), (req, res) => {
  // Parse XML response
  // Verify SHA-1 hash: timestamp.merchantid.orderid.result.message.pasref.authcode
  const xml = req.body;

  // (simplified — real implementation uses an XML parser)
  const result = extractFromXml(xml, 'result');
  const orderId = extractFromXml(xml, 'orderid');

  if (result === '00') {
    handlePaymentSuccess(orderId);
  } else {
    handlePaymentFailure(orderId, result);
  }

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

What you can remove

Migrating from Global Payments to Felloh lets you remove significant custom code.

Migration plan

A step-by-step approach to moving from Global Payments 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 — Audit and plan

1. Identify your Global Payments integration type — XML API (Realex), Hosted Payment Page, newer Unified Payments API, or a combination
2. List all payment flows — initial auth, stored card charges (receipt-in), HPP redirects
3. Review RealControl configuration — note any fraud rules (RealScore), response URLs, and HPP settings that need to be recreated in Felloh
4. Export payer data — pull customer details from your payer references or booking system
5. Create customers and bookings in Felloh for any active reservations

Phase 3 — Migrate payment flows

1. Replace HPP redirects with Felloh payment links
2. Replace direct XML auth with Felloh ecommerce sessions and the Felloh SDK
3. Replace receipt-in stored card charges (cron jobs) with Felloh scheduled payments
4. Replace rebate requests with Felloh's two-stage refund process
5. Replace response URL handlers with Felloh webhook handlers
6. Remove SHA-1 hash generation — Felloh uses bearer tokens
7. Remove XML building/parsing code — Felloh is JSON throughout
8. Remove manual settle/capture calls — Felloh captures automatically
9. Remove 3DS flow handling — Felloh handles 3DS 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 Global Payments and Felloh in parallel for a transition period — new bookings go through Felloh, existing stored card schedules complete naturally
3. Monitor the Felloh Dashboard for transaction status
4. Decommission Global Payments integration and remove legacy code
5. Cancel RealScore add-on (now covered by Fraud Shield)

Common migration questions

Can I run Global Payments and Felloh in parallel? Yes. Route new bookings to Felloh and let existing Global Payments stored card charges complete. There's no conflict between the two.

Do I need to re-collect card details? Yes, for new payments. Global Payments payer/card references 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 Global Payments' HPP iFrame integration, the Felloh SDK provides equivalent security.

I use receipt-in for recurring stored card charges. How does that translate? Replace each receipt-in call with a Felloh scheduled payment. Each scheduled payment has a specific date and amount — Felloh handles the execution automatically. No cron jobs, no payer references, no SHA-1 hashing.

What about the rebate password? Global Payments requires a separate rebate password (configured in RealControl) for processing refunds. Felloh replaces this with API-based two-stage refunds — you initiate a refund via the API, then authorise it separately. No password management required.

I'm on the newer Unified Payments API. Is migration easier? Slightly — the Unified Payments API is JSON-based, so you skip the XML migration. The core concepts (booking model, payment method selection, tokenisation) are the same regardless of which Global Payments API you're on.

What about 3DS (Strong Customer Authentication)? Felloh handles 3DS automatically on payment links and ecommerce sessions. You can configure 3DS rules in Fraud Shield. This removes the need to implement the 3DS redirect/challenge flow yourself — one of the most complex parts of a Global Payments integration.

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.