📗

INTEGRATOR GUIDE

Introduction

With an active Consent in place, an Account Holder (or more specifically, a Third Party Provider on their behalf) can perform the actions related to that Consent. For example, if the Consent was for Account Access, they can start to retrieve balances, transaction lists etc, or if the Consent was for a payment, they can request execution of that payment.

tell.gateway performs validation of the Consent and the third party provider, after which we call the API URL you have configured to return the relevant information or complete the action. You will need to expose an API endpoint that can consume our request, perform the relevant action, and return a response.

❗️

All requests from are sent via POST to a single URL endpoint per Gateway, containing details of the type of request and any relevant data in a JSON-formatted body. You do not need to implement different resource endpoints for each operation.

For example, if you have provided an API URL of

https://your-bank.com/tell-gateway-api

then all requests to your system will hit that endpoint, and the details of the type of operation are contained in the payload, not the URL.

Set your API URL within the Console by navigating to your Gateway, selecting the environment (Production or Integration) and entering it under YOUR API URI.

🔧

Integrator Note:

You can use a different URL for each Gateway (e.g. yoururl.com/client1, yoururl.com/client2) as a means of separating and identifying the Gateway application.

Or you can use a single URL for all Gateways (e.g. yoururl.com) and rely on the contents of the API request from tell.money (x-api-key) to identify the Gateway.


Sample Request & Response

The anatomy of a request and response is described in detail in the sections below, but for now, here is an example of what the end result will look like.

Sample Request from tell.gateway

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json
{
  "Info": {
    "Operation": "GET /balance",
    "RqId": "22a70d29-08d5-491c-942f-fb3a3a4ad6d1",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
    "AccountId": "10000001"
  }
}

Sample Response from account provider

{
  "Amount": "17.00",
  "Currency": "GBP",
  "CreditDebit": "Credit"
}

Request Format

Requests from tell.gateway include an API KEY and a SIGNED JWT in the Header, and a JSON body containing INFO (information about the request) and DATA (specifics of the request itself).

❯ Headers

Security Headers allow you to verify requests have come from tell.gateway and have not been tampered with in transit.

API Key

To view your API Key within the Management Console, navigate to your Gateway, select the environment (Production or Integration), and click the tab titled Calling Your APIs.

--header 'x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

SIGNED JWT

A JWT is formed of a header, a payload (which is the same as the main request payload) and is signed with our Private Key using the RS256 algorithm.

You should verify the signature using our Public Key. To view the relevant Public Key within the Management Console, navigate to your Gateway, select the environment (Production or Integration), and click the tab titled Calling Your APIs.

--header 'x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx'

❯ Body

Request payloads consist of a JSON body with two objects; Info and Data

Info

The Info object provides high-level information about the request.

FieldDescription
OperationName of the operation being requested
RqIdA UUID generated by tell.gateway to identify an individual request
ConsentIdThe Consent ID allocated by tell.gateway when the consent was created and used in the initial authorisation process
UserIdThe account holder identifier provided by your application when the consent was granted
TppAn object containing information about the third party provider making the request campaign. This object contains two elements:

- TppName
- AppName
"Info": {
  "Operation": "GET /balance",
  "RqId": "22a70d29-08d5-491c-942f-fb3a3a4ad6d1",
  "UserId": "106726572",
  "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
  "Tpp": {
    "TppName": "Tell Money",
    "AppName": "My Sandbox App"
  }
}

Data

The Data object is specific to the type of operation being requested and may contain user or event-related information. The structure for each Operation is outlined below.

  "Data": {
    "AccountId": "10000001"
  }

Response Format

Having received and processed a Request from tell.gateway (including performing security checks on the header elements), you should construct and return a response as described below.

❯ HTTP Status Code

Your response should use one of the following http status codes:

Status CodeUsageBody Required
200For all successfully processed requestsYes – as described in this documentation
400If you are unable to fulfil the request for reasons other than a technical fault (e.g. if an account is closed) then you should return 400. These responses must be accompanied by a JSON Object describing the “Error”, which we will pass back to the third party provider.Yes, in the format:

{
"Error": "account inactive"
}
404If the resource cannot be found return 404. No response body is required.No
500For any system-related errors. Where possible, the response should be accompanied by a JSON Object describing the “Error”, although this isn’t mandatory. The error body will be logged for reporting and bug checking purposes but will not be returned to the third party provider.Optional

❯ Body

Expect where indicated above (in the case of 404 or 500 status codes), you should always return a well-formed JSON object in the body of your response.

The contents of the response body will differ depending on the type of Operation and are described below.


Operations

Depending on the APIs and endpoints you have enabled for your Gateway, there are twelve potential Operations that may be presented to your application.

OperationAPIDescription
GET /accountsAISPRequests a list of accounts associated with a consent
GET /accountAISPRequests details of an account associated with a consent
GET /balanceAISPRequests the balance of an account associated with a consent
GET /transactionsAISPRequests a list of transactions for an account associated with a consent
GET /beneficiariesAISPRequests a list of beneficiaries for an account associated with a consent
GET /direct-debitsAISPRequests a list of direct debits for an account associated with a consent
GET /scheduled-paymentsAISPRequests a list of scheduled payments for an account associated with a consent
GET /standing-ordersAISPRequests a list of standing orders for an account associated with a consent
GET /statementsAISPRequests a list of statements for an account associated with a consent
GET /payment-funds-confirmationPISPRequests confirmation funds are available for a payment that has been consented to
POST /paymentPISPRequests execution of a payment that has been previously consented to by the User
GET /paymentPISPRequests status of a payment that has been submitted for execution
POST /funds-confirmationCBPIIRequests confirmation of funds

