Payment Links

A payment link is a shareable URL that directs customers to a hosted payment page. Payment links are valid until their expiry date or until a transaction is completed.

Payment Link Model

Properties

Name
id
Type
string
Description
Unique identifier for the payment link.
Name
booking
Type
object
Description
The booking model linked to the payment link.
Name
customer
Type
object
Description
The customer mode, linked to the payment link.
Name
email
Type
string
Description
The email address of the payee.
Name
methods.open_banking
Type
boolean
Description
Option to pay via open banking.
Name
methods.card
Type
boolean
Description
Option to pay via card.
Name
amount
Type
number
Description
Amount to be charged, in the lowest currency denomination (e.g., pence for GBP).
Name
currency
Type
string
Description
Currency of the transaction. See currency documentation.
Name
description
Type
string
Description
Description of the payment link's purpose.
Name
success_url
Type
string
Description
URL to redirect to upon payment success.
Name
failure_url
Type
string
Description
URL to redirect to upon payment failure.
Name
cancel_url
Type
string
Description
URL to redirect to upon payment cancellation.
Name
transactions
Type
array
Description
Contains transaction models created using the payment link.
Name
user
Type
object
Description
User object of the creator of the payment link.
Name
organisation
Type
object
Description
Organisation model owning the payment link.
Name
type
Type
object
Description
Type of the payment link.
Name
created_at
Type
datetime
Description
Date and time of creation within our systems.
Name
expires_at
Type
datetime
Description
Date and time when the payment link will expire.
Name
hide_store_card
Type
boolean
Description
Whether to hide the "Store card details for future payments" tickbox on payment pages.
Name
store_card_forced
Type
boolean
Description
Whether to force tokenisation of a customer card after payment.

{
  "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
  "booking": {
    "id": "9a33a74f-1e3e-595d-b89f-9da87d289e05",
    "email": "tom@felloh.org",
    "customer_name": "Tom Jones",
    "booking_reference": "FEL-00012",
    "departure_date": null,
    "return_date": null,
    "created_at": "2021-11-17T15:10:37.589Z"
  },
  "customer": {
    "id": "cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e",
    "customer_name": "Tom Jones",
    "email": "tom@felloh.org",
    "address_1": "The Old Rectory",
    "address_2": "Main Road",
    "city": "Belton",
    "county": "Lincolnshire",
    "country": "United Kingdom",
    "post_code": "NG32 2LW"
  },
  "email": "tom@felloh.org",
  "methods": {
    "open_banking": true,
    "card": true
  },
  "amount": 100,
  "currency": "GBX",
  "customer_name": "Tom Jones",
  "description": "Deposit for Bali",
  "success_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/success",
  "failure_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/failure",
  "cancel_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/cancel",
  "transactions": [
    {
      "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
      "amount": 100,
      "completed_at": "2021-11-17T15:11:37.581Z",
      "created_at": "2021-11-17T15:11:37.581Z"
    }
  ],
  "user": {
    "id": "e8c243ff-d000-4f81-ba57-94184d44dae2",
    "email": "tom@felloh.com"
  },
  "organisation": {
    "id": "X9876",
    "name": "Felloh"
  },
  "type": {
    "id": "UNKNOWN",
    "created_at": "2023-03-15T16:36:31.797Z"
  },
  "expires_at": "2021-12-17T15:10:37.589Z",
  "created_at": "2021-11-17T15:10:37.589Z"
}

POST/agent/payment-links

Fetch All

This endpoint retrieves all payment links, ordered by creation date with the most recent first.

Parameters

Name
organisationrequired
Type
string
Description
The organisation ID to fetch payment links for. Retrieve accessible organisations using the List all organisations method.
Name
keyword
Type
string
Description
Filter by customer name, booking reference, or email address.
Name
skip
Type
integer
Description
Pagination offset. See the pagination section for details.
Name
take
Type
integer
Description
Number of records to return. See the pagination section for details.
Name
show-child-organisations
Type
boolean
Description
Include payment links for child organisations.
Name
date_from
Type
date
Description
Start date for fetching payment links, in ISO 8601 format.
Name
date_to
Type
date
Description
End date for fetching payment links, in ISO 8601 format.
Name
filter_booking_exists
Type
boolean
Description
Filter based on whether a payment link is associated with a booking.

Returns

Returns an array of payment link models

Request

POST

/agent/payment-links

