Scheduled Payment

The Scheduled Payment Object represents the lifecycle of a scheduled payment, encompassing its various states such as succeeded, failed, pending, and more. It serves as a comprehensive record of payments that are set to occur at a future date or on a recurring schedule. This object captures all relevant information about the payment.

For more on how to get started with scheduled payments, check out our guide on creating scheduled payments.

Scheduled Payment Model

The Scheduled Payment Model offers comprehensive details about future-dated payments scheduled within the Felloh system. This model includes key data points such as payment amounts, execution date, and links to associated entities like customers, bookings, and transactions.

Properties

  • Name
    id
    Type
    string
    Description

    Unique identifier for the object.

  • Name
    amount
    Type
    number
    Description

    The amount of the scheduled payment.

  • Name
    booking
    Type
    object
    Description

    The booking the scheduled payment is linked to, as an object containing id and booking_reference.

  • Name
    created_at
    Type
    datetime
    Description

    The datetime at which the scheduled payment was created within our systems.

  • Name
    currency
    Type
    string
    Description

    The currency of the transaction. See the currency model for more information.

  • Name
    customer
    Type
    object
    Description

    The customer the payment will be taken from, as an object containing id and customer_name.

  • Name
    execute_after
    Type
    datetime
    Description

    The datetime at which the payment is due to be taken.

  • Name
    organisation
    Type
    object
    Description

    The organisation that owns the scheduled payment, as an object containing id and name.

  • Name
    transaction
    Type
    object
    Description

    The transaction created when the payment executed, as an object containing id. The id is null until the payment has run.

  • Name
    status
    Type
    string
    Description

    The status of the scheduled payment. Values include QUEUED, AWAITING_APPROVAL, IN_PROGRESS, PROCESSING, COMPLETE and FAILED.

{
  "id": "fa4d2473-fc9f-4273-82bc-366a33ce719c",
  "amount": 50,
  "booking": {
      "id": "d3428360-fda6-41c3-995e-fbb0fdb69fd2",
      "booking_reference": "recurring-payment"
  },
  "created_at": "2024-10-16T13:53:14.075Z",
  "currency": "GBX",
  "customer": {
      "id": "368b61c0-717f-4132-afb8-09b10e5a56b5",
      "customer_name": "Adam Clark"
  },
  "execute_after": "2024-10-16T13:53:14.067Z",
  "organisation": {
      "id": "X1234",
      "name": "Felloh"
  },
  "transaction": {
      "id": "04416b80-ffa9-4874-abc9-f608cb2910f2"
  },
  "status": "COMPLETE"
}
POST/payment/scheduled-payment

Fetch All

This endpoint retrieves scheduled payments. By default only payments with status QUEUED are returned; pass total_filter with another status (for example COMPLETE or FAILED) to list those instead. Scheduled payments are sorted by creation date, with the most recent scheduled payments coming first.

Parameters

  • Name
    organisationrequired
    Type
    string
    Description

    The organisation ID that you want to fetch scheduled payments for. You can find the organisation that you have access to by using the list all organisations method.

  • Name
    keyword
    Type
    string
    Description

    A booking reference to filter by (case-insensitive, partial match).

  • Name
    total_filter
    Type
    string
    Description

    Return payments in this status instead of QUEUED, for example COMPLETE, FAILED, IN_PROGRESS or AWAITING_APPROVAL.

  • Name
    sort_by
    Type
    string
    Description

    Field to sort by: amount, created_at, execute_after or status. Defaults to created_at.

  • Name
    direction
    Type
    string
    Description

    Sort direction, asc or desc. Defaults to desc.

  • Name
    skip
    Type
    integer
    Description

    Pagination offset. See pagination documentation for details.

  • Name
    take
    Type
    integer
    Description

    Number of records to return. Defaults to 25, maximum 25. See the pagination section for details.

  • Name
    show-child-organisations
    Type
    boolean
    Description

    Whether to also show scheduled payments for any of the requested organisation's child organisations.

Returns

Returns an array of Scheduled Payment Models

Request

POST
/payment/scheduled-payment
import axios from 'axios';