❯ GET /accounts

An AISP requests the full list of accounts that the account holder has authorised at the Consent stage.

Request

The request Data object will be empty for this Operation.

Response

tell.gateway automatically filters out any accounts that have not been consented to, so you may choose to simply return all accounts for the given user. tell.gateway also filters the response details based on the type of permissions consented to, so you should ensure that the full data set is returned on all occasions.

FieldDescriptionMandatoryOptions
AccountsAn array of AccountsYes
Accounts/AccountIdA unique identifier for the account (may be system-issued, not known to the account holder)Yes
Accounts/CurrencyAccount currency in ISO 4217 three-letter code formatYes
Accounts/AccountTypeType of accountYesPersonal
Business
Accounts/AccountSubTypeThe sub type of accountYesChargeCard
CreditCard
CurrentAccount
EMoney
Loan
Mortgage
PrePaidCard
Savings
Accounts/NicknameThe nickname of the accountNo
Accounts/SchemeNameIf using an 8-digit numeric account number and 6-digit sort-code, return SortCodeAccountNumber.

If using IBAN, return IBAN.

If using BBAN, return BBAN.

If using MSISDN, return MSISDN.

Otherwise use CustomCode.
YesOBIE:

- SortCodeAccountNumber

- IBAN

- CustomCodeNextGenPSD2:

- IBAN

- BBAN

- MSISDN
Accounts/IdentificationIf SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number.
If using CustomCode, provide the Identifier as known to your account holder.
Yes

GET Accounts Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /accounts",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {}
}

GET Accounts Response

{
  "Accounts": [
    {
      "AccountId": "10000001",
      "Currency": "GBP",
      "AccountType": "Personal",
      "AccountSubType": "CurrentAccount",
      "Nickname": "General Account",
      "Identification": "00000010000001",
      "SchemeName": "SortCodeAccountNumber"
    },
    {
      "AccountId": "10000002",
      "Currency": "GBP",
      "AccountType": "Personal",
      "AccountSubType": "CurrentAccount",
      "Nickname": "Main Account",
      "Identification": "1234ACC666-01",
      "SchemeName": "CustomCode"
    }
  ]
}

❯ GET /account

An AISP requests details of a specified account.

Request

FieldDescription
AccountIdA unique identifier for the account being requested

Response

tell.gateway filters the response based on the type of permissions consented to, so you should ensure that the full data set is returned.

FieldDescriptionMandatoryOptions
CurrencyAccount currency in ISO 4217 three-letter code formatYes
AccountTypeType of accountYesPersonal
Business
AccountSubTypeThe sub type of accountYesChargeCard
CreditCard
CurrentAccount
EMoney
Loan
Mortgage
PrePaidCard
Savings
NicknameThe nickname of the accountNo
SchemeNameIf using an 8-digit numeric account number and 6-digit sort-code, return SortCodeAccountNumber.

If using IBAN, return IBAN.

If using BBAN, return BBAN.

If using MSISDN, return MSISDN

Otherwise use CustomCode.
YesOBIE:

- SortCodeAccountNumber

- IBAN

- CustomCodeNextGenPSD2:

- IBAN

- BBAN

- MSISDN
IdentificationIf SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number.
If using CustomCode, provide the Identifier as known to your account holder.
Yes

GET Account Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /account",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001"
  }
}

GET Account Response

{
  "Currency": "GBP",
  "AccountType": "Personal",
  "AccountSubType": "CurrentAccount",
  "Nickname": "General Account",
  "Identification": "00000010000001",
  "SchemeName": "SortCodeAccountNumber"
}

❯ GET /balance

An AISP requests the available balance of a specified account.

Request

FieldDescription
AccountIdA unique identifier for the account being requested

Response

FieldDescriptionMandatoryOptions
AmountThe current available balance expressed as number with two or three decimal points e.g. 12.34Yes
CurrencyIdentification of the currency in which the balance is expressed in ISO 4217 three-letter code formatYes
CreditDebitIndicates whether the balance is a credit or a debit balanceYesCredit
Debit

GET Balance Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /balance",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001"
  }
}

GET Balance Response

{
  "Amount": "12.34",
  "Currency": "GBP",
  "CreditDebit": "Credit"
}

❯ GET /transactions

An AISP requests a list of transactions for a specified account. Transactions will automatically be filtered by tell. based on the BookingDateTime in your response using the FromBookingDateTime and ToBookingDateTime request parameters.

Optionally, you can provide paginated responses. This is useful in cases where an account has a large amount of transactions to help reduce latency between tell. and you. To achieve this, you must handle Offset in the request body and return these response headers:

  • x-offset - The current page that is returned (starting at "0").
  • x-total-pages - The total number of pages available.
  • x-array-size - The number of transactions per page.
  • x-total-elements - The total number of transactions.

If the GET /statements functionality is enabled, you will need to handle StatementId in the request parameters.

Request

