Transactions

This object represents a customer's transaction (completed, pending, and failed). These can be undertaken within our system or yours.

Transaction Model

The Transaction Model provides detailed information about each financial transaction processed through our system. This model includes essential data points such as transaction amounts, currencies, timestamps, and links to associated entities like customers and bookings.

Properties

Name
id
Type
string
Description
Unique identifier for the object.
Name
amount
Type
number
Description
The amount of the transaction.
Name
currency
Type
string
Description
The currency of the transaction | see currency documentation.
Name
booking
Type
object
Description
The booking model that the transaction is linked to.
Name
organisation
Type
object
Description
The organisation model that the transaction is linked to.
Name
status
Type
string
Description
The status of the payment.
Name
method
Type
string
Description
The method that was used to take payment.
Name
type
Type
string
Description
The type of payment method that was used.
Name
payment_link
Type
object
Description
The payment link model that was used to create the transaction.
Name
metadata.card_type
Type
string
Description
The card type that the charge was for, can be CREDIT or DEBIT.
Name
metadata.bin_type
Type
string
Description
The bin type of the card, can be PERSONAL or COMMERCIAL.
Name
metadata.payment_brand
Type
string
Description
The brand of the card that payment was taken on. Most common values are MASTER, AMEX or VISA.
Name
metadata.issuing_country
Type
string
Description
Issuing country of card in ISO 3166 format.
Name
metadata.last_four_digits
Type
string
Description
The last four digits of the payment card.
Name
metadata.cardholder_name
Type
string
Description
The name of the cardholder.
Name
provider_reference
Type
string
Description
The payment provider's reference for the transaction.
Name
completed_at
Type
datetime
Description
The datetime at which the transaction object was completed (payment taken).
Name
risk_rank
Type
string
Description
Felloh's model-assessed chargeback risk for the transaction: low, medium or high. Intended for review prioritisation, not automated blocking. null when the transaction has not been scored.
Name
risk_score
Type
number
Description
The underlying risk score between 0 and 1 that produced risk_rank. Higher is riskier. null when the transaction has not been scored.
Name
risk_reasons
Type
array
Description
The risk categories the model flagged for the transaction, ordered by confidence. Possible values: card_testing, velocity, location_mismatch, anonymous_device, new_customer, last_minute_travel. An empty array means no category was flagged; null when the transaction has not been scored. location_mismatch and anonymous_device are never flagged on MOTO transactions (call-centre payments share the merchant's network and devices), and last_minute_travel is only flagged when the transaction has a booking with a departure date.
Name
risk_scored_at
Type
datetime
Description
The datetime at which the transaction was risk scored. null when the transaction has not been scored.
Name
created_at
Type
datetime
Description
The datetime at which the transaction object was created within our systems.
Name
surcharge.amount
Type
number
Description
The total value of surcharges on the transaction (this will only be available if you have surcharging enabled).
Name
surcharge.currency
Type
string
Description
The currency of surcharges on the transaction (this will only be available if you have surcharging enabled).

{
  "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
  "amount": 1021,
  "currency": "GBX",
  "booking": {
    "id": "9a33a74f-1e3e-595d-b89f-9da87d289e05",
    "email": "tom@felloh.org",
    "customer_name": "Tom Jones",
    "booking_reference": "FEL-123456",
    "departure_date": null,
    "return_date": null,
    "created_at": "2021-11-17T15:10:37.589Z"
  },
  "organisation": {
    "id": "X000",
    "name": "Felloh"
  },
  "status": "COMPLETE",
  "method": "ONLINE",
  "type": "CARD",
  "payment_link": {
    "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
    "amount": 1000,
    "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",
    "expires_at": "2021-12-17T15:10:37.589Z",
    "created_at": "2021-11-17T15:10:37.589Z"
  },
  "metadata": {
    "card_type": "DEBIT",
    "bin_type": "PERSONAL",
    "payment_brand": "MASTER",
    "issuing_country": "GB",
    "currency": "GBP",
    "last_four_digits": "4397",
    "cardholder_name": "Tom Jones",
    "created_at": "2021-11-17T15:11:37.581Z"
  },
  "surcharge": {
    "amount": 21,
    "currency": "GBX"
  },
  "provider_reference": "vmtest-12313211413-ab",
  "risk_rank": "low",
  "risk_score": 0.184,
  "risk_reasons": [],
  "risk_scored_at": "2021-11-17T16:02:11.101Z",
  "completed_at": "2021-11-17T15:11:37.581Z",
  "created_at": "2021-11-17T15:11:37.581Z"
}

POST/agent/transactions

Fetch All

This endpoint retrieves all transactions. Transactions are sorted by creation date, with the most recent transactions coming first.

Parameters

Name
organisationrequired
Type
string
Description
The organisation ID that you want to fetch transactions 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, customer name or provider reference to filter by (case-insensitive, partial match).
Name
skip
Type
integer
Description
Pagination offset. See the pagination section 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 transactions for any of the requested organisation's child organisations.
Name
type
Type
string
Description
Can be 'csv' or 'json', defaults to 'json'.
Name
date_from
Type
date
Description
The date that you want to get transactions from, in YYYY-MM-DD format.
Name
date_to
Type
date
Description
The date that you want to get transactions to, in YYYY-MM-DD format.
Name
statuses
Type
array
Description
An array of statuses can be provided if you wish to filter by transaction status. If this is not provided, the query will default to exclude abandoned and pending transactions. A full list of transaction statuses can be found by using the enums endpoint.

Returns

Returns an array of Transaction Models

Request

POST

/agent/transactions

import axios from 'axios';

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

Response (set using type parameter)

{
  "data": [{
    "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
    "amount": 1000,
    "currency": "GBX",
    "booking": {
      "id": "9a33a74f-1e3e-595d-b89f-9da87d289e05",
      "email": "tom@felloh.org",
      "customer_name": "Tom Jones",
      "booking_reference": "FEL-123456",
      "departure_date": null,
      "return_date": null,
      "created_at": "2021-11-17T15:10:37.589Z"
    },
    "organisation": {
      "id": "X000",
      "name": "Felloh"
    },
    "status": "COMPLETE",
    "method": "ONLINE",
    "type": "CARD",
    "payment_link": {
      "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
      "amount": 1000,
      "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",
      "expires_at": "2021-12-17T15:10:37.589Z",
      "created_at": "2021-11-17T15:10:37.589Z"
    },
    "metadata": {
      "card_type": "DEBIT",
      "bin_type": "PERSONAL",
      "payment_brand": "MASTER",
      "issuing_country": "GB",
      "currency": "GBP",
      "last_four_digits": "4397",
      "cardholder_name": "Tom Jones",
      "created_at": "2021-11-17T15:11:37.581Z"
    },
    "surcharge": {
      "amount": 21,
      "currency": "GBX"
    },
    "provider_reference": "vmtest-12313211413-ab",
    "completed_at": "2021-11-17T15:11:37.581Z",
    "created_at": "2021-11-17T15:11:37.581Z"
  }],
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6",
    "count": 1
  }
}

