NAV
curl

Introduction

API Production:

"https://api.telleroo.com"

API Sandbox:

"https://sandbox.telleroo.com"

Welcome to Telleroo API documentation! You can use this API for sending payments out through bank transfers - faster payments in the UK and SEPA in the Eurozone.

Telleroo API is RESTful and JSON. The API enables the use of our web-hooks to retrieve failed and credited transfers.

Feel free to join our developer community on Slack where you can get help with our API. Also, send us an email or give us a call under +44 749 7689 291.

Overview

How does it work?

Here’s an overview of the structure of the API:

API endpoint Description
/accounts Returns unique ID including current available balance in pence/cents (e.g. 100 equals 1 GBP/EUR).
/recipients/{id} Returns (GET) or deletes (DELETE) a single recipient.
/recipients Retrieves (GET) or creates (POST) a single recipient.
/bank_transfers Creates a bank transfer request for a selected account.
/transactions Specify start_date and end_date to get a list of your complete account activity, including credits and all transfers.
/transactions/{id} Retrieves all relevant data of a single transaction including transfer status.

Authentication

Using your login credentials, you can generate unique API key’s required for every API call. Here you can generate or revoke tokens securely on your Telleroo Dashboard:

All API requests are made over HTTPS. To make calls to the API you must add a key named ‘Authorization’ to the HTTP request header containing your Authorization Token. API requests over plain HTTP or without authentication will fail.

API Endpoints

Accounts List

curl "https://api.telleroo.com/accounts" \
  -H Authorization: "your_auth_token" \
  -X GET

The above command returns JSON structured like this:

{
  "accounts": [
    {
      "id": "7e583a6d-0869-4c62-9f2c-74a75b8c2a75",
      "name": "client account",
      "currency": "GBP",
      "balance": 500,
      "account_no": "12345678",
      "sort_code": "123456",
      "tag": "UK Marketplace"
    }
  ]
}

This retrieves all bank accounts assigned to your company including a unique ID to be used to navigate through Telleroo API. Telleroo allows you to add a customized TAG to each account for an improved searching experience.

HTTP request

GET https://api.telleroo.com/accounts

Parameter Type Description
Authorization String Your authorization key.

Recipients List

curl "https://api.telleroo.com/recipients" \
  -H Authorization: "your_auth_token" \
  -d page=1 \
  -X GET

The above command returns JSON structured like this:

{
  "recipients": [
    {
      "id": "ff17b231-2bc4-485e-967e-231867e15fd6",
      "name": "John Archer",
      "currency_code": "GBP",
      "account_no": "12345678",
      "sort_code": "123456",
      "legal_type": "PRIVATE"
    },
    {
      "id": "1fdfef97-95b8-4985-917a-5d9ac9d52d35",
      "name": "António Silva",
      "currency_code": "EUR",
      "iban": "12345678901234567",
      "bic": "12345678901",
      "legal_type": "PRIVATE"
    }
  ]
}

Retrieves all recipients under your company. You can use recipients ID to send bank transfers to.

HTTP request

GET https://api.telleroo.com/recipients

Parameter Type Description
Authorization String Your authorization key.
page Integer Page you want to return. Pagination index starts at 1.

Recipient Creation

curl "http://api.telleroo.com/recipients" \
  -d name="Sam" \
  -d currency_code="GBP" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d legal_type="PRIVATE" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
  "account": {
    "id": "a60f2402-8b7e-4f39-8ddb-d9082b7951ad",
    "name": "Sam",
    "currency_code": "GBP",
    "account_no": "12345678",
    "sort_code": "123456",
    "legal_type": "PRIVATE"
  }
}

HTTP request

POST https://api.telleroo.com/recipients

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
name String The recipient’s full name or business name.
currency_code String The recipient’s account currency code.
account_no String The recipient’s account number.
sort_code String The recipient’s account sort code.
legal_type String If recipient a person should be PRIVATE. If recipient a business should be BUSINESS.

Recipient Deletion

curl "http://api.telleroo.com/recipients" \
  -d id="4314d582-491c-443d-84f4-51324dfb26b5aec" \
  -H Authorization: "your_auth_token" \
  -X DELETE

The above command returns JSON structured like this:

no content

HTTP request

DELETE https://api.telleroo.com/recipients

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
id String The recipient’s unique ID.

Bank Transfers

