Resources
ACCOUNT PROVIDER 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.
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.
Field | Description |
---|---|
Operation | Name of the operation being requested |
RqId | A UUID generated by tell.gateway to identify an individual request |
ConsentId | The Consent ID allocated by tell.gateway when the consent was created and used in the initial authorisation process |
UserId | The account holder identifier provided by your application when the consent was granted |
Tpp | An 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 Code | Usage | Body Required |
---|---|---|
200 | For all successfully processed requests | Yes – as described in this documentation |
400 | If 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" } |
404 | If the resource cannot be found return 404. No response body is required. | No |
500 | For 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.
Operation | API | Description |
---|---|---|
GET /accounts | AISP | Requests a list of accounts associated with a consent |
GET /account | AISP | Requests details of an account associated with a consent |
GET /balance | AISP | Requests the balance of an account associated with a consent |
GET /transactions | AISP | Requests a list of transactions for an account associated with a consent |
GET /beneficiaries | AISP | Requests a list of beneficiaries for an account associated with a consent |
GET /direct-debits | AISP | Requests a list of direct debits for an account associated with a consent |
GET /scheduled-payments | AISP | Requests a list of scheduled payments for an account associated with a consent |
GET /standing-orders | AISP | Requests a list of standing orders for an account associated with a consent |
GET /statements | AISP | Requests a list of statements for an account associated with a consent |
GET /payment-funds-confirmation | PISP | Requests confirmation funds are available for a payment that has been consented to |
POST /payment | PISP | Requests execution of a payment that has been previously consented to by the User |
GET /payment | PISP | Requests status of a payment that has been submitted for execution |
POST /funds-confirmation | CBPII | Requests 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.
Field | Description | Mandatory | Options |
---|---|---|---|
Accounts | An array of Accounts | Yes | |
Accounts/AccountId | A unique identifier for the account (may be system-issued, not known to the account holder) | Yes | |
Accounts/Currency | Account currency in ISO 4217 three-letter code format | Yes | |
Accounts/AccountType | Type of account | Yes | Personal Business |
Accounts/AccountSubType | The sub type of account | Yes | ChargeCard CreditCard CurrentAccount EMoney Loan Mortgage PrePaidCard Savings |
Accounts/Nickname | The nickname of the account | No | |
Accounts/SchemeName | 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. | Yes | OBIE: - SortCodeAccountNumber - IBAN - CustomCodeNextGenPSD2: - IBAN - BBAN - MSISDN |
Accounts/Identification | If 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
Field | Description |
---|---|
AccountId | A 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.
Field | Description | Mandatory | Options |
---|---|---|---|
Currency | Account currency in ISO 4217 three-letter code format | Yes | |
AccountType | Type of account | Yes | Personal Business |
AccountSubType | The sub type of account | Yes | ChargeCard CreditCard CurrentAccount EMoney Loan Mortgage PrePaidCard Savings |
Nickname | The nickname of the account | No | |
SchemeName | 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. | Yes | OBIE: - SortCodeAccountNumber - IBAN - CustomCodeNextGenPSD2: - IBAN - BBAN - MSISDN |
Identification | If 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
Field | Description |
---|---|
AccountId | A unique identifier for the account being requested |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
Amount | The current available balance expressed as number with two or three decimal points e.g. 12.34 | Yes | |
Currency | Identification of the currency in which the balance is expressed in ISO 4217 three-letter code format | Yes | |
CreditDebit | Indicates whether the balance is a credit or a debit balance | Yes | Credit 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
Field | Description | Usage |
---|---|---|
AccountId | A unique identifier for the account being requested | Mandatory |
FromBookingDateTime | If specified, this indicates the date from which the transactions should be filtered | Optional |
ToBookingDateTime | If specified, this indicates the date to which the transactions should be filtered | Optional |
Offset | This 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 |
StatementId | If 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
Field | Description | Mandatory | Options |
---|---|---|---|
Transactions | An array of Transactions | Yes | Provide 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 format | Yes | |
Transactions/ Amount | The transaction amount expressed as number with two or three decimal points e.g. 12.34 | Yes | |
Transactions/ Currency | Transaction currency in ISO 4217 three-letter code format | Yes | |
Transactions/ Status | Status of the transaction | Yes | Booked Pending Rejected |
Transactions/ CreditDebit | Indicates if the transaction is a credit or a debit | Yes | Credit Debit |
Transactions/ Code | Transaction code | Yes if SubCode is supplied | Transfer 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 section | Yes if Code is supplied | Transfer: - 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. | No | AmericanExpress 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. | No | OBIE: - 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
Field | Description |
---|---|
AccountId | A unique identifier for the account being requested |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
Beneficiaries | An array of Beneficiaries | Yes | |
Beneficiaries/BeneficiaryId | A unique identifier for the beneficiary (may be system-issued, not known to the account holder) | Yes | |
Beneficiaries/SchemeName | 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. Otherwise use CustomCode. | Yes | SortCodeAccountNumber IBAN BBAN CustomCode |
Beneficiaries/Identification | If SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number | Yes | |
Beneficiaries/Reference | Reference for the beneficiary | No | |
Beneficiaries/Name | Name 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
Field | Description |
---|---|
AccountId | A unique identifier for the account being requested |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
DirectDebits | An array of Direct Debits | Yes | |
DirectDebits/DirectDebitId | A unique identifier for the direct debit (may be system-issued, not known to the account holder) | Yes | |
DirectDebits/StatusCode | Status of the direct debit | Yes | Active Inactive |
DirectDebits/MandateIdentification | Direct Debit reference. For AUDDIS service users provide Core Reference. For non AUDDIS service users provide Core reference if possible or last used reference | Yes | |
DirectDebits/Name | Name of the Direct Debit beneficiary | Yes |
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
Field | Description |
---|---|
AccountId | A unique identifier for the account being requested |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
ScheduledPayments | An array of Scheduled Payments | Yes | |
ScheduledPayments/ScheduledPaymentId | A unique identifier for the scheduled payment (may be system-issued, not known to the account holder) | Yes | |
ScheduledPayments/ScheduledPaymentDateTime | The date on which the scheduled payment will be made in ISODateTime | Yes | |
ScheduledPayments/SchemeName | 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. Otherwise use CustomCode. | Yes | SortCodeAccountNumber IBAN BBAN CustomCode |
ScheduledPayments/Identification | If SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number. If using CustomCode, provide the Identifier as known to your account holder | Yes | |
ScheduledPayments/Amount | The amount due to be paid expressed as number with two or three decimal points e.g. 12.34 | Yes | |
ScheduledPayments/Currency | Payment currency in ISO 4217 three-letter code format | Yes | |
ScheduledPayments/Name | Name of the account, as assigned by the account servicing institution | Yes |
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
Field | Description |
---|---|
AccountId | A unique identifier for the account being requested |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
StandingOrders | An array of Standing Orders | Yes | |
StandingOrders/StandingOrderId | A unique identifier for the standing order (may be system-issued, not known to the account holder) | Yes | |
StandingOrders/Reference | A reference for the standing order | Yes | |
StandingOrders/SchemeName | 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. Otherwise use CustomCode. | Yes | SortCodeAccountNumber IBAN BBAN CustomCode |
StandingOrders/Identification | If SchemeName is SortCodeAccountNumber, concatenate sort-code followed by account number. If using CustomCode, provide the Identifier as known to your account holder | Yes | |
StandingOrders/Amount | The amount due to be paid expressed as number with two or three decimal points e.g. 12.34 | Yes | |
StandingOrders/Currency | Payment currency in ISO 4217 three-letter code format | Yes | |
StandingOrders/Name | Name of the account, as assigned by the account servicing institution | Yes | |
StandingOrders/Frequency | Frequency of the standing order | Yes | See Frequency for details |
StandingOrders/StatusCode | Status code of the standing order | Yes | Active Inactive |
StandingOrders/FirstPaymentDateTime | The date (ISO) on which the first payment for a Standing Order schedule will be made. | No | |
StandingOrders/LastPaymentDateTime | The 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
andtoStatementDateTime
- 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
Field | Description | Usage |
---|---|---|
AccountId | A unique identifier for the account being requested | Mandatory |
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
Field | Description | Mandatory | Options |
---|---|---|---|
Statements | An array of Statements | Yes | |
Statements/StatementId | A unique identifier for the statement (may be system-issued, not known to the account holder) | Yes | |
Statements/StartDateTime | Date and time at which the statement period starts (ISODateTime) | Yes | |
Statements/EndDateTime | Date and time at which the statement period ends (ISODateTime) | Yes | Transfer Card DirectDebit Misc |
Statements/CreationDateTime | Date and time at which the resource was created (ISODateTime) | Yes | |
Statements/StatementType | Statement type, in a coded form | Yes | AccountClosure AccountOpening Annual Interim RegularPeriodic |
Statements/Transactions | An array of transactions associated with a statement | No | |
Statements/Transactions/Amount | The transaction amount expressed as number with two or three decimal points e.g. 12.34 | Yes for each transaction | |
Statements/Transactions/Currency | Transaction currency in ISO 4217 three-letter code format | Yes for each transaction | |
Statements/Transactions/CreditDebit | Indicates if the transaction is a credit or a debit | Yes for each transaction | Credit Debit |
Statements/Transactions/AmountType | Amount type, in a coded form. | Yes for each transaction | ArrearsClosingBalance 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
Field | Description |
---|---|
AccountId | A unique identifier for the account being requested |
DebtorAccount | Identification 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 |
Amount | The amount due to be paid expressed as number with two or three decimal points e.g. 12.34 |
Currency | Payment currency in ISO 4217 three-letter code format |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
FundsAvailable | Confirmation of whether sufficient funds are currently available to successfully execute the payment expressed as a Boolean value | Yes | TRUE 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
Field | Description | Used Where Payment Type Is | Options |
---|---|---|---|
AccountId | A unique identifier for the account being requested | All Payment Types | |
PaymentType | Type of payment | All Payment Types | OBIE: - 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 |
DebtorIdentification | Identification 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 Types | OBIE -ProvidedDuringAuthorisation |
BeneficiaryIdentification | Identification of the beneficiary account | All Payment Types | |
BeneficiarySchemeName | The SchemeName of the BeneficiaryIdentification | All Payment Types | OBIE: - SortCodeAccountNumber - IBAN - CustomCodeNextGenPSD2: - IBAN - BBAN - MSISDN |
BeneficiaryName | Name of the beneficiary | All Payment Types | |
Amount | The amount due to be paid expressed as number with two or three decimal points e.g. 12.34 | OBIE: - Domestic - Domestic Scheduled - International - International ScheduledNextGenPSD2: - SEPA Credit Transfers - Instant SEPA Credit Transfers - Target 2 Payments - Cross Border Credit Transfers | |
Currency | Payment currency in ISO 4217 three-letter code format | OBIE: - Domestic - Domestic Scheduled - International - International ScheduledNextGenPSD2: - SEPA Credit Transfers - Instant SEPA Credit Transfers - Target 2 Payments - Cross Border Credit Transfers | |
ExecutionDateTime | Date at which the requestor would like the payment to be made | OBIE: - Domestic Scheduled - International Scheduled | |
Frequency | Frequency of the standing order | OBIE: - Domestic Standing Order - International Standing Order | See Frequency for details |
FirstPaymentAmount | The amount of the first Standing Order. This field will not always be provided | OBIE: - Domestic Standing Order - International Standing Order | |
FirstPaymentCurrency | The currency of the first Standing Order in ISO 4217 three-letter code format. This field will only be provided if FirstPaymentAmount is present | OBIE: - Domestic Standing Order - International Standing Order | |
FirstPaymentDateTime | The 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 present | OBIE: - Domestic Standing Order - International Standing Order | |
RecurringPaymentAmount | The amount of the recurring Standing Order | OBIE: - Domestic Standing Order - International Standing Order | |
RecurringPaymentCurrency | The currency of the recurring Standing Order in ISO 4217 three-letter code format | OBIE: - Domestic Standing Order - International Standing Order | |
FinalPaymentAmount | The amount of the final Standing Order. This field will not always be provided | OBIE: - Domestic Standing Order - International Standing Order | |
FinalPaymentCurrency | The currency of the final Standing Order in ISO 4217 three-letter code format. This field will only be provided if FinalPaymentAmount is present | OBIE: - Domestic Standing Order - International Standing Order | |
FinalPaymentDateTime | The 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 present | OBIE: - Domestic Standing Order - International Standing Order | |
CurrencyOfTransfer | The currency of the amount to be transferred in ISO 4217 three-letter code format, which is different from the currency of the debtor's account | OBIE: - International - International Scheduled - International Standing Order | |
EndToEndIdentification | Unique identification to unambiguously identify the transaction. This identification is immutable throughout the entire end-to-end chain. | OBIE: - Domestic - Domestic Scheduled - International - International Scheduled | |
Reference | Reference 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/Identification | Unique and unambiguous identification of a financial institution or a branch of a financial institution | OBIE: (Optional) - International - International Scheduled - International Standing Order | |
CreditorAgent/SchemeName | Name of the identification scheme. | OBIE: (Optional) - International - International Scheduled - International Standing Order | OBIE - BICFI - NCC.[ISO3166CountryCode] |
CreditorAgent/Name | Name by which an agent is known and which is usually used to identify that agent | OBIE: (Optional) - International - International Scheduled - International Standing Order | |
CreditorAgent/AddressLine | Information 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
Field | Description | Mandatory |
---|---|---|
PaymentReference | Unique identification assigned by your application to uniquely identify the payment | Yes |
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
Field | Description |
---|---|
AccountId | A unique identifier for the account being requested |
PaymentReference | Unique identification assigned by your application and returned as part of the POST /payment operation |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
PaymentStatus | Status of the payment | Yes | Pending 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
Field | Description | Options |
---|---|---|
AccountId | A unique identifier for the account being requested | |
DebtorAccount | Identification of the account of the debtor to which a confirmation of funds consent was applied. The type of identification is identified by DebtorSchemeName . | |
DebtorSchemeName | Name 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. |
Amount | The amount to confirm expressed as number with two or three decimal points e.g. 12.34 | |
Currency | Currency in ISO 4217 three-letter code format |
Response
Field | Description | Mandatory | Options |
---|---|---|---|
FundsAvailable | Confirmation of whether sufficient funds are currently available based on the value supplied, expressed as a Boolean value | Yes | TRUE 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))
Updated about 1 month ago