Payment Links

A payment link is a shareable URL that will take your customers to a hosted payment page.

When a customer opens a payment link it will generate a new checkout transaction to render the payment page.

Payment links are usable until their expiry date or until a completed transaction is made against them.

The Payment Link Object

{
  "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"
  },
  "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"
}

The compact payment link object

{
  "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
  "amount": 100,
  "currency": "GBX",
  "description": "Deposit for Bali",
  "expires_at": "2021-12-17T15:10:37.589Z",
  "created_at": "2021-11-17T15:10:37.589Z"
}

idstring

Unique identifier for the object

bookingobject

The booking object that the payment link is linked to

emailstring

The email address of the payee

methods.open_bankingboolean

Whether the customer will be presented with the option to pay by open banking

methods.cardboolean

Whether the customer will be presented with the option to pay by card

amountnumber

The amount that the customer should be charged, in its lowest denomination (for GBP, this would be pence)

currencystring

The currency that the payment link will be charged in | see currency documentation

customer_namestring

The name of the customer that the payment link is for

descriptionstring

Description of what the payment link is for

success_urlstring

The url that the payment link will redirect to on payment success

failure_urlstring

The url that the payment link will redirect to on payment failure

cancel_urlstring

The url that the payment link will redirect to on payment cancellation

transactionsarray

An array containing any compact transaction objects created using the payment link

userobject

The compact user object of the user that created the booking

organisationobject

A compact organisation object representing the organisation owner of the payment link.

typeobject

The type of that payment link.

created_atdatetime

The datetime at which the payment link object was created within our systems

expires_atdatetime

The datetime at which the payment link will no longer be usable by a customer

---

Fetch all

POST/agent/payment-links

import axios from 'axios';

const response = await axios(
  {
    method: 'post',
    url: 'https://api.felloh.com/agent/payment-links',
    data: {
        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"
      },
      "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
  }
}

This endpoint retrieves all payment links. Payment links are sorted by creation date by default, with the most recent payment links coming first.

HTTP Method

POST

HTTP Endpoint

PRODhttps://api.felloh.com/agent/payment-links

SANDBOXhttps://sandbox.felloh.com/agent/payment-links

Payload

Parameter	Required	Type	Description
organisation	true	string	The organisation ID that you want to fetch payment links for. You can find the organisation that you have access to by using the List all organisations method.
keyword	false	string	A customer name, booking reference or email address that you want to filter by.
skip	false	Integer	See pagination section for details
take	false	Integer	See pagination section for details
show-child-organisations	fasle	Boolean	Whether to also show payment links for any of the requested organisations child organisations
date_from	false	date	The creation date that you want to get payment links from, in ISO 8601 format
date_to	false	date	The creation date that you want to get payment links to, in ISO 8601 format
filter_booking_exists	false	boolean	Allows filtering based on whether the payment link has a booking attatched to it. If null, then no filtering. If true, then only payment links with bookings. If False, then only payment links without bookings.

Response

Returns an array of Payment links

---

Fetch one

GET/agent/payment-links/226009ab-ffe9-4c80-922b-982e8e7849f8

import axios from 'axios';

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

const response = await axios(
  {
    method: 'get',
    url: `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"
    },
    "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"
  }
}

This endpoint allows you to retrieve a single payment link

HTTP Method

GET

HTTP Endpoint

PRODhttps://api.felloh.com/agent/payment-links/<PAYMENT LINK ID>

SANDBOXhttps://sandbox.felloh.com/agent/payment-links/<PAYMENT LINK ID>

Path Parameters

Parameter	Required	Type	Description
id	true	UUID	The payment link id that you wish to retrieve

Response

Returns a Payment Link Object

---

Delete one

DELETE/agent/payment-links/226009ab-ffe9-4c80-922b-982e8e7849f8

import axios from 'axios';

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

const response = await axios(
  {
    method: 'delete',
    url: `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"
  }
}

This endpoint allows you to delete a single payment link

HTTP Method

DELETE

HTTP Endpoint

PRODhttps://api.felloh.com/agent/payment-links/<PAYMENT LINK ID>

SANDBOXhttps://sandbox.felloh.com/agent/payment-links/<PAYMENT LINK ID>

Path Parameters

Parameter	Required	Type	Description
id	true	UUID	The payment link id that you wish to delete

---

Create one

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',
        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",
    }),
    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"
  }
}

This endpoint allows you to create a new payment link

HTTP Method

PUT

HTTP Endpoint

PRODhttps://api.felloh.com/agent/payment-links

SANDBOXhttps://sandbox.felloh.com/agent/payment-links

Payload

Parameter	Required	Type	Description
customer_name	true	string	The customers full name.
email	true	string	The customers email address
organisation	true	string	The organisation ID that you want to create the payment link in.
booking_id	false	string	The booking ID that you want to assign the payment link to. This can be assigned later if you wish.
amount	true	integer	The value that you want to charge the customer
openbankingenabled	false	bool	Whether to allow the customer to pay via open banking
card_enabled	false	bool	Whether to allow the customer to pay via card
description	false	string	The description of what the payment is for, which will be show to the customer.
expires_at	false	date	The date that the payment link will expire, defaults to 30 days from date created.
currency	false	string	The currency that transactions will be undertaken in, defaults to GBX, see currency documentation for more information.
type	true	string	The payment link type ID.

Response

Parameter	Type	Description
id	UUID	The ID of the payment link that you have created

---

Assign to booking

POST/agent/payment-links/{paymentlinkid}/assign

import axios from 'axios';

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

const response = await axios(
  {
    method: 'post',
    url: `https://api.felloh.com/agent/payment-links/${paymentLinkID}/assign`,
    data : JSON.stringify({
      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"
  }
}

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

HTTP Method

POST

HTTP Endpoint

PRODhttps://api.felloh.com/agent/payment-links/{payment_link_id}/assign

SANDBOXhttps://sandbox.felloh.com/agent/payment-links/{payment_link_id}/assign

Payload

Parameter	Required	Type	Description
booking_id	false	string	The booking ID that you want to assign the payment link to.