FieldDescriptionUsage
AccountIdA unique identifier for the account being requestedMandatory
FromBookingDateTimeIf specified, this indicates the date from which the transactions should be filteredOptional
ToBookingDateTimeIf specified, this indicates the date to which the transactions should be filteredOptional
OffsetThis indicates the page to be returned (starting at "0").

If you are not providing paginated responses, you may ignore this.
Optional

Mandatory to handle if providing paginated responses
StatementIdIf specified, this indicates the statement identifier to which transactions are associated with.

If GET /statements is not enabled, you may ignore this.
Optional

Mandatory to handle if GET /statements is enabled

Response

FieldDescriptionMandatoryOptions
TransactionsAn array of TransactionsYesProvide an empty array if there's no transactions.
Transactions/
TransactionId
A unique identifier for the transaction (may be system-issued, not known to the account holder)No
Transactions/
BookingDateTime
Date and time when a transaction entry is posted in ISODateTime formatYes
Transactions/
Amount
The transaction amount expressed as number with two or three decimal points e.g. 12.34Yes
Transactions/
Currency
Transaction currency in ISO 4217 three-letter code formatYes
Transactions/
Status
Status of the transactionYesBooked
Pending
Rejected
Transactions/
CreditDebit
Indicates if the transaction is a credit or a debitYesCredit
Debit
Transactions/
Code
Transaction codeYes if SubCode is suppliedTransfer
Card
DirectDebit
Misc
Transactions/
SubCode
Transaction sub code. Sub codes are related to the transaction code and must be an applicable child code as per the list in this Options sectionYes if Code is suppliedTransfer:

- StandingOrder

- StandingOrderCrossBorder

- CreditTransferSEPA

- CreditTransferDomestic

- CreditTransferCrossBorder

- Other

Card:

- CashWithdrawal

- POS

- Other

DirectDebit:

- DirectDebit

- DirectDebitSEPACore

- DirectDebitSEPAB2B

- DirectDebitCrossBorder

Misc:

- Fees

- Commission

- Interest

- Adjustments

- Other
Transactions/
CardSchemeName
Use if Code is "Card"
Name of the card scheme.
NoAmericanExpress
Diners
Discover
MasterCard
VISA
Transactions/
CardIdentification
Use if Code is "Card"
Identification assigned by an institution to identify the card instrument used in the transaction. This identification is known by the account owner, and must be masked – do not provide clear PAN under any circumstances
No
Transactions/
CreditorSchemeName
Use if Code is "Transfer"
If using an 8-digit numeric account number and 6-digit sort-code, return SortCodeAccountNumber.

If using IBAN, return IBAN.

If using BBAN, return BBAN.

If using MSISDN, return MSISDN

Otherwise use CustomCode.
NoOBIE:

- SortCodeAccountNumber

- IBAN

- CustomCodeNextGenPSD2:

- IBAN

- BBAN

- MSISDN
Transactions/
CreditorIdentification
Use if Code is "Transfer"
If CreditorSchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number.
If using CustomCode, provide the Identifier as known to your account holder
No
Transactions/
CreditorName
Use if Code is "Transfer"
Name of creditor account
No
Transactions/
AddressLine
Information that locates and identifies a specific address for a transaction entry (Max length of 70 characters)No
Transactions/
MerchantCategoryCode
Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.No
Transactions/
MerchantName
Name by which the merchant is known (Max length of 350 characters)No
Transactions/
TransactionInformation
Further details of the transaction. This is the transaction narrative (Max length of 500 characters)No

GET Transactions Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /transactions",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001",
      "Offset": 0
  }
}

GET Transactions Response

{
  "Transactions": [
    {
      "AddressLine": "An Address",
      "Amount": "12.34",
      "BookingDateTime": "2021-04-05T10:43:07+00:00",
      "CardSchemeName": "VISA",
      "CardIdentification": "#7692",
      "Currency": "GBP",
      "CreditDebit": "Debit",
      "MerchantCategoryCode": "7992",
      "MerchantName": "Tesco",
      "Code": "Card",
      "SubCode": "CashWithdrawal",
      "Status": "Booked",
      "TransactionId": "txid_1234321",
      "TransactionInformation": "Info"
    },
    {
      "AddressLine": "An Address",
      "Amount": "12.34",
      "Currency": "GBP",
      "BookingDateTime": "2021-04-08T10:43:07+00:00",
      "CreditDebit": "Debit",
      "CreditorSchemeName": "SortCodeAccountNumber",
      "CreditorIdentification": "80200112345678",
      "CreditorName": "Mrs Jones",
      "Code": "Transfer",
      "SubCode": "CreditTransferDomestic",
      "Status": "Pending",
      "TransactionId": "txid_1234329",
      "TransactionInformation": "Info"
    },
    {
      "AddressLine": "An Address",
      "Amount": "12.34",
      "Currency": "GBP",
      "BookingDateTime": "2021-05-05T10:43:07+00:00",
      "CreditDebit": "Debit",
      "Code": "DirectDebit",
      "SubCode": "DirectDebitCrossBorder",
      "Status": "Booked",
      "TransactionId": "txid_1234381",
      "TransactionInformation": "Info"
    },
    {
      "AddressLine": "An Address",
      "Amount": "12.34",
      "Currency": "GBP",
      "BookingDateTime": "2021-06-05T10:43:07+00:00",
      "CreditDebit": "Debit",
      "Code": "Misc",
      "SubCode": "Fees",
      "Status": "Booked",
      "TransactionId": "txid_121212",
      "TransactionInformation": "Info"
    },
    {
      "AddressLine": "An Address",
      "Amount": "12.34",
      "Currency": "GBP",
      "BookingDateTime": "2021-07-05T10:43:07+00:00",
      "CardSchemeName": "VISA",
      "CardIdentification": "#7692",
      "CreditDebit": "Debit",
      "MerchantCategoryCode": "7992",
      "MerchantName": "Tesco",
      "Code": "Card",
      "SubCode": "POS",
      "Status": "Booked",
      "TransactionId": "txid_1234334",
      "TransactionInformation": "Info"
    }
  ]
}

