NAV
shell ruby

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.

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) recipients or creates (POST) a single recipient.
/bank_transfers Creates a bank transfer request to a recipient for a selected account.
/adhoc_bank_transfers Creates a bank transfer request to a adhoc recipient 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.

Transfer Status

When a bank transfer request is made the following statuses apply to your payment request.

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.

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.

Full Access Token

This token allows you full access to all API endpoints. You can also set the approval option:

Transactions Approved - Any bank transfers made will be automatically Approved.

Transaction Approval required - Any bank transfer made will need approve from the Telleroo dashboard.

Recipient Access

This token allows access to recipient endpoint to create, view (censored bank details) and delete recipients.

Accounts

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,
      "awaiting_funds_balance": 640,
      "awaiting_approval_balance": 100,
      "account_no": "12345678",
      "sort_code": "123456",
      "tag": "UK Marketplace"
    }
  ]
}

This retrieves all bank accounts assigned to your company including a unique ID.

HTTP request

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

Parameter Type Description
Authorization String Your authorization key.

Recipients

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 the recipients ID to send bank transfers to.

HTTP request

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

Parameter Type Description Optional
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
page Integer Page you want to return. Pagination index starts at 1. optional

Single Recipient

 

curl "https://api.telleroo.com/recipients/ff17b231-2bc4-485e-967e-231867e15fd6" \
  -H "Authorization: your_auth_token" \
  -X GET

The above command returns JSON structured like this:

{
  "recipient": {
    "id": "ff17b231-2bc4-485e-967e-231867e15fd6",
    "name": "John Archer",
    "currency_code": "GBP",
    "account_no": "12345678",
    "sort_code": "123456",
    "legal_type": "PRIVATE"
  }
}

Retrieves single recipient by id in URL path.

HTTP request

GET https://api.telleroo.com/recipients/{id}

Parameter Type Description
Authorization String Your authorization key.

Accepted PRIVATE names examples

Andrew Cookson
Bu Le
James St Peter Johnson

Rejected PRIVATE names examples

Andrew
B Le
Bu L
Mr James
James j2

Accepted BUSINESS names examples

Tokyo Bikes
Andrew ltd
Andrew Kitchen
Tenbells
Bikes 1

Rejected BUSINESS name examples

Andrew (This would fall into common name category)
Charlie (This would fall into common name category)

If the recipient is an individual, legal_type must be set to PRIVATE. This recipients name must contain at least their first and second name of 2 characters each.

The individual name can only contain letters, hyphens, underscores, curved brackets, single quotes, asterisks, commas and dots eg.

Ben Dreamer

If the recipient is a business, legal_type must be set to BUSINESS. Most business names are accepted - but common names can be flagged and rejected. We ask you include the business type after the name to avoid this from happening eg.

Micheal Ltd

Recipient Creation

 

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins",
                currency_code: "GBP",
                account_no: "12345678",
                sort_code: "123456",
                legal_type: "PRIVATE"
              }

The above command returns JSON structured like this:

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

All bank details added will be validated in both sandbox and production.

Valid sort code and Account Numbers

account_no: 22345678 , 12345678 , 2345678 , 42345678 , 52345678

sort_code: 123456

HTTP request

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

Parameter Type Description
Authorization String Your authorization key.

General parameters

Parameter Type Description Optional
name String Name validations are dependant on legal_type selected. Find detailed information here.
currency_code String The recipient's account currency code.
legal_type String If recipient a person should be PRIVATE. If recipient a business should be BUSINESS.

UK recipient parameters

Parameter Type Description
account_no String The recipient's account number.
sort_code String The recipient's account sort code.

Euro recipient parameters

Parameter Type Description
iban String The recipient's IBAN.
bic String The recipient's BIC.

Recipient Validation Errors

When PRIVATE recipient name only has first name

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
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam",
                currency_code: "GBP",
                account_no: "12345678",
                sort_code: "123456",
                legal_type: "PRIVATE"
              }
{
    "error": {
        "name": [
            "must contain full name of recipient. If you are sending to a business, please use \"business\" legal type"
        ]
    }
}

When PRIVATE recipient contains a special character that's not allowed

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins!" \
  -d currency_code="GBP" \
  -d account_no="123a" \
  -d sort_code="123a" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins!",
                currency_code: "GBP",
                account_no: "123a",
                sort_code: "123a",
                legal_type: "PRIVATE"
              }
{
    "error": {
        "name": [
            "can only contain letters, hyphens, underscores, curved brackets, single quotes, asterisks, commas and dots"
        ]
    }
}

When PRIVATE recipient contains 1 letter for each word