curl "https://api.telleroo.com/adhoc_bank_transfers" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d332d604" \
  -d amount=100 \
  -d currency_code="GBP" \
  -d recipient_name="Wayne Rooney" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d reference="PayslipDec16" \
  -d tag="Payroll" \
  -d reconciliation="f9q3408rh3" \
  -d idempotent_key="12343" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
  "bank_transfer": {
    "id": "842963c5-e230-42ef-8de8-2b7a459026",
    "processed_at": "2016-12-02T12:15:22.486Z",
    "transaction_type": "Debit",
    "currency_code": "GBP",
    "amount": 100,
    "recipient_id": "14296335-e230-42ef-8de8-2b7a459026",
    "status": "Preparing Payment",
    "status_info": "Creating payment request.",
    "reconciliation": "f9q3408rh3",
    "reference": "PayslipDec16",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "tag": "Payroll",
    "end_balance": 2200,
    "idempotent_key": "12343",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

You can create a bank transfer request from a selected account to any bank account. Depending on the currency assigned to your account this creates a faster payment (GBP) or a SEPA direct credit transfer (EUR).

HTTP request

POST https://api.telleroo.com/adhoc_bank_transfers

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
account_id String The source account’s ID.
amount Integer The amount to be transferred in pence/cents (100 equals 1 GBP/EUR).
currency_code String The currency code used for this transaction. Only transaction requests in the same currency of the originating account are allowed.
recipient_name String The recipient’s full name.
account_no/iban Integer The recipient’s bank account number (8-digits) if account currency is GBP. The recipient’s IBAN (max 34-chars) if account currency is EUR.
sort_code/bic Integer The recipient’s sort code (6-digits) if account currency is GBP. The recipient’s BIC (8-chars or 11-chars) if account currency is EUR.
idempotent_key String Unique key for each transaction.
reference String External payment reference visible to recipient.
tag String Optional field to group payments into custom categories.
reconciliation String Optional field to allow reconciliation with your systems (e.g. User_id).

Bank Transfers to Recipient ID

curl "https://api.telleroo.com/bank_transfers" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d332d604" \
  -d amount=100 \
  -d currency_code="GBP" \
  -d recipient_id="ff17b231-2bc4-485e-967e-231867e15fd6" \
  -d reference="PayslipDec16" \
  -d tag="Payroll" \
  -d reconciliation="f9q3408rh3" \
  -d idempotent_key="2130948" \
  -H Authorization: "your_auth_token" \
  -X POST

The above command returns JSON structured like this:

{
  "bank_transfer": {
    "id": "842963c5-e230-42ef-8de8-2b7a459026",
    "processed_at": "2016-12-02T12:15:22.486Z",
    "transaction_type": "Debit",
    "currency_code": "GBP",
    "amount": 100,
    "recipient_id": "ff17b231-2bc4-485e-967e-231867e15fd6",
    "status": "Preparing Payment",
    "status_info": "Creating payment request",
    "reconciliation": "f9q3408rh3",
    "reference": "PayslipDec16",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "tag": "Payroll",
    "end_balance": 2100,
    "idempotent_key": "2130948",
    "created_at": "2017-3-08T13:15:32.237Z",
    "updated_at": "2017-3-08T13:15:32.237Z"
  }
}

You can create a bank transfer request from a selected account to a recipient account. Depending on the currency assigned to your account this creates a faster payment (GBP) or a SEPA direct credit transfer (EUR).

HTTP request

POST https://api.telleroo.com/bank_transfers

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
account_id String The source account’s Universally Unique Identifier.
amount Integer The amount to be transferred in pence/cents (100 equals 1 GBP/EUR).
currency_code String The currency code used for this transaction. Only transaction requests in the same currency of the originating account are allowed.
recipient_id String The recipient’s Universally Unique Identifier.
reference String External payment reference visible to recipient.
tag String Optional field to group payments into custom categories.
reconciliation String Optional field to allow reconciliation with your systems (e.g. User_id).
idempotent_key String Unique key for each transaction.

Transactions List

curl "https://api.telleroo.com/transactions" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d3d60264" \
  -d start_date="2016-10-02" \
  -d end_date="2016-10-02" \
  -d page=1 \
  -H Authorization: "your_auth_token" \
  -X GET

The above command returns JSON structured like this:

{
  "transactions": [
    {
      "id": "842963c5-e230-42ef-8de8-2b7a459026",
      "processed_at": "2016-12-01T12:15:23.486Z",
      "transaction_type": "Credit",
      "currency_code": "GBP",
      "amount": "1000",
      "recipient_id": null,
      "status": "Credited",
      "status_info": "Funds successfully credited",
      "reconciliation": "3456yujk",
      "reference": "Funding Telleroo",
      "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
      "tag": "Sponsoring",
      "end_balance": 1560,
      "created_at": "2016-12-01T12:15:22.486Z",
      "updated_at": "2016-12-01T12:15:22.486Z"
    },
    {
      "id": "842963c5-e230-42ef-8de8-2b7a459026",
      "processed_at": "2016-12-01T12:15:23.486Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": "100",
      "recipient_id": "122963c5-e230-42ef-8de8-327459026",
      "status": "Preparing Payment",
      "status_info": "Creating payment request",
      "reconciliation": "f9q3408rh3",
      "reference": "Withdrawal Telleroo",
      "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
      "tag": "Manutd",
      "end_balance": 1460,
      "idempotent_key": "6130348",
      "created_at": "2016-12-01T12:15:22.486Z",
      "updated_at": "2016-12-01T12:15:22.486Z"
    }
  ]
}

Specify start_date and end_date to get a list of all transactions including credits and debits for the selected bank account. This also returns failed transfers.

Following we explain all properties on transactions:

Properties Description
id Universally Unique Identifier given back after every transfer request.
processed_at Exact time when transfer has been placed.
transaction_type Shows account has been credited or debited.
currency_code Denominated currency used in the transaction.
amount Transaction amount in pence (100 equals 1 GBP/EUR).
recipient Name of the third party account holder.
account_no/iban Bank account number if account currency is GBP. IBAN if account currency is EUR.
sort_code/bic Sort Code if account currency is GBP. BIC if account currency is EUR.
status Real-time status of the transfer request.
status_info Additional info on payment status including failure reason.
reconciliation Optional parameter that can be used to save custom data (e.g. User_id).
reference External payment reference visible to recipient.
account_id Account Universally Unique Identifier that the transaction is associated with.
tag Optional field that can be used to group payments into custom categories.
end_balance End balance in pence or cents after the value is credited/deducted from the account.
idempotent_key Unique key for each transactions.
created_at Exact time when bank transfer request was created.
updated_at Exact time of the last transfer update.

HTTP request

GET https://api.telleroo.com/transactions

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
account_id String The account’s Universally Unique Identifier.
start_date String Enter starting date (FORMAT: YYYY-MM-DD).
end_date String Enter end date (FORMAT: YYYY-MM-DD).
page Integer Page you want to return. Pagination index starts at 1.

Pagination

curl "https://api.telleroo.com/transactions" \
  -d account_id="ed5af7d2-741c-4905-a3ba-66d3d60264" \
  -d start_date="2016-10-02" \
  -d end_date="2016-10-02" \
  -d page=1 \
  -H Authorization: "your_auth_token" \
  -X GET

Transactions use pagination to return 40 objects per request ordered by processed_at date. Use the page parameter to return each page.

Single Transaction

curl "https://api.telleroo.com/transactions" \
  -d id="842963c5-e230-42ef-8de8-2b7a459026" \
  -H Authorization: "your_auth_token"
  -X GET

The above command returns JSON structured like this:

{
  "transaction": {
    "id": "842963c5-e230-42ef-8de8-2b7a459026",
    "processed_at": "2016-12-01T12:15:23.486Z",
    "transaction_type": "Debit",
    "currency_code": "GBP",
    "amount": 100,
    "recipient_id": "442663c5-e230-32ef-8de8-1b7a459026",
    "status": "Preparing Payment",
    "status_info": "Creating payment request",
    "reconciliation": "f9q3408rh3",
    "reference": "Withdrawal Telleroo",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "tag": "Manutd",
    "end_balance": 2200,
    "idempotent_key": "6130348",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

Retrieves all relevant data of a single transaction including the transfer status.

HTTP request

GET https://api.telleroo.com/transactions

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description
id String The transaction’s Universally Unique Identifier to retrieve the related transaction details.

API versions

If no version is selected, the request will default to our latest version. If you want to use a specific version use, Accept in the header.

curl "https://api.telleroo.com/accounts" \
  -H Authorization: "your_auth_token" \
  -H Accept: "application/vnd.telleroo.v1" \
  -X GET

The API version you choose influences the request parameters format and the JSON responses you get.

When we change the API in a non backwards compatible way, we warn you in advance so that you have time to set the version you want to use until you decide to upgrade.

Idempotent Requests

curl "https://api.telleroo.com/bank_transfers" \
  -d amount=100 \
  -d recipient_name="Payee name" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d idempotent_key="984q3h8f" \
  -d reference="payout rooney" \
  -d tag="manutd" \
  -d reconciliation="9487r2q8hr" \
  -H Authorization: "your_auth_token" \
  -X POST

Telleroo API has built in support for idempotency to avoid repetition of a transfer request. It’s part of the bank transfers body and also mandatory to keep your funds safe. A transfer request will fail if the idempotency key is already in use. You can use any random combination for this field.

{
  "error": {
    "idempotent_key": [
      "has already been taken"
    ]
  }
}

Webhooks

Webhooks are configured on Telleroo dashboard under account settings. Click on Update Webhook URLs to save the entered URLs for receiving notifications through webhooks. Telleroo comes with two webhook types, credits and failed transactions. A POST call to the URL you provided will be made when any of the supported events are triggered.

The urls provided must include the protocol (http|https), a hostname (example.com) and optionally a file name (credit.php).

Valid url example: https://example.com/credit

Invalid url example: example.com/credit

Account Update Webhook

Account Update Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "Account Status Update",
    "status": "initialized",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "currency_code": "GBP",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

At the right column you can see an example of an account update webhook call reaching your defined url.

Credit Notification Webhook

Credit Notification Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "New Credit",
    "transaction_id": "129633c5-a230-32ef-7de8-2b7a459161",
    "processed_at": "2016-12-01T12:18:23.372Z",
    "amount": 100,
    "currency_code": "GBP",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "reference": "Funding Telleroo",
    "end_balance": 2300,
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

At the right column you can see an example of a credit notification webhook call reaching your defined url.

Failed Transaction Webhook

Failed Transaction Notification Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "Failed Payment",
    "transaction_id": "538633c5-d120-45fa-9ee5-1c6a348232",
    "processed_at": "2016-12-01T12:18:23.372Z",
    "amount": 5000,
    "currency_code": "GBP",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "reference": "Withdrawal Telleroo",
    "tag": "",
    "reconciliation": "",
    "status_info": "Transaction failed",
    "end_balance": 2300,
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

At the right column you can see an example of a failed transaction notification webhook call reaching your defined url.

Sent Transaction Webhook

Sent Transaction Notification Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "Sent Payment",
    "transaction_id": "538633c5-d120-45fa-9ee5-1c6a348232",
    "processed_at": "2016-12-01T12:18:23.372Z",
    "amount": 5000,
    "currency_code": "GBP",
    "recipient_id": "638633c5-d120-15fa-9ee5-7c6a348266",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "reference": "Withdrawal Telleroo",
    "end_balance": 2300,
    "idempotent_key": "418633c5-1120-45fa-9ee5-1c6a348232",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

At the right column you can see an example of a sent transaction notification webhook call reaching your defined url.

Transfer Status

Telleroo API has a very clear logic to reflect and communicate the real transfer status at any point in time. All possible transfer status values are independent of HTTP status codes.

Status Meaning Example
Preparing Payment Payment is being prepared to be sent e.g. Further checks on recipient (KYC)
Payment Sent Payment has been sent to recipients bank account. e.g. Recipient should receive payment unless there is a problem on their side.
Waiting for funds Request successfully created but balance is insufficient. Payment will be made as soon as sufficient funding is in the account. e.g. tried to deliver 50 GBP and the available balance is only 45 GBP. After an additional credit of 5 GBP the request goes to Preparing Payment.
Looking into it We’re looking into this payment. e.g. were checking this payment and will notify you if you need to take any action.
Failed Request initially sent but failed while trying to deliver. e.g. wrong account details such as closed bank account or changed details.

Errors

HTTP RESPONSE CODES

The Telleroo API uses conventional HTTP response codes to indicate errors, and includes more detailed information on the exact nature of an error in the HTTP response.

In general, error codes are separated in three different ranges. The 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was missing, etc.), and codes in the 5xx range indicate an error on Telleroo’s end (these are rare).

Code Meaning
200 OK – Request successful.
201 Created – A new resource was succefully created.
400 Bad Request – Your request could not be accepted because it is missing or has invalid parameters.
401 Unauthorized – Your API key is not valid.
403 Forbidden – Your request is authenticated but has insufficient permissions.
404 Not Found – The requested resource or endpoint doesn’t exist.
406 Not Acceptable – Your application doesn’t accept the content format returned according to the headers sent in the request.
429 Too Many Requests – Too many requests hit our API too quickly. We recommend to back off your application requests.
500, 503, 504 Server Errors – Something went wrong on our end. Please try again later.

Authentication errors

Errors related to authentication are standard errors but also contain extra information. Specifically, they contain the error key with the following value:

invalid credentials The supplied auth_token is invalid or has expired.