❯ GET /beneficiaries

An AISP requests a list of beneficiaries for a specified account.

Request

FieldDescription
AccountIdA unique identifier for the account being requested

Response

FieldDescriptionMandatoryOptions
BeneficiariesAn array of BeneficiariesYes
Beneficiaries/BeneficiaryIdA unique identifier for the beneficiary (may be system-issued, not known to the account holder)Yes
Beneficiaries/SchemeNameIf using an 8-digit numeric account number and 6-digit sort-code, return SortCodeAccountNumber.

If using IBAN, return IBAN.

If using BBAN, return BBAN.

Otherwise use CustomCode.
YesSortCodeAccountNumber
IBAN
BBAN
CustomCode
Beneficiaries/IdentificationIf SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account numberYes
Beneficiaries/ReferenceReference for the beneficiaryNo
Beneficiaries/NameName by which the beneficiary is known by.No

GET Beneficiaries Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /beneficiaries",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001"
  }
}

GET Beneficiaries Response

{
  "Beneficiaries": [
    {
      "BeneficiaryId": "abc-123-qwe-456",
      "Reference": "Mum",
      "SchemeName": "SortCodeAccountNumber",
      "Identification": "80200112345678",
      "Name": "Mrs Smith"
    },
    {
      "BeneficiaryId": "ert-123-qwe-655",
      "Reference": "Dad",
      "SchemeName": "SortCodeAccountNumber",
      "Identification": "80200112345678"
    },
    {
      "BeneficiaryId": "ttr-123-qwe-878",
      "SchemeName": "CustomCode",
      "Identification": "80200112-35ABC",
      "Name": "Secondary School Acadamy"
    }
  ]
}

❯ GET /direct-debits

An AISP requests a list of direct debits for a specified account.

Request

FieldDescription
AccountIdA unique identifier for the account being requested

Response

FieldDescriptionMandatoryOptions
DirectDebitsAn array of Direct DebitsYes
DirectDebits/DirectDebitIdA unique identifier for the direct debit (may be system-issued, not known to the account holder)Yes
DirectDebits/StatusCodeStatus of the direct debitYesActive
Inactive
DirectDebits/MandateIdentificationDirect Debit reference. For AUDDIS service users provide Core Reference. For non AUDDIS service users provide Core reference if possible or last used referenceYes
DirectDebits/NameName of the Direct Debit beneficiaryYes

GET Direct Debits Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /direct-debits",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001"
  }
}

GET Direct Debits Response

{
  "DirectDebits": [
    {
      "DirectDebitId": "DD03",
      "DirectDebitStatusCode": "Active",
      "MandateIdentification": "DD03_MANDATE_REF",
      "Name": "Energy Bill"
    },
    {
      "DirectDebitId": "DD09",
      "DirectDebitStatusCode": "Active",
      "MandateIdentification": "DD09_MANDATE_REF",
      "Name": "Rent"
    },
    {
      "DirectDebitId": "DD98",
      "DirectDebitStatusCode": "Inactive",
      "MandateIdentification": "DD98_MANDATE_REF",
      "Name": "Mobile Phone Bill"
    }
  ]
}

❯ GET /scheduled-payments

An AISP requests a list of scheduled payments for a specified account.

Request

FieldDescription
AccountIdA unique identifier for the account being requested

Response

FieldDescriptionMandatoryOptions
ScheduledPaymentsAn array of Scheduled PaymentsYes
ScheduledPayments/ScheduledPaymentIdA unique identifier for the scheduled payment (may be system-issued, not known to the account holder)Yes
ScheduledPayments/ScheduledPaymentDateTimeThe date on which the scheduled payment will be made in ISODateTimeYes
ScheduledPayments/SchemeNameIf using an 8-digit numeric account number and 6-digit sort-code, return SortCodeAccountNumber.

If using IBAN, return IBAN.

If using BBAN, return BBAN.

Otherwise use CustomCode.
YesSortCodeAccountNumber
IBAN
BBAN
CustomCode
ScheduledPayments/IdentificationIf SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number.
If using CustomCode, provide the Identifier as known to your account holder
Yes
ScheduledPayments/AmountThe amount due to be paid expressed as number with two or three decimal points e.g. 12.34Yes
ScheduledPayments/CurrencyPayment currency in ISO 4217 three-letter code formatYes
ScheduledPayments/NameName of the account, as assigned by the account servicing institutionYes

GET Scheduled Payments Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /scheduled-payments",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001"
  }
}

GET Scheduled Payments Response