curl "http://api.telleroo.com/recipients" \
  -d name="S J" \
  -d currency_code="GBP" \
  -d account_no="123a" \
  -d sort_code="123a" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "S J",
                currency_code: "GBP",
                account_no: "123a",
                sort_code: "123a",
                legal_type: "PRIVATE"
              }
{
    "error": {
        "name": [
            "words must be at least 2 letters long"
        ]
    }
}

When a sort code and account number format and length incorrect

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="123a" \
  -d sort_code="123a" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins",
                currency_code: "GBP",
                account_no: "123a",
                sort_code: "123a",
                legal_type: "PRIVATE"
              }
{
  "error": {
    "account_no": [
      "is not a number",
      "is the wrong length (should be 8 characters)"
    ],
    "sort_code": [
      "is not a number",
      "is the wrong length (should be 6 characters)"
    ]
  }
}

When a sort code is not valid

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="12345678" \
  -d sort_code="112233" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins",
                currency_code: "GBP",
                account_no: "12345678",
                sort_code: "112233",
                legal_type: "PRIVATE"
              }
{
  "error": {
    "sort_code": [
      "could not be validated (please enter a valid sort code)"
    ]
  }
}

When a account number and sort code do not match

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="GBP" \
  -d account_no="11223344" \
  -d sort_code="112233" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins",
                currency_code: "GBP",
                account_no: "11223344",
                sort_code: "112233",
                legal_type: "PRIVATE"
              }
{
  "error": {
    "base": [
      "account number and sort code do not match"
    ]
  }
}

When a IBAN and BIC length incorrect

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="EUR" \
  -d iban="123a" \
  -d bic="123a" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins",
                currency_code: "EUR",
                iban: "123a",
                bic: "123a",
                legal_type: "PRIVATE"
              }
{
  "error": {
    "iban": [
      "is too short (minimum is 15 characters)"
    ],
    "bic": [
      "length must be 8 or 11"
    ]
  }
}

When a IBAN is not valid

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="EUR" \
  -d iban="111222333444555" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins",
                currency_code: "EUR",
                iban: "111222333444555",
                legal_type: "PRIVATE"
              }
{
  "error": {
    "iban": [
      "Please enter valid IBAN number"
    ]
  }
}

When a IBAN and BIC do not match

curl "http://api.telleroo.com/recipients" \
  -d name="Sam Jenkins" \
  -d currency_code="EUR" \
  -d iban="111222333444555" \
  -d bic="12345678" \
  -d legal_type="PRIVATE" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/recipients',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                name: "Sam Jenkins",
                currency_code: "EUR",
                iban: "111222333444555",
                bic: "12345678",
                legal_type: "PRIVATE"
              }
{
  "error": {
    "iban": [
      "This IBAN is for the wrong country"
    ]
  }
}

When a recipient bank details are not valid we return the following errors. You can trigger these errors in sandbox using the details below:

Invalid sort code

sort_code: 223344

Account Number and Sort code do not match

account_no: 11111111

sort_code: 522127

Invalid IBAN

iban: 111222333444555

Recipient Deletion

 

curl "http://api.telleroo.com/recipients/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/{id}

Parameter Type Description
Authorization String Your authorization key.

Url parameters

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

Transactions

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 status="preparing_payment" \
  -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:20:23.486Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": "100",
      "sender_name": "Daryl Oates",
      "status": "Preparing Payment",
      "status_info": "Creating payment request",
      "reconciliation": "3456yujk",
      "reference": "Funding Telleroo",
      "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
      "tag": "Sponsoring",
      "end_balance": 800,
      "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": 900,
      "idempotent_key": "6130348",
      "created_at": "2016-12-01T12:15:22.486Z",
      "updated_at": "2016-12-01T12:15:22.486Z"
    },
    {
      "id": "9ac76bb4-feed-5f75-b403-c1e9eed9e0c7",
      "processed_at": "2016-11-22T11:22:17.547272Z",
      "transaction_type": "Credit",
      "currency_code": "GBP",
      "amount": 1000,
      "sender_name": "John Walker",
      "sender_account_no": 12345678,
      "sender_sort_code": 123467,
      "status": "Credit",
      "status_info": "Funds successfully credited",
      "reconciliation": nil,
      "reference": nil,
      "account_id": "3ec81072-6860-531c-ba41-867ef1ea3eea",
      "tag": nil,
      "end_balance": 1000,
      "idempotent_key": nil,
      "created_at": "2020-08-06T16:11:38Z",
      "updated_at": "2020-08-06T16:11:38Z"
    }
  ]
}

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.

