Agentic Billing Workflows

Automate travel payment workflows — from booking creation to refund processing — using AI agents and the Felloh API.

This guide covers how to provision customers and bookings, collect payments, manage installment schedules, and handle refunds — all from an AI agent using the Felloh MCP server or API directly.

How it works

Felloh is purpose-built for travel payments. Unlike general payment platforms, Felloh's data model centres around bookings — a container representing a customer's trip that links together transactions, payment links, scheduled payments, and supplier components.

AI agents can use the Felloh MCP server or API to orchestrate end-to-end payment workflows:

  1. Create a customer and booking for a travel reservation
  2. Collect payment via payment links, ecommerce sessions, or scheduled payments
  3. Manage the booking lifecycle — update amounts, process refunds, handle chargebacks
  4. Disburse funds to suppliers via managed trust accounts

Prerequisites

Before you begin, make sure you have:

Use sandbox credentials (https://sandbox.felloh.com) for testing. All examples in this guide work against the sandbox environment.

Create a customer and booking

The first step in any travel payment workflow is creating a customer record and a booking to represent their trip.

Create a customer

POST
https://api.felloh.com/agent/customers
import axios from 'axios';

const createCustomer = async (token, organisationId) => {
  const response = await axios({
    method: 'post',
    url: 'https://api.felloh.com/agent/customers',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    data: {
      organisation: organisationId,
      name: 'Jane Smith',
      email: 'jane.smith@example.com',
    },
  });

  return response.data;
};

Once you have a customer, create a booking with the trip details:

Create a booking

POST
https://api.felloh.com/agent/bookings
import axios from 'axios';

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

  return response.data;
};

Felloh uses minor currency units — GBX (pence), USX (cents), and EUX (euro cents). A value of 150000 in GBX equals £1,500.00.

Collect payment

Felloh offers multiple ways for agents to collect payment, depending on the workflow.

Payment links

The simplest approach — generate a shareable URL that directs the customer to a hosted payment page. Ideal when an agent needs to collect payment without handling card details.

Create a payment link

POST
https://api.felloh.com/agent/payment-links
import axios from 'axios';

const createPaymentLink = async (token, organisationId) => {
  const response = await axios({
    method: 'post',
    url: 'https://api.felloh.com/agent/payment-links',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    data: {
      organisation: organisationId,
      booking_reference: 'TRIP-2026-001',
      customer_email: 'jane.smith@example.com',
      amount: 50000,            // £500.00 deposit
      currency: 'GBX',
      description: 'Deposit for August trip',
      open_banking: true,
      card: true,
      redirect_url_success: 'https://example.com/payment/success',
      redirect_url_failure: 'https://example.com/payment/failure',
    },
  });

  return response.data;
};

Ecommerce sessions

For agents that want to embed payment collection in their own UI using the Felloh SDK, ecommerce sessions provide more control over the checkout experience.

Create an ecommerce session

POST
https://api.felloh.com/agent/ecommerce
import axios from 'axios';

const createEcommerceSession = async (token, organisationId) => {
  const response = await axios({
    method: 'post',
    url: 'https://api.felloh.com/agent/ecommerce',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    data: {
      organisation: organisationId,
      booking_reference: 'TRIP-2026-001',
      customer_email: 'jane.smith@example.com',
      customer_name: 'Jane Smith',
      amount: 50000,
      currency: 'GBX',
      open_banking: true,
      card: true,
    },
  });

  return response.data;
};

Scheduled payments

For installment plans common in travel — such as a deposit now and final payment before departure — agents can create scheduled payments using a tokenised card.

Create a scheduled payment

POST
https://api.felloh.com/agent/scheduled-payments
import axios from 'axios';

const createScheduledPayment = async (token, bookingId, tokenId) => {
  const response = await axios({
    method: 'post',
    url: 'https://api.felloh.com/agent/scheduled-payments',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    data: {
      booking_id: bookingId,
      amount: 100000,           // £1,000.00 final payment
      token_id: tokenId,
      execution_date: '2026-07-15',
    },
  });

  return response.data;
};

Scheduled payments require a tokenised card from a previous transaction on the booking. Use the get-available-tokens MCP tool or API endpoint to retrieve available tokens.

Process refunds

Felloh uses a two-stage refund process — an agent initiates the refund, and it enters a pending state that requires explicit authorisation. This prevents accidental refunds and supports compliance workflows.

Initiate a refund

POST
https://api.felloh.com/agent/transactions/{id}/refund
import axios from 'axios';

const refundTransaction = async (token, transactionId, amount) => {
  const response = await axios({
    method: 'post',
    url: `https://api.felloh.com/agent/transactions/${transactionId}/refund`,
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    data: {
      amount: amount,           // Partial or full amount in minor units
    },
  });

  return response.data;
};

Once a refund is initiated, it can be authorised or declined:

Authorise or decline a refund

import axios from 'axios';

const authoriseRefund = async (token, authorisationCode) => {
  const response = await axios({
    method: 'post',
    url: 'https://api.felloh.com/agent/refunds/authorise',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    data: {
      authorization_code: authorisationCode,
    },
  });

  return response.data;
};

Handle webhooks

Use webhooks to respond to payment events in real time. This is essential for agents that need to react to successful payments, failed transactions, or refund completions.

Webhook handler

import express from 'express';
import crypto from 'crypto';

const app = express();

app.post('/webhooks/felloh', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;

  // Verify the webhook signature
  const expected = crypto.createHmac('sha256', secret).update(req.body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'transaction.completed':
      // Payment succeeded — update booking status, notify customer
      console.log('Payment completed:', event.data.id);
      break;
    case 'transaction.failed':
      // Payment failed — alert agent, retry or send new payment link
      console.log('Payment failed:', event.data.id);
      break;
    case 'refund.completed':
      // Refund processed — confirm to customer
      console.log('Refund completed:', event.data.id);
      break;
  }

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

app.listen(4242, () => console.log('Webhook handler running on port 4242'));

Use with AI agents

The fastest way to integrate Felloh into an AI agent is via the MCP server. Once connected, your agent can call any Felloh tool directly.

Example agent prompts

With the Felloh MCP server connected, your AI agent can handle natural language requests like:

  • "Create a booking for Jane Smith, reference TRIP-2026-001, for £1,500 departing 15th August"
  • "Send a payment link for a £500 deposit to jane.smith@example.com"
  • "Show me all transactions for booking TRIP-2026-001"
  • "Refund £200 from transaction abc-123"
  • "Set up a scheduled payment of £1,000 on 15th July using the saved card"
  • "List all pending refunds and authorise them"

Example: installment plan workflow

A common travel payment pattern is collecting a deposit upfront and scheduling the balance for a later date. Here's how an agent orchestrates this:

  1. Agent creates a booking for £2,000 with departure on 15th August
  2. Agent creates a payment link for £500 (25% deposit) and sends it to the customer
  3. Customer pays via the payment link — their card is tokenised
  4. Agent retrieves available tokens on the booking
  5. Agent creates a scheduled payment for £1,500 using the tokenised card, set to execute 30 days before departure
  6. Felloh automatically charges the card on the scheduled date
  7. Agent monitors via webhooks and handles any failures

Testing

Use the Felloh sandbox environment (https://sandbox.felloh.com) to test your agent workflows without processing real payments. Sandbox credentials can be generated from the Felloh Dashboard.

For more details on testing, see the Developing your Integration guide.