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.

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.

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.

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 the 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 Jenkins" \
  -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 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
name String The recipient’s full name or business name.
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.

USD recipient parameters

Parameter Type Description
account_no String The recipient’s account number.
routing_number String The recipient’s routing number.
state String The recipient’s state.
city String The recipient’s city.
first_line String The recipient’s first line of address.
postcode String The recipient’s zipcode.
account_type String The recipient account type (SAVINGS or CHECKING)

Recipient Validation Errors

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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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
{
  "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.

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:

{
  "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
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 or USD. 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.
routing_number String Routing number for USD transfers.
state String State of recipient for USD.
city String City of recipient for USD.
first_line String first line of address for USD.
postcode String zipcode of address for USD.
account_type String CHECKING or SAVINGS for USD.
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:

{
  "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
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.

Bank Transfer Idempotent Key

When a idempotent key is reused on a different bank transfer

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

When you try and recreate a identical bank transfer with the same idempotent key, we will return a conflict status with the bank transfer.

If you try to reuse a idempotent key with a new bank transfer it will return an error.

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

Transaction Approval Request

Requesting approval for transaction created before a certain date

curl "https://api.telleroo.com/approval_requests" \
  -d type='transaction'
  -d end_time=2017-10-30T18%3A57%3A34 \
  -H Authorization: "your_auth_token" \
  -X POST

Only required if token used requires transactions to be approved

Sending a transaction approval request will SMS all users who are allowed to approve transactions a code.

When requested it will return all transactions you’ve requested to approve.

{
    "transaction_approval": {
        "id": "5e03d7e5-0b37-4648-8c01-3f658bfcdc3c",
        "status": "requested",
        "end_time": "2017-10-30T18:57:34Z",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T16:59:59Z",
        "transactions": [
            {
                "id": "ca12635e-3c33-421b-ad80-86923fb0cf5c",
                "amount": 10
            },
            {
                "id": "9f2ef1a4-49f8-4d70-98ab-f6c2b4d3a31f",
                "amount": 129
            },
            {
                "id": "eeae9b3a-d772-4add-b573-6588eb9becb0",
                "amount": 5000
            },
            {
                "id": "29808cfc-a70e-49bc-bff0-0f3fccc7bc43",
                "amount": 9
            }
        ]
    }
}

Single Transaction Approval Request

Returns a single transaction request approval

curl "https://api.telleroo.com/approval_requests/5e03d7e5-0b37-4648-8c01-3f658bfcdc3c" \
  -H Authorization: "your_auth_token" \
  -X GET

Get a single transaction approval request.

{
    "transaction_approval": {
        "id": "5e03d7e5-0b37-4648-8c01-3f658bfcdc3c",
        "status": "requested",
        "end_time": "2017-10-30T18:57:34Z",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T16:59:59Z",
        "transactions": [
            {
                "id": "ca12635e-3c33-421b-ad80-86923fb0cf5c",
                "amount": 10
            },
            {
                "id": "9f2ef1a4-49f8-4d70-98ab-f6c2b4d3a31f",
                "amount": 129
            },
            {
                "id": "eeae9b3a-d772-4add-b573-6588eb9becb0",
                "amount": 5000
            },
            {
                "id": "29808cfc-a70e-49bc-bff0-0f3fccc7bc43",
                "amount": 9
            }
        ]
    }
}

Transaction Approval Response

Sending approval code with approval ID

curl "https://api.telleroo.com/approval_responses" \
  -d id=5e03d7e5-0b37-4648-8c01-3f658bfcdc3c \
  -d code=123456 \
  -H Authorization: "your_auth_token" \
  -X POST

To approve the requested transactions we expect you to enter the code sent by SMS and the approval ID.

You are only allowed to try three different codes before the approval request is rejected.

{
    "transaction_approval": {
        "id": "5e03d7e5-0b37-4648-8c01-3f658bfcdc3c",
        "status": "approved",
        "end_time": "2017-10-30T18:57:34Z",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T17:06:45Z",
        "transactions": [
            {
                "id": "ca12635e-3c33-421b-ad80-86923fb0cf5c",
                "amount": 10
            },
            {
                "id": "9f2ef1a4-49f8-4d70-98ab-f6c2b4d3a31f",
                "amount": 129
            },
            {
                "id": "eeae9b3a-d772-4add-b573-6588eb9becb0",
                "amount": 5000
            },
            {
                "id": "29808cfc-a70e-49bc-bff0-0f3fccc7bc43",
                "amount": 9
            }
        ]
    }
}

Create User

Create a user to approve transactions

curl "https://api.telleroo.com/users" \
  -d email='sam@test.com'
  -d phone_number_country_code=44 \
  -d phone_number=75473829403 \
  -d password='Str0ng_pa**w0d' \
  -H Authorization: "your_auth_token" \
  -X POST

If you would like authorization to use this endpoint, please get in contact with us

Creates a unapproved user who will receive SMS’s when a transaction approval request is created.

{
    "user": {
        "id": "b357b7fe-2ea5-49a7-828c-76a0850d771d",
        "email": "sam@test.com",
        "status": "initialized"
    }
}

Single User

Returns a single User

curl "https://api.telleroo.com/users/b357b7fe-2ea5-49a7-828c-76a0850d771d" \
  -H Authorization: "your_auth_token" \
  -X GET

If you would like authorization to use this endpoint, please get in contact with us

Get a single transaction approval request.

The above command returns JSON structured like this:

{
    "user": {
        "id": "b357b7fe-2ea5-49a7-828c-76a0850d771d",
        "email": "sam@test.com",
        "status": "initialized"
    }
}

User list

Returns all users

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

If you would like authorization to use this endpoint, please get in contact with us

Get all users and there current status.

The above command returns JSON structured like this:

{
    "users": [
        {
            "id": "b357b7fe-2ea5-49a7-828c-76a0850d771d",
            "email": "sam@test.com",
            "status": "initialized"
        },
        {
            "id": "2a5ac05a-4d76-4824-a5c4-40be37fb2430",
            "email": "ben@test.com",
            "status": "approved"
        }
    ]
}

User Deletion

curl "http://api.telleroo.com/users/b357b7fe-2ea5-49a7-828c-76a0850d771d" \
  -H Authorization: "your_auth_token" \
  -X DELETE

If you would like authorization to use this endpoint, please get in contact with us

Deletes a user.

The above command returns JSON structured like this:

no content

User Approval Request

Requesting approval for user

curl "https://api.telleroo.com/approval_requests" \
  -d type='user'
  -d id=2a5ac05a-4d76-4824-a5c4-40be37fb2430 \
  -H Authorization: "your_auth_token" \
  -X POST

Sending a user approval request will SMS all users who are allowed to approve users a code.

When requested it will return the user you’ve requested to approve.

  {
      "user_approval": {
          "id": "2a5ac05a-4d76-4824-a5c4-40be37fb2430",
          "status": "requested",
          "end_time": "null",
          "created_at": "2017-10-30T16:59:59Z",
          "updated_at": "2017-10-30T16:59:59Z"
      }
  }

Single User Approval Request

Returns a single User request approval

curl "https://api.telleroo.com/approval_requests/e1042121-c25a-41b5-9181-db30c4d7957d" \
  -H Authorization: "your_auth_token" \
  -X GET

Get a single transaction approval request.

{
    "user_approval": {
        "id": "e1042121-c25a-41b5-9181-db30c4d7957d",
        "status": "requested",
        "end_time": "null",
        "created_at": "2017-10-30T16:59:59Z",
        "updated_at": "2017-10-30T16:59:59Z"
    }
}

User Approval Response

Sending approval code with approval ID

curl "https://api.telleroo.com/approval_responses" \
  -d id=2a5ac05a-4d76-4824-a5c4-40be37fb2430 \
  -d code=123456 \
  -H Authorization: "your_auth_token" \
  -X POST

To approve the requested user we expect you to enter the code sent by SMS and the approval ID.

You are only allowed to try three different codes before the approval request is rejected.

{
    "user_approval": {
        "id": "2a5ac05a-4d76-4824-a5c4-40be37fb2430",
        "status": "approved",
        "end_time": null,
        "created_at": "2017-11-14T12:01:25Z",
        "updated_at": "2017-11-14T12:07:53Z"
    }
}

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/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.

Create Company

curl "https://api.telleroo.com/companies" \
-H Authorization="your_auth_token" \
-H content-type="application/json" \
-d first_name="Andrew" \
-d last_name="Thompson" \
-d email="andrew@test.com"
-d company_name="Test Company" \
-d company_type="ltd" \
-d companies_house_number=1234234 \
-d sector="Testing" \
-d business_address="11 London Road, London, E1 LON" \
-d gbp_account=true \
-d eur_account=true \
-d sent_webhook_url="https://webhook.test/test" \
-d error_webhook_url="https://webhook.test/test" \
-d credit_webhook_url="https://webhook.test/test" \
-d token_name="Rspec Token" \
-d webhook_token="Telleroo-test-123" \
-d users:
  {
    email='user_one@test.com' \
    phone_number_country_code=44 \
    phone_number=712345678 \
  }
-d shareholders:
  [
    {
      name="Andrew Benson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
      identity='https://www.example.com/passport.jpg' \
    },
    {
      name="Ben Andreson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
    }
  ],
-d directors:
  [
    {
      name="Andrew Benson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
    },
    {
      name="Ben Andreson" \
      dob="12/06/1991" \
      residence="United Kingdom" \
    }
  ]
  -X POST

If you would like authorization to use this endpoint, please get in contact with us

The above command returns JSON structured like this:

{
  "company": {
    "id": "7ab52fce-93d4-469b-b949-a54265bc8350",
    "name": "Migeroo",
    "email": "admin-miguel@telleroo.com",
    "settings": {
      "sent_webhook_url": "https://requestb.in/xae3j8xa",
      "error_webhook_url": "https://requestb.in/xae3j8xa",
      "credit_webhook_url": "https://requestb.in/xae3j8xa",
      "webhook_token": "Telleroo-test-123"
    },
    "tokens": [
      {
        "name": "Rspec Token",
        "value": "Token-here"
      }
    ]
  }
}

If your interested in this endpoint please get in contact with us to unlock

Setup company for verification.

HTTP request

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

Parameter Type Description
Authorization String Your authorization key.

Main parameters

Parameter Type Description
first_name String First name of Main User
last_name String Last name of Main User
email String Email address of Main User
company_name String Name of company
company_type String Company type eg. Ltd
companies_house_number String Company type eg. Ltd
sector String Company sector e.g catering
business_address String Company registered address
gbp_account Boolean Setup GBP account
eur_account Boolean Setup EUR account
sent_webhook_url String URL of sent webhook
error_webhook_url String URL of error webhook
credit_webhook_url String URL of credit webhook
token_name String Name of Auth token
webhook_token String More info here

User parameters

Admin user for account.

Parameter Type Description
email String Admin user email
phone_number_country_code String Country code of phone (44 or 1)
phone_number String Phone number of admin user

Shareholders parameters

Information for shareholders who own more than 25% of the company.

Must provide passport copy of one shareholder

Parameter Type Description
name String Full name
dob String Date of Birth (DD/MM/YYYY)
residence String City of residence
identity String URL to driving licence or passport

Director parameters

Information for directors who own more than 25% of the company.

Parameter Type Description
name String Full name
dob String Date of Birth (DD/MM/YYYY)
residence String City of residence

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 webhook settings. 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-WEHOOK-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 webhook settings.

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"
  }
}

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",
    "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"
  }
}

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",
    "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 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.