GET/agent/transactions/:transaction_id

Fetch One

This endpoint retrieves a specific transaction by its ID.

Path Parameters

Name
transaction_id
Type
UUID
Description
The transaction ID you wish to retrieve.

Returns

Returns a of Transaction Model

Request

GET

/agent/transactions/:transaction_id

import axios from 'axios';

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

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

Response

{
  "data": {
    "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
    "amount": 1000,
    "currency": "GBX",
    "booking": {
      "id": "9a33a74f-1e3e-595d-b89f-9da87d289e05",
      "email": "tom@felloh.org",
      "customer_name": "Tom Jones",
      "booking_reference": "FEL-123456",
      "departure_date": null,
      "return_date": null,
      "created_at": "2021-11-17T15:10:37.589Z"
    },
    "organisation": {
      "id": "X000",
      "name": "Felloh"
    },
    "status": "COMPLETE",
    "method": "ONLINE",
    "type": "CARD",
    "payment_link": {
      "id": "b5e1bd24-7379-4d27-b4d8-07120fefc25c",
      "amount": 1000,
      "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",
      "expires_at": "2021-12-17T15:10:37.589Z",
      "created_at": "2021-11-17T15:10:37.589Z"
    },
    "metadata": {
      "card_type": "DEBIT",
      "bin_type": "PERSONAL",
      "payment_brand": "MASTER",
      "issuing_country": "GB",
      "currency": "GBP",
      "last_four_digits": "4397",
      "cardholder_name": "Tom Jones",
      "created_at": "2021-11-17T15:11:37.581Z"
    },
    "surcharge": {
      "amount": 21,
      "currency": "GBX"
    },
    "provider_reference": "vmtest-12313211413-ab",
    "completed_at": "2021-11-17T15:11:37.581Z",
    "created_at": "2021-11-17T15:11:37.581Z"
  },
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}

