Charges
The charges object represents what Felloh charged on a transaction. It includes the booking reference, the transaction, the rate applied, and — for card payments — metadata such as card type and country.
Charges cover both card and open banking payments, and the two are worked out differently. Card charges are estimated from the rate information available from your merchant acquirer, and can vary. Open banking charges are the exact amounts billed on your Felloh invoice. Use type to tell them apart.
Charge Model
Properties
- Name
type- Type
- string
- Description
How the payment was taken:
CARDorOPEN_BANKING.
- Name
booking- Type
- object
- Description
Details about the booking, including the Felloh booking ID and your reference.
- Name
charges- Type
- object
- Description
Details about the charges, including amount, currency, and rate. For a card payment the amount is an estimate derived from the rate; for an open banking payment it is the amount billed on your invoice.
- Name
metadata- Type
- object
- Description
Card metadata for the transaction, such as card type and country type. Every field is
nullfor an open banking payment, which has no card behind it.
- Name
transaction- Type
- object
- Description
The transaction model that the charge relates to.
{
"type": "CARD",
"booking": {
"id": "ce9c7525-ec4e-44cd-a400-f2b6c8a5e1a9",
"booking_reference": "ABC-1234"
},
"charges": {
"amount": "2013",
"currency": "GBX",
"rate": "0.85"
},
"metadata": {
"level": "PERSONAL",
"card_type": "DEBIT",
"country_type": "DOMESTIC",
"payment_brand": "MASTER"
},
"transaction": {
"id": "a9832728-0107-11ed-b939-0242ac120002",
"amount": 130808,
"completed_at": "2024-03-31T04:01:14.000Z",
"created_at": "2024-03-31T04:00:10.149Z",
"currency": "GBX"
}
}
An open banking charge, with no card metadata:
{
"type": "OPEN_BANKING",
"booking": {
"id": "ce9c7525-ec4e-44cd-a400-f2b6c8a5e1a9",
"booking_reference": "ABC-1234"
},
"charges": {
"amount": "196",
"currency": "GBX",
"rate": "0.15"
},
"metadata": {
"level": null,
"card_type": null,
"country_type": null,
"payment_brand": null
},
"transaction": {
"id": "6830f98e-1bd4-4b55-87bb-ddf71914a2fd",
"amount": 130808,
"completed_at": "2024-03-31T04:01:14.000Z",
"created_at": "2024-03-31T04:00:10.149Z",
"currency": "GBX"
}
}
Fetch All
This endpoint retrieves all charges associated with an organisation within a specified date range.
Parameters
- Name
organisationrequired- Type
- string
- Description
The organisation ID that you want to fetch charges for. You can find the organisation you have access to by using the List all organisations method.
- Name
date_from- Type
- date
- Description
The starting date for fetching charges (by transaction completion date), in YYYY-MM-DD format.
- Name
date_to- Type
- date
- Description
The ending date for fetching charges (by transaction completion date, inclusive), in YYYY-MM-DD format.
- 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.
Returns
Returns an array of Charge Models
Request
import axios from 'axios';
const response = await axios.post(
'https://api.felloh.com/agent/charges',
{
organisation: 'X9876',
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": [
{
"type": "CARD",
"booking": {
"id": "ce9c7525-ec4e-44cd-a400-f2b6c8a5e1a9",
"booking_reference": "ABC-1234"
},
"charges": {
"amount": "2013",
"currency": "GBX",
"rate": "0.85"
},
"metadata": {
"level": "PERSONAL",
"card_type": "DEBIT",
"country_type": "DOMESTIC",
"payment_brand": "MASTER"
},
"transaction": {
"id": "a9832728-0107-11ed-b939-0242ac120002",
"amount": 130808,
"completed_at": "2024-03-31T04:01:14.000Z",
"created_at": "2024-03-31T04:00:10.149Z",
"currency": "GBX"
}
}
],
"errors": [],
"meta": {
"code": 200,
"reason": "OK",
"message": "The request was successful",
"request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6",
"count": 1
}
}
Aggregates
This endpoint summarises charges for an organisation, grouped by how the payment was taken and the rate it was charged at. Use it for totals rather than paging through every charge.
Card payments group by region, brand, card type and level — one row per combination. Open banking has no card behind it, so it collapses to a single row per currency with those fields null.
Parameters
- Name
organisationrequired- Type
- string
- Description
The organisation ID that you want to fetch charges for. You can find the organisation you have access to by using the List all organisations method.
- Name
date_from- Type
- date
- Description
The starting date for fetching charges (by transaction completion date), in YYYY-MM-DD format.
- Name
date_to- Type
- date
- Description
The ending date for fetching charges (by transaction completion date, inclusive), in YYYY-MM-DD format.
Returns
Returns an array of groups, each with:
- Name
type- Type
- string
- Description
How the payment was taken:
CARDorOPEN_BANKING.
- Name
country_type- Type
- string
- Description
Where the card was issued relative to you —
DOMESTIC,INTRAorINTER.nullfor open banking.
- Name
card_type- Type
- string
- Description
DEBITorCREDIT.nullfor open banking.
- Name
level- Type
- string
- Description
The card level, such as
PERSONALorCORPORATE.nullfor open banking.
- Name
payment_brand- Type
- string
- Description
The card scheme, such as
VISAorMASTER.nullfor open banking.
- Name
currency- Type
- string
- Description
The currency of the transactions in this group.
- Name
rate- Type
- string
- Description
The percentage rate applied to this group.
- Name
count- Type
- integer
- Description
How many transactions fall in this group.
- Name
tx_total- Type
- integer
- Description
The total value of those transactions, in minor units.
- Name
charges- Type
- integer
- Description
The total charged across the group, in minor units.
Request
curl -X POST https://api.felloh.com/agent/charges/aggregates \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{
"organisation": "ABC123",
"date_from": "2024-03-01",
"date_to": "2024-03-31"
}'
Response
{
"data": [
{
"type": "CARD",
"country_type": "DOMESTIC",
"card_type": "DEBIT",
"level": "PERSONAL",
"payment_brand": "VISA",
"currency": "GBX",
"rate": "0.65",
"count": "1067",
"tx_total": "144579666",
"charges": "939841"
},
{
"type": "OPEN_BANKING",
"country_type": null,
"card_type": null,
"level": null,
"payment_brand": null,
"currency": "GBX",
"rate": "0.15",
"count": "378",
"tx_total": "63347100",
"charges": "94911"
}
],
"errors": [],
"meta": {
"code": 200,
"reason": "OK",
"message": "The request was successful",
"request_id": "cdd40f5c-9d82-44c2-92e3-b5d2cad364f6"
}
}
