Ecommerce

This feature must be enabled by your account manager and is not available by default.

An ecommerce object allows you to take a payment via the SDK, similar to a typical ecommerce transaction. It is associated with a customer, booking, and specific payment methods.

Ecommerce Model

Properties

Name
id
Type
uuid
Description
Unique identifier for the ecommerce object.
Name
booking
Type
object
Description
The booking model linked to the ecommerce session.
Name
customer
Type
object
Description
The customer model associated with this ecommerce session.
Name
email
Type
string
Description
The email address of the payee.
Name
methods.open_banking
Type
boolean
Description
Option for the customer to pay using open banking.
Name
methods.card
Type
boolean
Description
Option for the customer to pay using a card.
Name
amount
Type
number
Description
The amount to be charged, in the lowest currency denomination (e.g., pence for GBP).
Name
currency
Type
string
Description
The currency for the transaction. See the currency documentation.
Name
customer_name
Type
string
Description
The name of the customer for whom the ecommerce session is intended.
Name
transactions
Type
array
Description
Any transaction models created using the ecommerce object.
Name
user
Type
object
Description
The user object of the creator of the ecommerce session.
Name
organisation
Type
object
Description
The organisation model representing the owner of the ecommerce session.
Name
created_at
Type
datetime
Description
The datetime when the ecommerce session was created in our systems.
Name
expires_at
Type
datetime
Description
The datetime when the ecommerce session will no longer be valid.
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",
  "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"
}

POST/agent/ecommerce

Fetch All

This endpoint retrieves all ecommerce objects for an organisation, sorted by creation date with the most recent first.

Parameters

Name
organisationrequired
Type
string
Description
The organisation ID to fetch ecommerce objects 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 ecommerce sessions for child organisations.
Name
date_from
Type
date
Description
Start date for fetching ecommerce objects, in ISO 8601 format.
Name
date_to
Type
date
Description
End date for fetching ecommerce objects, in ISO 8601 format.

Returns

Returns an array of Ecommerce Models

Request

POST

/agent/ecommerce

import axios from 'axios';

const response = await axios.post(
  'https://api.felloh.com/agent/ecommerce',
  {
    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",
      "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/ecommerce/:ecommerce_id

Fetch One

This endpoint allows you to retrieve a single ecommerce session by its ID.

Path Parameters

Name
ecommerce_id
Type
uuid
Description
The ecommerce object ID to retrieve.

Returns

Returns an Ecommerce Model

Request

GET

/agent/ecommerce/:ecommerce_id

import axios from 'axios';

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

const response = await axios.get(
  `https://api.felloh.com/agent/ecommerce/${ecommerceID}`,
  {
    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",
    "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"
  }
}

PUT/agent/ecommerce

Create One

This endpoint allows you to create a new ecommerce session.

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 for which the ecommerce session is being created.
Name
amountrequired
Type
integer
Description
Amount to charge the customer, in the lowest currency denomination.
Name
booking_id
Type
string
Description
Booking ID to assign the ecommerce session. Can be added later if required.
Name
customer_id
Type
string
Description
Customer ID to pre-fill address fields on the card payment form.
Name
open_banking_enabled
Type
boolean
Description
Allow customer to pay using open banking.
Name
card_enabled
Type
boolean
Description
Allow customer to pay using card.
Name
expires_at
Type
date
Description
Expiry date for the ecommerce session, defaults to 30 days from creation.
Name
currency
Type
string
Description
Currency for the transaction, defaults to GBX. See currency documentation for more information.
Name
authorisation_only
Type
boolean
Description
If set to true, the payment will be authorised but not captured. Defaults to false.
Name
surcharging_enabled
Type
boolean
Description
If true, surcharging will be enabled (if allowed by the 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
Specific card types to exclude, e.g., AMEX, VISA, MASTER.
Name
excluded_card_regions
Type
array
Description
Specific card regions to exclude, e.g., 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
string
Description
The ID of the created ecommerce instance, this can be used in your application when rendering the SDK Element.

Request

PUT

/agent/ecommerce

import axios from 'axios';

const response = await axios.put(
  'https://api.felloh.com/agent/ecommerce',
  {
    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,
    expires_at: '2022-07-25',
    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/ecommerce/:ecommerce_id

Delete One

This endpoint allows you to delete a single ecommerce object. This can only be undertaken on ecommerce objects that have not had any transactions undertaken on them.

Ensure there are no transactions on the ecommerce object before attempting to delete it.

Path Parameters

Name
ecommerce_id
Type
uuid
Description
The ecommerce object ID to delete.

Request

DELETE

/agent/ecommerce/:ecommerce_id

import axios from 'axios';

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

const response = await axios.delete(
  `https://api.felloh.com/agent/ecommerce/${ecommerceID}`,
  {
    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/ecommerce/:ecommerce_id/assign

Assign to Booking

This endpoint allows you to assign an ecommerce object to a specific booking.

Parameters

Name
booking_idrequired
Type
string
Description
The booking ID to assign the ecommerce object.

Request

POST

/agent/ecommerce/:ecommerce_id/assign

import axios from 'axios';

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

const response = await axios.post(
  `https://api.felloh.com/agent/ecommerce/${ecommerceID}/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"
  }
}