{
  "ScheduledPayments": [
    {
      "ScheduledPaymentId": "SchPay956",
      "ScheduledPaymentDateTime": "2022-12-25T00:00:00+00:00",
      "Identification": "23605490179017",
      "SchemeName": "SortCodeAccountNumber",
      "Name": "Auntie Beeb",
      "Amount": "12.34",
      "Currency": "GBP"
    },
    {
      "ScheduledPaymentId": "SchPay85",
      "ScheduledPaymentDateTime": "2023-12-25T00:00:00+00:00",
      "Identification": "23605490179017",
      "SchemeName": "SortCodeAccountNumber",
      "Name": "Auntie Beeb",
      "Amount": "102.00",
      "Currency": "GBP"
    },
    {
      "ScheduledPaymentId": "SchPay771",
      "ScheduledPaymentDateTime": "2024-12-25T00:00:00+00:00",
      "Identification": "23605490179017",
      "SchemeName": "SortCodeAccountNumber",
      "Name": "Auntie Beeb",
      "Amount": "0.01",
      "Currency": "GBP"
    }
  ]
}

❯ GET /standing-orders

An AISP requests a list of standing orders for a specified account.

Request

FieldDescription
AccountIdA unique identifier for the account being requested

Response

FieldDescriptionMandatoryOptions
StandingOrdersAn array of Standing OrdersYes
StandingOrders/StandingOrderIdA unique identifier for the standing order (may be system-issued, not known to the account holder)Yes
StandingOrders/ReferenceA reference for the standing orderYes
StandingOrders/SchemeNameIf using an 8-digit numeric account number and 6-digit sort-code, return SortCodeAccountNumber.

If using IBAN, return IBAN.

If using BBAN, return BBAN.

Otherwise use CustomCode.
YesSortCodeAccountNumber
IBAN
BBAN
CustomCode
StandingOrders/IdentificationIf SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number.
If using CustomCode, provide the Identifier as known to your account holder
Yes
StandingOrders/AmountThe amount due to be paid expressed as number with two or three decimal points e.g. 12.34Yes
StandingOrders/CurrencyPayment currency in ISO 4217 three-letter code formatYes
StandingOrders/NameName of the account, as assigned by the account servicing institutionYes
StandingOrders/FrequencyFrequency of the standing orderYesSee Frequency for details
StandingOrders/StatusCodeStatus code of the standing orderYesActive
Inactive
StandingOrders/FirstPaymentDateTimeThe date (ISO) on which the first payment for a Standing Order schedule will be made.No
StandingOrders/LastPaymentDateTimeThe date (ISO) on which the last (most recent) payment for a Standing Order schedule was made.No

GET Standing Orders Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /standing-orders",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001"
  }
}

GET Standing Orders Response

{
  "StandingOrders": [
    {
      "StandingOrderId": "SOID754",
      "Identification": "23605490179017",
      "SchemeName": "SortCodeAccountNumber",
      "Name": "Auntie Beeb",
      "Frequency": "EvryDay",
      "Amount": "99.99",
      "Currency": "GBP",
      "Reference": "TV Licence",
      "StatusCode": "Active",
      "FirstPaymentDateTime": '2024-10-01T00:00:00+00:00',
      "LastPaymentDateTime": '2024-10-10T00:00:00+00:00'
    },
    {
      "StandingOrderId": "SOID544",
      "Identification": "93605490179013",
      "SchemeName": "SortCodeAccountNumber",
      "Name": "MGage Providers 101",
      "Frequency": "IntrvlMnthDay:01:-01",
      "Amount": "123.45",
      "Currency": "GBP",
      "Reference": "Mortgage payments",
      "StatusCode": "Active",
      "FirstPaymentDateTime": '2024-10-01T00:00:00+00:00'
    },
    {
      "StandingOrderId": "SOID098",
      "Identification": "Acc-Ref-0101x1",
      "SchemeName": "CustomCode",
      "Name": "Little Smith",
      "Frequency": "IntrvlWkDay:01:01",
      "Amount": "10.00",
      "Currency": "GBP",
      "Reference": "Pocket Money",
      "StatusCode": "Inactive"
    }
  ]
}

❯ GET /statements

An AISP requests a list of statements for a specified account. The TPP may make the request with the following request parameters:

  • fromStatementDateTime and toStatementDateTime- A TPP has specified a date range.
  • StatementId - A TPP has specified an individual statement.

tell. will automatically filter statements based on the request query parameters from the TPP. This means there's nothing for you to do! Simply return all statements of an AccountId and we will handle the rest.

Request

FieldDescriptionUsage
AccountIdA unique identifier for the account being requestedMandatory

📘

Returning the Transactions array in the response is entirely optional. Transactions will only be included in the response to the TPP if the consent was granted ReadStatementsDetail by the PSU, otherwise they will be filtered out.

Response