HTTP request

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

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
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).
status String Filter by payment statuses. Find status keys in table below. optional
page Integer Page you want to return. Pagination index starts at 1. optional

Status Filter Keys

Status Key to Use
Payment Sent payment_sent
Preparing Payment preparing_payment
On Hold on_hold
Waiting for approval waiting_for_approval
Waiting for funds waiting_for_funds
Looking into it looking_into_it
Credit credited
Failed failed
Cancelled cancelled

Response Properties

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_id Third party account holder Universally Unique Identifier if a transaction is a debit.
sender_name Name of the sender if transaction is a credit.
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.

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/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 a single transaction including the transfer status.

HTTP request

GET https://api.telleroo.com/transactions/{id}

Parameter Type Description
Authorization String Your authorization key.

URL parameters

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

Bank Transfers

Bank Transfer

 

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 legal_type="BUSINESS" \
  -d tag="Payroll" \
  -d reconciliation="f9q3408rh3" \
  -d idempotent_key="12343" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/adhoc_bank_transfers',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                account_id: 'ed5af7d2-741c-4905-a3ba-66d332d604',
                amount: 100,
                currency_code: 'GBP',
                recipient_name: 'Wayne Rooney',
                account_no: '12345678',
                sort_code: '123456',
                reference: 'PayslipDec16',
                legal_type: 'Business',
                tag: 'Payroll',
                reconciliation: 'f9q3408rh3',
                idempotent_key: '12343'
              }

The above command returns JSON structured like this:

