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: CARD or OPEN_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 null for 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"
  }
}

POST/agent/charges

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

POST
/agent/charges
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
  }
}

POST/agent/charges/aggregates

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: CARD or OPEN_BANKING.

  • Name
    country_type
    Type
    string
    Description

    Where the card was issued relative to you — DOMESTIC, INTRA or INTER. null for open banking.

  • Name
    card_type
    Type
    string
    Description

    DEBIT or CREDIT. null for open banking.

  • Name
    level
    Type
    string
    Description

    The card level, such as PERSONAL or CORPORATE. null for open banking.

  • Name
    payment_brand
    Type
    string
    Description

    The card scheme, such as VISA or MASTER. null for 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

POST
/agent/charges/aggregates
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"
  }
}