FieldDescriptionMandatoryOptions
StatementsAn array of StatementsYes
Statements/StatementIdA unique identifier for the statement (may be system-issued, not known to the account holder)Yes
Statements/StartDateTimeDate and time at which the statement period starts (ISODateTime)Yes
Statements/EndDateTimeDate and time at which the statement period ends (ISODateTime)YesTransfer
Card
DirectDebit
Misc
Statements/CreationDateTimeDate and time at which the resource was created (ISODateTime)Yes
Statements/StatementTypeStatement type, in a coded formYesAccountClosure AccountOpening
Annual
Interim
RegularPeriodic
Statements/TransactionsAn array of transactions associated with a statementNo
Statements/Transactions/AmountThe transaction amount expressed as number with two or three decimal points e.g. 12.34Yes for each transaction
Statements/Transactions/CurrencyTransaction currency in ISO 4217 three-letter code formatYes for each transaction
Statements/Transactions/CreditDebitIndicates if the transaction is a credit or a debitYes for each transactionCredit
Debit
Statements/Transactions/AmountTypeAmount type, in a coded form.Yes for each transactionArrearsClosingBalance
AvailableBalance
AverageBalanceWhenInCredit
AverageBalanceWhenInDebit
AverageDailyBalance
BalanceTransferClosingBalance
CashClosingBalance
ClosingBalance
CreditLimit
CurrentPayment
DirectDebitPaymentDue
FSCSInsurance
MinimumPaymentDue
PendingTransactionsBalance
PreviousClosingBalance
PreviousPayment
PurchaseClosingBalance
StartingBalance
TotalAdjustments
TotalCashAdvances
TotalCharges
TotalCredits
TotalDebits
TotalPurchases

GET Statements Request

{
  "Info": {
    "Operation": "GET /statements",
    "RqId": "86b0d5d9-b550-4d7d-98d9-5ddf4d0357dc",
    "UserId": "106726572",
    "ConsentId": "9162e1b6-b46d-4fa1-a0b8-e0fd47aec36f",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Sandbox App"
    }
  },
  "Data": {
      "AccountId": "10000001"
  }
}
POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

GET Statements Response

{
  "Statements": [
    {
      "StatementId": "34hj24u-324h33-31i3p4",
      "StartDateTime": "2017-10-01T00:00:00+00:00",
      "EndDateTime": "2017-10-30T23:59:59+00:00",
      "CreationDateTime": "2017-11-01T00:00:00+00:00",
      "StatementType": "RegularPeriodic",
      "Transactions": [
        {
          "Amount": "400.00",
          "Currency": "GBP",
          "CreditDebit": "Credit",
          "AmountType": "ClosingBalance"
        },
        {
          "Amount": "600.00",
          "Currency": "GBP",
          "CreditDebit": "Credit",
          "AmountType": "PreviousClosingBalance"
        }
      ]
    },
    {
      "StatementId": "8sfhke-sifhkeuf-97813",
      "StartDateTime": "2017-08-01T00:00:00+00:00",
      "EndDateTime": "2017-08-31T23:59:59+00:00",
      "CreationDateTime": "2017-09-01T00:00:00+00:00",
      "StatementType": "RegularPeriodic"
    }
  ]
}

❯ GET /payment-funds-confirmation

PISP requests confirmation funds are available for a payment that has been consented to (prior to execution). This operation is only relevant for Domestic and International payments (not scheduled payments or standing orders).

Please note that this is not a request to execute the payment and should not affect the status of the consent or the account balance.

Request

FieldDescription
AccountIdA unique identifier for the account being requested
DebtorAccountIdentification of the account from which funds should be drawn. This may be the same as the AccountId except in cases where the Id used by the customer is different from your system Id
AmountThe amount due to be paid expressed as number with two or three decimal points e.g. 12.34
CurrencyPayment currency in ISO 4217 three-letter code format

Response

FieldDescriptionMandatoryOptions
FundsAvailableConfirmation of whether sufficient funds are currently available to successfully execute the payment expressed as a Boolean valueYesTRUE
FALSE

GET Payment Funds Confirmation Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /payment-funds-confirmation",
    "RqId": "d8490996-79aa-4ceb-a901-5a58abce9e5b",
    "ConsentId": "215d0837-c4fb-4915-bc4a-c046726ffb56",
    "UserId": "106726572",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Integration App"
    }
  },
  "Data": {
    "AccountId": "10000001",
    "DebtorAccount": "00000010000001",
    "Amount": "123.12",
    "Currency": "GBP"
  }
}

GET Payment Funds Confirmation Response

{
  "FundsAvailable": true
}

❯ POST /payment

PISP requests execution of a payment which has been authorised by the PSU through the consent process. This operation is used for all payment types (domestic, domestic standing order, domestic scheduled, international, international scheduled and international standing order) with differing payloads based on the payment type.

The request data will always match the data provided when the consent was requested and accepted (neither the user nor the third party provider can alter it after consent is granted).

Request

FieldDescriptionUsed Where Payment Type IsOptions
AccountIdA unique identifier for the account being requestedAll Payment Types
PaymentTypeType of paymentAll Payment TypesOBIE:

- Domestic

- Domestic Scheduled

- Domestic Standing Order

- International

- International Scheduled

- International Standing OrderNextGenPSD2:

- SEPA Credit Transfers

- Instant SEPA Credit Transfers

- Target 2 Payments

- Cross Border Credit Transfers
DebtorIdentificationIdentification of the account of the debtor to which a debit entry will be made as a result of the transaction.

For OBIE, if the debtor account was selected during authorisation, the value will be "ProvidedDuringAuthorisation". In this case, refer to the AccountId for the debtor account.
All Payment TypesOBIE
-ProvidedDuringAuthorisation
BeneficiaryIdentificationIdentification of the beneficiary accountAll Payment Types
BeneficiarySchemeNameThe SchemeName of the BeneficiaryIdentificationAll Payment TypesOBIE:

