Tillo API

Appearance

Floats ​

Our API can also be used to manage your account's floats.

Check Floats ​

Fetch the real-time balance of any funds or credit for all float accounts you have on the platform.

The total of any pending payment transfers is also returned for each float. Results will be grouped by currency, and may be filtered by currency, e.g. GBP.

WARNING

If you are using International Payments and using the check-floats endpoint, currencies that are mapped in International Payments will not be visible.

The example request/response below shows available balance and pending payments for a sample set of GBP floats.

text
GET /api/v2/check-floats?currency=GBP
GET /api/v2/check-floats?currency=GBP
json
  "GBP": {
      "universal-float": {
          "available_balance": {
              "amount": 1999.49,
              "currency": "GBP"
          },
          "pending_payments": {
              "amount": 10000,
              "currency": "GBP"
          }
      },
      "amazon": {
        "available_balance": {
            "amount": 5999.51,
            "currency": "GBP"
        },
        "pending_payments": {
          "amount": 0,
          "currency": "GBP"
        }
      }
  }
  "GBP": {
      "universal-float": {
          "available_balance": {
              "amount": 1999.49,
              "currency": "GBP"
          },
          "pending_payments": {
              "amount": 10000,
              "currency": "GBP"
          }
      },
      "amazon": {
        "available_balance": {
            "amount": 5999.51,
            "currency": "GBP"
        },
        "pending_payments": {
          "amount": 0,
          "currency": "GBP"
        }
      }
  }

Request Float Payment Transfer ​

Register a request for a payment transfer to fund one of your floats. The float name and currency must correspond to one of the results in your check-floats response.

Our API will automatically generate a payment reference, or you may optionally supply your own payment reference, as in the following request/response.

json
POST /api/v2/float/request-payment-transfer
{
  "float": "universal-float",
  "currency": "GBP",
  "amount": 100.00,
  "payment_reference": "OUR_REF"
 }
POST /api/v2/float/request-payment-transfer
{
  "float": "universal-float",
  "currency": "GBP",
  "amount": 100.00,
  "payment_reference": "OUR_REF"
 }
json
{
  "code": "000",
  "status": "success",
  "message": "Payment transfer request registered",
  "data": {
    "float": "universal-float",
    "currency": "GBP",
    "amount": "100.00",
    "payment_reference": "OUR_REF"
  }
}
{
  "code": "000",
  "status": "success",
  "message": "Payment transfer request registered",
  "data": {
    "float": "universal-float",
    "currency": "GBP",
    "amount": "100.00",
    "payment_reference": "OUR_REF"
  }
}

We offer a proforma invoicing feature if payment transfer invoicing is required. With this feature enabled, a proforma invoice is generated using your registered company details, then emailed to your finance contact. Optionally, the company details and finance email address may be overridden, as in the example request below.

json
POST /api/v2/float/request-payment-transfer
{
  "float": "amazon",
  "currency": "GBP",
  "amount": 100.00,
  "payment_reference": "OUR_REF",
  "proforma_invoice": {
    "company_name": "string",
    "address_line_1": "string",
    "address_line_2": "string",
    "address_line_3": "string",
    "address_line_4": "string",
    "city": "string",
    "post_code": "string",
    "county": "string",
    "country": "string"
  },
  "finance_email": "test@payment.com"
}
POST /api/v2/float/request-payment-transfer
{
  "float": "amazon",
  "currency": "GBP",
  "amount": 100.00,
  "payment_reference": "OUR_REF",
  "proforma_invoice": {
    "company_name": "string",
    "address_line_1": "string",
    "address_line_2": "string",
    "address_line_3": "string",
    "address_line_4": "string",
    "city": "string",
    "post_code": "string",
    "county": "string",
    "country": "string"
  },
  "finance_email": "test@payment.com"
}

Get Transfer Requests ​

Retrieve transfer requests based on various filters including float, currency, payment reference, date range, and status.

All query parameters are optional and can be combined to filter results.

Query Parameters ​

  • float: Specifies the target float (e.g., "universal-float")
  • currency: ISO 4217 currency code (e.g., "GBP")
  • payment_reference: The payment reference (e.g., "BUYER-PROVIDED-REF")
  • start_date: Beginning of the date range in ISO 8601 format (e.g., "2025-10-12")
  • end_date: End of the date range in ISO 8601 format (e.g., "2025-10-16")
  • status: Filter for transfer request state (see status enumeration below)

Status Values ​

  • pending – Transfer request awaiting receipt of payment
  • approved – Request has been approved without modifications
  • approved_edited – Request approved with adjustments to the original amount
  • removed – Buyer-initiated cancellation via the buyer hub
  • cancelled – Administrative cancellation performed by management

Example Request ​

text
GET /api/v2/float/transfer-requests?float=universal-float&currency=GBP&payment_reference=BUYER-PROVIDED-REF&start_date=2025-10-12&end_date=2025-10-16
GET /api/v2/float/transfer-requests?float=universal-float&currency=GBP&payment_reference=BUYER-PROVIDED-REF&start_date=2025-10-12&end_date=2025-10-16

Example Response ​

json
{
  "code": "000",
  "status": "success",
  "data": [
    {
      "float": "universal-float",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": null,
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "pending",
      "created_at": "2025-09-13T16:09:42+00:00"
    },
    {
      "float": "amazon",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "approved",
      "created_at": "2025-09-14T12:09:42+00:00"
    },
    {
      "float": "amazon",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": {
        "currency": "GBP",
        "amount": "310.00"
      },
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "approved_edited",
      "created_at": "2025-09-14T12:09:42+00:00"
    },
    {
      "float": "amazon",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": {
        "currency": "GBP",
        "amount": "310.00"
      },
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "removed",
      "created_at": "2025-09-14T12:09:42+00:00"
    },
    {
      "float": "reward-pass",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": null,
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "cancelled",
      "created_at": "2025-09-14T12:09:42+00:00"
    }
  ]
}
{
  "code": "000",
  "status": "success",
  "data": [
    {
      "float": "universal-float",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": null,
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "pending",
      "created_at": "2025-09-13T16:09:42+00:00"
    },
    {
      "float": "amazon",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "approved",
      "created_at": "2025-09-14T12:09:42+00:00"
    },
    {
      "float": "amazon",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": {
        "currency": "GBP",
        "amount": "310.00"
      },
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "approved_edited",
      "created_at": "2025-09-14T12:09:42+00:00"
    },
    {
      "float": "amazon",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": {
        "currency": "GBP",
        "amount": "310.00"
      },
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "removed",
      "created_at": "2025-09-14T12:09:42+00:00"
    },
    {
      "float": "reward-pass",
      "requested": {
        "currency": "GBP",
        "amount": "321.21"
      },
      "approved": null,
      "payment_reference": "BUYER-PROVIDED-REF",
      "status": "cancelled",
      "created_at": "2025-09-14T12:09:42+00:00"
    }
  ]
}