{
  "transaction": {
    "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 Optional
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 Name validations are dependant on legal_type selected. Find detailed information here.
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.
legal_type String If recipient a person should be PRIVATE. If recipient a business should be BUSINESS.
idempotent_key String Unique key for each transaction. optional
reference String External payment reference visible to recipient. optional
tag String Optional field to group payments into custom categories. optional
reconciliation String Optional field to allow reconciliation with your systems (e.g. User_id). optional

Bank Transfer 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
require 'httparty'
HTTParty.post 'https://api.telleroo.com/bank_transfers',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                account_id: "ed5af7d2-741c-4905-a3ba-66d332d604",
                amount: 100,
                currency_code: "GBP",
                recipient_id: "ff17b231-2bc4-485e-967e-231867e15fd6",
                reference: "PayslipDec16",
                tag: "Payroll",
                reconciliation: "f9q3408rh3",
                idempotent_key: "2130948"
              }

The above command returns JSON structured like this:

{
  "transaction": {
    "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 Optional
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. optional
tag String Optional field to group payments into custom categories. optional
reconciliation String Optional field to allow reconciliation with your systems (e.g. User_id). optional
idempotent_key String Unique key for each transaction. optional

Bank Transfer Cancelling

 

curl "http://api.telleroo.com/bank_transfers/842963c5-e230-42ef-8de8-2b7a459026" \
  -H "Authorization: your_auth_token" \
  -X DELETE

The above command returns JSON structured like this:

no content

HTTP request

DELETE https://api.telleroo.com/bank_transfers/{id}

Parameter Type Description
Authorization String Your authorization key.

Url parameters

Parameter Type Description
id String The bank transfer's unique ID.

Idempotent Key

When a idempotent key is reused on a different bank transfer

curl "https://api.telleroo.com/bank_transfers" \
  -d recipient_name="Cris Ron" \
  -d account_no="12345678" \
  -d sort_code="123456" \
  -d amount=100 \
  -d reference="payout ronaldo" \
  -d idempotent_key="trx-984q3h8f" \
  -H "Authorization: your_auth_token" \
  -X POST
require 'httparty'
HTTParty.post 'https://api.telleroo.com/bank_transfers',
              headers: {
                authorization: "your_auth_token"
              },
              query: {
                recipient_name: "Cris Ron",
                account_no: "12345678",
                sort_code: "123456",
                amount: 100,
                reference: "payout ronaldo",
                idempotent_key: "trx-984q3h8f",
              }

The above command returns a JSON structured like this:

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

To avoid incorrect duplication of bank transfers, we use the idempotent key.

If the same idempotent key gets used twice we will always return the same original response body content but instead of 200 OK you will get a 409 CONFLICT http status code.

Sandbox API Endpoints

Endpoints that are only available on sandbox.

Send Bank Transfer

curl "https://api.telleroo.com/transaction_send" \
  -H "Authorization: your_auth_token" \
  -d id="b58584f7-7924-4022-bbb5-9ab3cb36ae3b" \
  -X POST

The above command returns JSON structured like this:

{
  "transaction": {
      "id": "b58584f7-7924-4022-bbb5-9ab3cb36ae3b",
      "processed_at": "2018-06-14T14:37:28Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": 100,
      "recipient_id": "b577ebe2-b3ca-48cd-8a74-b36359ad1883",
      "status": "Payment Sent",
      "status_info": "Your payment has been sent to the recipients bank",
      "reconciliation": null,
      "reference": null,
      "account_id": "15fa5095-d3cb-4df5-b5ac-87f14c4a4327",
      "tag": null,
      "end_balance": 4325596,
      "idempotent_key": null,
      "created_at": "2018-06-14T14:37:28Z",
      "updated_at": "2018-06-14T14:37:38Z"
  }
}

This endpoint allows you to move a transaction from preparing payment to sent on sandbox.

HTTP request

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

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
id String Transaction Id

Fail Bank Transfer

curl "https://api.telleroo.com/transaction_fail" \
  -H "Authorization: your_auth_token" \
  -d id="b58584f7-7924-4022-bbb5-9ab3cb36ae3b" \
  -X POST

The above command returns JSON structured like this:

{
  "transaction": {
      "id": "b58584f7-7924-4022-bbb5-9ab3cb36ae3b",
      "processed_at": "2018-06-14T14:37:28Z",
      "transaction_type": "Debit",
      "currency_code": "GBP",
      "amount": 100,
      "recipient_id": "bf57ebe2-b3ca-48cd-8a74-b36359ad1883",
      "status": "Failed",
      "status_info": "Transaction failed",
      "reconciliation": null,
      "reference": null,
      "account_id": "15fa5095-d3cb-4df5-b5ac-87f14c4a4327",
      "tag": null,
      "end_balance": null,
      "idempotent_key": null,
      "created_at": "2018-06-14T14:37:28Z",
      "updated_at": "2018-06-14T14:38:50Z"
  }
}

This endpoint allows you to move a transaction from payment sent to failed on sandbox.

HTTP request

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

Header

Parameter Type Description
Authorization String Your authorization key.

Query parameters

Parameter Type Description Optional
id String Transaction Id

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.

Webhooks

Webhooks are configured on Telleroo dashboard under API webhooks. Click on Update Webhook URLs to save the entered URLs for receiving notifications through webhooks. Telleroo comes with three webhook types, sent, 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

Webhook Authenticity Token

In the header of the webhook post you will find your webhook authenticity token:

  "Authenticity-Token":"YOUR-WEBHOOK-TOKEN-HERE"

Your webhook authenticity token is chosen by you, so you can identify that the webhook post is coming from Telleroo by looking at the header.

Webhooks authenticity tokens are configured on Telleroo dashboard under API webhooks.

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",
    "sender_name": "Daryl Oates",
    "sender_account_no": "12345678",
    "sender_sort_code": "123456",
    "reference": "Funding Telleroo",
    "end_balance": 2300,
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

When a credit is received, we will post details to your defined URL.

e.g. When you topup your account, funds arrive trigging the webhook.

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",
    "recipient_id": "638633c5-d120-15fa-9ee5-7c6a348266",
    "account_id": "ed5af7d2-741c-4905-a3ba-66d332d604",
    "reference": "Withdrawal Telleroo",
    "tag": "payroll",
    "reconciliation": "f9q3408rh3",
    "end_balance": 2300,
    "idempotent_key": "2130948",
    "status_info": "Transaction failed",
    "created_at": "2016-12-02T12:15:22.486Z",
    "updated_at": "2016-12-02T12:15:22.486Z"
  }
}

When a payment fails, we will post details to your defined URL.

e.g. A sent payment bounces back, triggering the webhook.

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",
    "tag": "payroll",
    "reconciliation": "f9q3408rh3",
    "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"
  }
}

When a payment is sent, we will post details to your defined URL.

e.g. A payment is sent from the account, triggering the webhook.

Company Approved Webhook

Company Approved Webhook returns JSON structured like this:

{
  "webhook": {
    "type": "Company Approved",
    "company_id": "538633c5-d120-45fa-9ee5-1c6a348232",
    "company_name": "Test Company One"
  }
}

This webhook is only available if you have the create company endpoint unlocked

When a company has been approved by our compliance team and is ready to use, the webhook will be sent.

e.g. A requested company is been approved and is ready to use.

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.
204 No content -- When deletion successful no content returned.
422 Unprocessable entity -- Your request could not be accepted as invalid parameters used.
404 Not Found -- The requested resource or endpoint doesn't exist.
409 Conflict -- When you have already created this resource with the same idempotent key.
429 Too Many Requests -- Too many requests hit our API too quickly. We recommend to reducing the number of requests sent.
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.