import axios from 'axios';

const response = await axios.post(
  'https://api.felloh.com/agent/payment-links',
  {
    organisation: 'X9876',
    keyword: 'james.dean@gmail.com',
    date_from: '2020-02-01',
    date_to: '2021-05-10',
    skip: 10,
    take: 20
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": [
    {
      "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
      "booking": {
        "id": "9a33a74f-1e3e-595d-b89f-9da87d289e05",
        "email": "tom@felloh.org",
        "customer_name": "Tom Jones",
        "booking_reference": "FEL-00012",
        "departure_date": null,
        "return_date": null,
        "created_at": "2021-11-17T15:10:37.589Z"
      },
      "customer": {
        "id": "cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e",
        "customer_name": "Tom Jones",
        "email": "tom@felloh.org",
        "address_1": "The Old Rectory",
        "address_2": "Main Road",
        "city": "Belton",
        "county": "Lincolnshire",
        "country": "United Kingdom",
        "post_code": "NG32 2LW"
      },
      "email": "tom@felloh.org",
      "methods": {
        "open_banking": true,
        "card": true
      },
      "amount": 100,
      "currency": "GBX",
      "customer_name": "Tom Jones",
      "description": "Deposit for Bali",
      "success_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/success",
      "failure_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/failure",
      "cancel_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/cancel",
      "transactions": [
        {
          "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
          "amount": 100,
          "completed_at": "2021-11-17T15:11:37.581Z",
          "created_at": "2021-11-17T15:11:37.581Z"
        }
      ],
      "user": {
        "id": "e8c243ff-d000-4f81-ba57-94184d44dae2",
        "email": "tom@felloh.com"
      },
      "organisation": {
        "id": "X9876",
        "name": "Felloh"
      },
      "expires_at": "2021-12-17T15:10:37.589Z",
      "created_at": "2021-11-17T15:10:37.589Z"
    }
  ],
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6",
    "count": 1
  }
}

GET/agent/payment-links/:payment_link_id

Fetch One

This endpoint allows you to retrieve a single payment link by its ID.

Path Parameters

Name
payment_link_id
Type
uuid
Description
The payment link ID to retrieve.

Returns

Returns a payment link model

Request

GET

/agent/payment-links/:payment_link_id

import axios from 'axios';

const paymentLinkID = 'b5e1bd24-7379-4d27-b4d8-07120fefc25c';

const response = await axios.get(
  `https://api.felloh.com/agent/payment-links/${paymentLinkID}`,
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {
    "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
    "booking": {
      "id": "9a33a74f-1e3e-595d-b89f-9da87d289e05",
      "email": "tom@felloh.org",
      "customer_name": "Tom Jones",
      "booking_reference": "FEL-00012",
      "departure_date": null,
      "return_date": null,
      "created_at": "2021-11-17T15:10:37.589Z"
    },
    "customer": {
      "id": "cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e",
      "customer_name": "Tom Jones",
      "email": "tom@felloh.org",
      "address_1": "The Old Rectory",
      "address_2": "Main Road",
      "city": "Belton",
      "county": "Lincolnshire",
      "country": "United Kingdom",
      "post_code": "NG32 2LW"
    },
    "email": "tom@felloh.org",
    "methods": {
      "open_banking": true,
      "card": true
    },
    "amount": 100,
    "currency": "GBX",
    "customer_name": "Tom Jones",
    "description": "Deposit for Bali",
    "success_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/success",
    "failure_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/failure",
    "cancel_url": "https://pay.felloh.com/b5e1bd24-7379-4d27-b4d8-07120fefc25c/cancel",
    "transactions": [
      {
        "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
        "amount": 100,
        "completed_at": "2021-11-17T15:11:37.581Z",
        "created_at": "2021-11-17T15:11:37.581Z"
      }
    ],
    "user": {
      "id": "e8c243ff-d000-4f81-ba57-94184d44dae2",
      "email": "tom@felloh.com"
    },
    "organisation": {
      "id": "X9876",
      "name": "Felloh"
    },
    "type": {
      "id": "UNKNOWN",
      "created_at": "2023-03-15T16:36:31.797Z"
    }
    "expires_at": "2021-12-17T15:10:37.589Z",
    "created_at": "2021-11-17T15:10:37.589Z"
  },
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}

PUT/agent/payment-links

Create One

This endpoint allows you to create a new payment link.