- SortCodeAccountNumber

- IBAN

- CustomCodeNextGenPSD2:

- IBAN

- BBAN

- MSISDN
BeneficiaryNameName of the beneficiaryAll Payment Types
AmountThe amount due to be paid expressed as number with two or three decimal points e.g. 12.34OBIE:

- Domestic

- Domestic Scheduled

- International

- International ScheduledNextGenPSD2:

- SEPA Credit Transfers

- Instant SEPA Credit Transfers

- Target 2 Payments

- Cross Border Credit Transfers
CurrencyPayment currency in ISO 4217 three-letter code formatOBIE:

- Domestic

- Domestic Scheduled

- International

- International ScheduledNextGenPSD2:

- SEPA Credit Transfers

- Instant SEPA Credit Transfers

- Target 2 Payments

- Cross Border Credit Transfers
ExecutionDateTimeDate at which the requestor would like the payment to be madeOBIE:

- Domestic Scheduled
- International Scheduled
FrequencyFrequency of the standing orderOBIE:

- Domestic Standing Order
- International Standing Order
See Frequency for details
FirstPaymentAmountThe amount of the first Standing Order. This field will not always be providedOBIE:

- Domestic Standing Order
- International Standing Order
FirstPaymentCurrencyThe currency of the first Standing Order in ISO 4217 three-letter code format. This field will only be provided if FirstPaymentAmount is presentOBIE:

- Domestic Standing Order
- International Standing Order
FirstPaymentDateTimeThe date on which the first payment for a Standing Order schedule will be made in ISODateTime format. This field will only be provided if FirstPaymentAmount is presentOBIE:

- Domestic Standing Order
- International Standing Order
RecurringPaymentAmountThe amount of the recurring Standing OrderOBIE:

- Domestic Standing Order
- International Standing Order
RecurringPaymentCurrencyThe currency of the recurring Standing Order in ISO 4217 three-letter code formatOBIE:

- Domestic Standing Order
- International Standing Order
FinalPaymentAmountThe amount of the final Standing Order. This field will not always be providedOBIE:

- Domestic Standing Order
- International Standing Order
FinalPaymentCurrencyThe currency of the final Standing Order in ISO 4217 three-letter code format. This field will only be provided if FinalPaymentAmount is presentOBIE:

- Domestic Standing Order
- International Standing Order
FinalPaymentDateTimeThe date on which the final payment for a Standing Order schedule will be made in ISODateTime format. This field will only be provided if FinalPaymentAmount is presentOBIE:

- Domestic Standing Order
- International Standing Order
CurrencyOfTransferThe currency of the amount to be transferred in ISO 4217 three-letter code format, which is different from the currency of the debtor's accountOBIE:

- International
- International Scheduled
- International Standing Order
EndToEndIdentificationUnique identification to unambiguously identify the transaction. This identification is immutable throughout the entire end-to-end chain.OBIE:

- Domestic
- Domestic Scheduled
- International
- International Scheduled
ReferenceReference to enable the matching/reconciliation of an entry with the items that the payment is intended to settle. The TPP may not provide one.(Optional) All Payment Types
CreditorAgent/IdentificationUnique and unambiguous identification of a financial institution or a branch of a financial institutionOBIE:
(Optional)

- International
- International Scheduled
- International Standing Order
CreditorAgent/SchemeNameName of the identification scheme.OBIE:
(Optional)

- International
- International Scheduled
- International Standing Order
OBIE

- BICFI
- NCC.[ISO3166CountryCode]
CreditorAgent/NameName by which an agent is known and which is usually used to identify that agentOBIE:
(Optional)

- International
- International Scheduled
- International Standing Order
CreditorAgent/AddressLineInformation that locates and identifies a specific address, as defined by postal services, presented in free format text.OBIE:
(Optional)

- International
- International Scheduled
- International Standing Order

Response

FieldDescriptionMandatory
PaymentReferenceUnique identification assigned by your application to uniquely identify the paymentYes

POST Payment Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "POST /payment",
    "RqId": "d8490996-79aa-4ceb-a901-5a58abce9e5b",
    "ConsentId": "215d0837-c4fb-4915-bc4a-c046726ffb56",
    "UserId": "106726572",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Integration App"
    }
  },
  "Data": {
    "PaymentType": "Domestic",
    "AccountId": "10000001",
    "DebtorIdentification": "00000010000001",
    "BeneficiaryIdentification": "12345612345678",
    "BeneficiaryName": "Joe Bloggs",
    "Amount": "123.12",
    "Currency": "GBP",
    "EndToEndIdentification": "e574a44a-3e85-476e-8503-d6c0f4d487d6",
    "Reference": "1234567",
    "CreditorAgent": {
      "Identification": "BANKGB22XXX",
      "SchemeName": "BICFI",
      "Name": "Joe Bloggs",
    }
  }
}

POST Payment Response

{
  "PaymentReference": "4e28ff4c-3639-4183-a8f6-bcb5a3f36754"
}

❯ GET /payment

PISP requests the status of a payment which has been submitted for execution. This operation is used for all payment types (domestic, domestic standing order, domestic scheduled, international, international scheduled and international standing order).

