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
Header
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
Header
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}
Header
Parameter | Type | Description |
---|---|---|
Authorization | String | Your authorization key. |
Recipient Legal Type Validations
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)
PRIVATE legal Type
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
BUSINESS legal Type
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
Header
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}
Header
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
Header
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}
Header
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
Header
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
Header
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}
Header
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
Header
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.