const response = await axios.post(
  'https://api.felloh.com/payment/scheduled-payment',
  {
      organisation: 'X9876',
      skip: 10,
      take: 20,
  },
  {
      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

JSON Response

{
  "data": [
    {
      "id": "fa4d2473-fc9f-4273-82bc-366a33ce719c",
      "amount": 50,
      "booking": {
          "id": "d3428360-fda6-41c3-995e-fbb0fdb69fd2",
          "booking_reference": "recurring-payment"
      },
      "created_at": "2024-10-16T13:53:14.075Z",
      "currency": "GBX",
      "customer": {
          "id": "368b61c0-717f-4132-afb8-09b10e5a56b5",
          "customer_name": "Adam Clark"
      },
      "execute_after": "2024-10-16T13:53:14.067Z",
      "organisation": {
          "id": "X1234",
          "name": "Felloh"
      },
      "transaction": {
          "id": "04416b80-ffa9-4874-abc9-f608cb2910f2"
      },
      "status": "COMPLETE"
    }
    ],
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6",
    "count": 1
  }
}
GET/payment/booking/:booking_id/available-tokens

Get Cards On Booking

This endpoint retrieves all available tokens associated with a specific booking. Tokens represent saved payment methods and include details like the cardholder name, card brand, and organisation ID.

Path Parameters

  • Name
    booking_id
    Type
    UUID
    Description

    The booking ID you wish to find tokenised card details for.

Returns

Returns an array of Tokenised Card Models

Request

GET
/payment/booking/:booking_id/available-tokens
import axios from 'axios';

const bookingId = 'd8529e8d-dbfd-41fc-bc35-71bbe91ab719';
const response = await axios.get(
  `https://api.felloh.com/payment/booking/${bookingId}/available-tokens`,
  {
    headers: { 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

console.log(response.data);

JSON Response

{
    "data": [
        {
            "id": "3067549d-d3ce-4002-8d02-b10bc38af53b",
            "cardholder_name": "Adam Clark",
            "bin": "43965400",
            "card_brand": "VISA",
            "organisation_id": "X1234"
        }
    ],
    "errors": [],
    "meta": {
        "code": 200,
        "reason": "OK",
        "message": "The request was successful",
        "request_id": "ead76d39-f561-4ed9-be8a-008454e3fc77"
    }
}
POST/payment/booking/{bookingId}/payment

Create Payment for Booking

This endpoint creates a payment for a specific booking.

Parameters

  • Name
    bookingIdrequired
    Type
    string
    Description

    The unique ID of the booking for which the payment is being created. This must be included in the URL path.

Payload

  • Name
    tokenrequired
    Type
    string
    Description

    The token representing the payment method to be used. Tokens can be retrieved using the Get Cards On Booking endpoint; use the id field of the returned tokenised card.

  • Name
    amountrequired
    Type
    number
    Description

    The amount to be paid. This value should be in the smallest currency unit (e.g., cents for USD or pence for GBP).

  • Name
    date
    Type
    string
    Description

    The date and time when the payment should be executed, in ISO 8601 format. If no date is provided, then the payment will be taken immediately.

  • Name
    authorisation_only
    Type
    boolean
    Description

    Only authorise the payment (pre-auth) when it executes, without capturing. The resulting transaction can be captured or reversed later. Note that uncaptured authorisations expire after around 7 days, depending on the card scheme. Defaults to false.

Returns

An empty object is returned upon successful payment creation.

Request

POST
/payment/booking/{bookingId}/payment
import axios from 'axios';

const payload = {
  token: "3067549d-d3ce-4002-8d02-b10bc38af53b",
  amount: 25,
  date: "2025-03-29T00:00:00.000Z"
};

const response = await axios.post(
  'https://api.felloh.com/payment/booking/d8529e8d-dbfd-41fc-bc35-71bbe91ab719/payment',
  payload,
  {
    headers: { 'Authorization': `Bearer <YOUR TOKEN HERE>`, 'Content-Type': 'application/json' }
  }
);

console.log(response.data);

JSON Response

{
    "data": {},
    "errors": [],
    "meta": {
        "code": 200,
        "reason": "OK",
        "message": "The request was successful",
        "request_id": "011cf9dc-c2b5-4bd1-90ad-825389521a08"
    }
}
POST/agent/bookings/{bookingId}/approval-link

This endpoint generates an approval link for scheduled payments for a specific booking. The approval link will be emailed to your customer when this endpoint is hit.

This is an optional feature and must be enabled on the Organisation Settings Page. If not enabled, scheduled payments will be automatically approved.

Parameters

  • Name
    bookingIdrequired
    Type
    string
    Description

    The unique ID of the booking for which the approval link is being generated. This must be included in the URL path.

Returns

An empty object is returned upon the approval link being sent to the customer.

Request

POST
/agent/bookings/{bookingId}/approval-link
import axios from 'axios';

const response = await axios.post(
  'https://api.felloh.com/agent/bookings/d8529e8d-dbfd-41fc-bc35-71bbe91ab719/approval-link',
  {},
  {
    headers: { 'Authorization': `Bearer <YOUR TOKEN HERE>`, 'Content-Type': 'application/json' }
  }
);

console.log(response.data);

JSON Response

{
    "data": {},
    "errors": [],
    "meta": {
        "code": 200,
        "reason": "OK",
        "message": "The request was successful",
        "request_id": "12345678-90ab-cdef-1234-567890abcdef"
    }
}
DELETE/payment/scheduled-payment/{paymentId}

Cancel Scheduled Payment

This endpoint cancels a scheduled payment by its unique ID. Once canceled, the payment will no longer be executed.

Parameters

  • Name
    paymentIdrequired
    Type
    string
    Description

    The unique ID of the scheduled payment to cancel. This must be included in the URL path.

Returns

An empty object is returned upon successful cancellation. Only payments with status QUEUED or AWAITING_APPROVAL can be cancelled; any other status returns a 400 with the error code scheduled_payment.not_cancellable, and an unknown id returns a 404.

Request

DELETE
/payment/scheduled-payment/{paymentId}
import axios from 'axios';

const response = await axios.delete(
  'https://api.felloh.com/payment/scheduled-payment/da08e745-2382-4619-bbb2-c85982672557',
  {
    headers: { 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

console.log(response.data);

JSON Response

{
    "data": {},
    "errors": [],
    "meta": {
        "code": 200,
        "reason": "OK",
        "message": "The request was successful",
        "request_id": "87654321-fedc-ba09-8765-432109abcdef"
    }
}