Request

FieldDescription
AccountIdA unique identifier for the account being requested
PaymentReferenceUnique identification assigned by your application and returned as part of the POST /payment operation

Response

FieldDescriptionMandatoryOptions
PaymentStatusStatus of the paymentYesPending
Rejected
AcceptedSettlementInProcess
AcceptedSettlementCompleted

GET Payment Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "GET /payment",
    "RqId": "d8490996-79aa-4ceb-a901-5a58abce9e5b",
    "ConsentId": "215d0837-c4fb-4915-bc4a-c046726ffb56",
    "UserId": "106726572",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Integration App"
    }
  },
  "Data": {
    "AccountId": "10000001",
    "PaymentReference": "4e28ff4c-3639-4183-a8f6-bcb5a3f36754"
  }
}

GET Payment Response

{
  "PaymentStatus": "AcceptedSettlementCompleted"
}

❯ POST /funds-confirmation

CBPII requests confirmations of the availability of funds.

The request data will always match the data provided when the consent was requested and accepted (neither the user nor the third party provider can alter it after consent is granted).

Request

FieldDescriptionOptions
AccountIdA unique identifier for the account being requested
DebtorAccountIdentification of the account of the debtor to which a confirmation of funds consent was applied
DebtorSchemeNameName of the debtor account's identification scheme."SortCodeAccountNumber"
6-digit sort code concatenated with 8-digit account number.

"IBAN"

"CustomCode"
Custom identification type known to the Account Holder and/or Account Providers.
AmountThe amount to confirm expressed as number with two or three decimal points e.g. 12.34
CurrencyCurrency in ISO 4217 three-letter code format

Response

FieldDescriptionMandatoryOptions
FundsAvailableConfirmation of whether sufficient funds are currently available based on the value supplied, expressed as a Boolean valueYesTRUE
FALSE

POST Funds Confirmation Request

POST /your-bank.com/tell-gateway-api HTTP/1.1
x-api-key: 6d0b32a2-xxxx-xxxx-xxxx-xxxxxxxxxxxx
x-jws-signature: eyJhxxxx.eyJJxxxx.Ugzpxxxx
Content-Type: application/json
Accept: application/json

{
  "Info": {
    "Operation": "POST /funds-confirmation",
    "RqId": "d8490996-79aa-4ceb-a901-5a58abce9e5b",
    "ConsentId": "215d0837-c4fb-4915-bc4a-c046726ffb56",
    "UserId": "106726572",
    "Tpp": {
      "TppName": "Tell Money",
      "AppName": "My Integration App"
    }
  },
  "Data": {
    "AccountId": "10000001",
    "DebtorAccount": "00000012345678",
    "DebtorSchemeName": "SortCodeAccountNumber",
    "Amount": "20.00",
    "Currency": "GBP"
  }
}

POST Funds Confirmation Response

{
  "FundsAvailable": true
}


Frequency

Individual Definitions:

  • EvryDay - Every day
  • EvryWorkgDay - Every working day
  • IntrvlWkDay - An interval specified in weeks (01 to 09), and the day within the week (01 to 07)
  • WkInMnthDay - A monthly interval, specifying the week of the month (01 to 05) and day within the week (01 to 07)
  • IntrvlMnthDay - An interval specified in months (between 01 to 06, 12, 24), specifying the day within the month (-5 to -1, 1 to 31)
  • QtrDay - Quarterly (either ENGLISH, SCOTTISH, or RECEIVED)
  • ENGLISH = Paid on the 25th March, 24th June, 29th September and 25th December.
  • SCOTTISH = Paid on the 2nd February, 15th May, 1st August and 11th November.
  • RECEIVED = Paid on the 20th March, 19th June, 24th September and 20th December.

Individual Patterns:

  • EvryDay (ScheduleCode)
  • EvryWorkgDay (ScheduleCode)
  • IntrvlWkDay:IntervalInWeeks:DayInWeek (ScheduleCode + IntervalInWeeks + DayInWeek)
  • WkInMnthDay:WeekInMonth:DayInWeek (ScheduleCode + WeekInMonth + DayInWeek)
  • IntrvlMnthDay:IntervalInMonths:DayInMonth (ScheduleCode + IntervalInMonths + DayInMonth)
  • QtrDay: + either (ENGLISH, SCOTTISH or RECEIVED) ScheduleCode + QuarterDay

Regular Expression:

The regular expression for this element combines five smaller versions for each permitted pattern. To aid legibility - the components are presented individually here:

  • EvryDay EvryWorkgDay

  • IntrvlWkDay:0[1-9]:0[1-7]

  • WkInMnthDay:0[1-5]:0[1-7]

  • IntrvlMnthDay:(0[1-6]|12|24):(-0[1-5]|0[1-9]|[12][0-9]|3[01])

  • QtrDay:(ENGLISH|SCOTTISH|RECEIVED)

    ^(EvryDay)$|^(EvryWorkgDay)$|^(IntrvlWkDay:0[1-9]:0[1-7])$|^(WkInMnthDay:0[1-5]:0[1-7])$|^(IntrvlMnthDay:(0[1-6]|12|24):(-0[1-5]|0[1-9]|[12][0-9]|3[01]))$|^(QtrDay:(ENGLISH|SCOTTISH|RECEIVED))