POST/agent/transactions/:transaction_id/refund

Generate a Refund

This endpoint generates a refund request and requires the refund:request role. By default the refund must then be authorised by a member of your organisation with the refund:approve role, using the Authorise One endpoint or the dashboard. If refund authorisation has been disabled for your organisation, the refund is authorised and sent for processing immediately.

Path Parameters

Name
transaction_id
Type
UUID
Description
The transaction ID you wish to refund.

Parameters

Name
amount
Type
integer
Description
The amount of the transaction that you wish to refund in the lowest denomination of the currency (for GBX it is pence, for USX it is cents). Defaults to the full transaction amount and cannot exceed it.
Name
description
Type
string
Description
A user defined description for the refund
Name
metadata
Type
object
Description
User defined metadata relating to the refund, such as internal ids, etc....

Returns

Returns the created refund. Keep the authorisation_code: it identifies the refund on the authorise and decline endpoints. The status, organisation and transaction objects are not populated in this response; use the refunds list to see the full refund.

Request

POST

/agent/transactions/:transaction_id/refund

import axios from 'axios';

const transactionID = '226009ab-ffe9-4c80-922b-982e8e7849f8';
const amount = 90;
const metadata = { internal_id: 'abc_1234' }

const response = await axios.post(
  `https://api.felloh.com/agent/transactions/${transactionID}/refund`,
  { amount },
  {
      headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer <YOUR TOKEN HERE>` }
  }
);

Response

{
  "data": {
    "id": "7c3f2a1e-5b7d-4c1a-9e2f-3d4b5a6c7d8e",
    "amount": 90,
    "description": null,
    "status": null,
    "requesting_user": null,
    "authorised_user": null,
    "authorisation_code": "19b6698d-d614-45e0-ae90-6a3ea0662431",
    "authorised_at": null,
    "organisation": null,
    "completed_at": null,
    "transaction": null,
    "created_at": "2023-08-01T10:19:10.904Z",
    "error_message": null,
    "metadata": {}
  },
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}

GET/agent/transactions/:transaction_id/complete

Complete a Pre-Authorised Transaction

This endpoint allows you to complete a pre-authorised transaction.

Path Parameters

Name
transaction_id
Type
UUID
Description
The transaction ID you wish to complete.

Request

GET

/agent/transactions/:transaction_id/complete

import axios from 'axios';

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

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

GET/agent/transactions/:transaction_id/reverse

Reverse a Pre-Authorised Transaction

This endpoint allows you to reverse a pre-authorised transaction.

Path Parameters

Name
transaction_id
Type
UUID
Description
The transaction ID you wish to reverse.

Request

GET

/agent/transactions/:transaction_id/reverse

import axios from 'axios';

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

const response = await axios.get(
  `https://api.felloh.com/agent/transactions/${transactionID}/reverse`,
  {
    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/transactions/:transaction_id/re-assign

Re-assign a Transaction

This endpoint allows you to re-assign a transaction from one booking to another.

Path Parameters

Name
transaction_id
Type
UUID
Description
The transaction ID you wish to re-assign.

Parameters

Name
booking_idrequired
Type
string
Description
The new booking ID to which the transaction will be re-assigned.

Request

POST

/agent/transactions/:transaction_id/re-assign

import axios from 'axios';

const transactionID = '226009ab-ffe9-4c80-922b-982e8e7849f8';
const newBookingID = 'b7c259ba-d356-4263-912f-c6c4e29155ec';

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

Response

{
  "data": {
    "booking": {
      "id": "b7c259ba-d356-4263-912f-c6c4e29155ec",
      "email": "tom@felloh.org",
      "customer_name": "Tom Jones",
      "booking_reference": "FEL-123456",
      "departure_date": null,
      "return_date": null,
      "created_at": "2021-11-17T15:10:37.589Z"
    },
    "transaction": {
      "id": "226009ab-ffe9-4c80-922b-982e8e7849f8",
      "amount": 1000,
      "currency": "GBX",
      "status": "COMPLETE",
      "method": "ONLINE",
      "type": "CARD",
      "provider_reference": "vmtest-12313211413-ab",
      "completed_at": "2021-11-17T15:11:37.581Z",
      "created_at": "2021-11-17T15:11:37.581Z"
    }
  },
  "errors": [],
  "meta": {
    "code": 200,
    "reason": "OK",
    "message": "The request was successful",
    "request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
  }
}