Parameters

Name
customer_namerequired
Type
string
Description
Full name of the customer.
Name
emailrequired
Type
string
Description
Email address of the customer.
Name
organisationrequired
Type
string
Description
Organisation ID where the payment link is created.
Name
amountrequired
Type
integer
Description
Amount to charge the customer, in the lowest currency denomination.
Name
typerequired
Type
string
Description
The payment link type ID.
Name
booking_id
Type
string
Description
Felloh booking ID to associate with the payment link.
Name
customer_id
Type
string
Description
Customer ID to autofill address fields on the card payment form.
Name
open_banking_enabled
Type
boolean
Description
Allow payment via open banking.
Name
card_enabled
Type
boolean
Description
Allow payment via card.
Name
description
Type
string
Description
Description of the payment's purpose, shown to the customer.
Name
expires_at
Type
date
Description
Expiry date for the payment link, defaults to 30 days from creation. This should be in ISO 8601 Format
Name
currency
Type
string
Description
Currency for transactions, defaults to GBX. See currency documentation.
Name
authorisation_only
Type
boolean
Description
Only authorise the payment (pre-auth), without capturing. Defaults to false.
Name
surcharging_enabled
Type
boolean
Description
Enable surcharging for the payment (if allowed by organisation). Defaults to true.
Name
dcc_enabled
Type
boolean
Description
Enable dynamic currency conversion (if allowed by organisation). Defaults to false.
Name
excluded_card_types
Type
array
Description
Card types to exclude from payment, options include AMEX, VISA, MASTER.
Name
excluded_card_regions
Type
array
Description
Card regions to exclude from payment, options include DOMESTIC, INTER, INTRA.
Name
hide_store_card
Type
boolean
Description
Whether to hide the "Store card details for future payments" tickbox on payment pages.
Name
store_card_forced
Type
boolean
Description
Whether to force tokenisation of a customer card after payment.

Returns

Name
id
Type
uuid
Description
Returns the ID of payment link model that has been created.

Request

PUT

/agent/payment-links

import axios from 'axios';

const response = await axios(
  {
    method: 'put',
    url: `https://api.felloh.com/agent/payment-links`,
    data : JSON.stringify({
        customer_name: 'Tom Brady',
        email: 'tom@felloh.com',
        booking_id: '226009ab-ffe9-4c80-922b-982e8e7849f8',
        customer_id: 'cc15e9a7-21bf-4d55-b500-2a24c8e4ed1e',
        amount: 20000, 
        currency: 'GBX',
        organisation: 'X1234',
        open_banking_enabled: true,
        card_enabled: true,
        description: 'Final payment for cruise holiday',
        expires_at: '2022-07-25',
        type: "UNKNOWN",
        surcharging_enabled: true,
        dcc_enabled: false,
        excluded_card_types: ["AMEX"],
        excluded_card_regions: ["INTER"],
        hide_store_card: false,
        store_card_forced: false
    }),
    headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer <YOUR TOKEN HERE>`,
    },
  },
);

Response

{
  "data": {
    "id": "226009ab-ffe9-4c80-922b-982e8e7849f8"
  },
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}

DELETE/agent/payment-links/:payment_link_id

Delete One

This endpoint allows you to delete a single payment link. Ensure no transactions have been made against the payment link before deletion.

A payment link can only be deleted if no transactions have occurred.

Path Parameters

Name
payment_link_id
Type
uuid
Description
The payment link ID to delete.

Request

DELETE

/agent/payment-links/:payment_link_id

import axios from 'axios';

const paymentLinkID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios.delete(
  `https://api.felloh.com/agent/payment-links/${paymentLinkID}`,
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {},
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}

POST/agent/payment-links/:payment_link_id/assign

Assign to Booking

This endpoint allows you to assign a payment link to a specific booking.

Required Parameters

Name
booking_id
Type
string
Description
The booking ID to assign the payment link.

Request

POST

/agent/payment-links/:payment_link_id/assign

import axios from 'axios';

const paymentLinkID = '226009ab-ffe9-4c80-922b-982e8e7849f8';
const bookingID = '226009ab-ffe9-4c80-922b-982e8e7849f8';

const response = await axios.post(
  `https://api.felloh.com/agent/payment-links/${paymentLinkID}/assign`,
  {
    booking_id: bookingID
  },
  {
    headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {},
  "errors": {},
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}