### ACCOUNT PROVIDER GUIDE ##### 🤔 [Is this the right developer guide for me?](doc:which-guide) This section describes the standard journey for authorising an Account Holder consent. Contact us if you would like to discuss customised or outsourced alternatives. # Consent Flow ![](https://files.readme.io/9613e80-image.png) # Initiation To access account data or or initiate a payment on behalf of an Account Holder, a Third Party Provider starts by initiating a **consent**. The Third Party Provider calls the **tell.**gateway API to verify its credentials and permissions, generate a consent request, and obtain an authorisation URL (we take care of all of that – no action required by you). With a valid request in place, the Account Holder is redirected to Authorisation Service URL you have configured for the Gateway (see Configuration for more information). *** # Your Implementation To implement Authorisation you will need to build an **Authorisation Service**, or adapt an existing part of your application, as described in the process steps below. ![](https://files.readme.io/18803f5-Authorisation_Image.png "Authorisation Image.png") ## 1. Extract ConsentId When the Account Holder arrives at your Authorisation Service you should begin by extracting the ConsentId from the querystring. For example, if your Authorisation Service is located at: ``` https://your-bank.com/tell-gateway ``` then the Account Holder will be redirected to: ``` https://your-bank.com/tell-gateway?ConsentId={ConsentId}&CallbackURL={CallbackURL} ``` so you will need to extract the value of **ConsentId**. Store this locally within your application as you will need to use it in a moment. > 🚧 CallbackURL Path Parameter > > This is **only** used in the event you're unable to retrieve a valid location from the [Post Result](#5-post-result) step towards the end of this process, so that you will always have a location to redirect the user back to. > > Navigating to the CallbackURL will automatically decline the consent request. *** ## 2. Authenticate (SCA) The tell.gateway service is never aware of who an Account Holder is. We do not receive, process or store any customer information for reasons of security and confidentiality. At this stage in the process, the Account Holder has not yet authenticated themselves, so now that they have arrived at your application, you should perform SCA checks to authenticate and verify the identity of the individual. *** ## 3. Get Consent Information Next, call the **GET /consent/\{ConsentId}** endpoint using the ConsentId. This will return all data associated with the consent. See API ↗. You can use this call at any time to retrieve data relating to a Consent. However at this stage in the process you should only proceed if the **ConsentStatus** is **AwaitingAuthorisation**. _Response:_

Field	Data Type	Description & Options
ConsentId	String	ConsentId as per the requested resource
Environment	String	Indicates the environment in which the Consent was created. * sandbox * integration * production
GatewayId	String	UUID of your Gateway
GatewayDomain	String	Domain name of your Gateway
TppName	String	Name of the TPP through which the Consent originated
TppWebsite	String	Website of the TPP through which the Consent originated
AppName	String	Name of the TPP’s App – a TPP may have multiple apps
AppDescription	String	Description of the TPP’s App
AppWebsite	String	Website of the TPP’s App
ConsentStatus	String	* AwaitingAuthorisation – consent is awaiting authorisation * AwaitingExchange – consent granted, awaiting TPP token exchange * AuthorisationDeclined – consent has been rejected * Authorised – consent granted and active * Revoked – consent has been revoked by account holder * Expired – consent has expired * Consumed – payment request has completed
Scope	String	* accounts * payments * fundsconfirmations
ConsentedAccounts	Array[String]	Array of Account IDs associated with the consent. This will be `null` until the consent is authorised.
ConsentedUserId	String	User ID associated with the consent. This will be `null` until the consent is authorised.
PaymentType	String	For payments, this field indicates the type of payment being consented to. 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
Permissions (OBIEOnly)	Array[String]	For accounts, this field will be populated with an array of permissions that the Consent relates to (you do not need to handle this any differently based on the list of Permissions as we take care of that, you just need to display this to the account holder, so they are fully aware of what they are consenting to) * ReadAccountsBasic * ReadAccountsDetail * ReadBalances * ReadBeneficiariesBasic * ReadBeneficiariesDetail * ReadDirectDebits * ReadScheduledPaymentsBasic * ReadScheduledPaymentsDetail * ReadTransactionsBasic * ReadTransactionsCredits * ReadTransactionsDebits * ReadTransactionsDetail * ReadStatementsBasic * ReadStatementsDetail[Code definitions](#permissions) can be found below.
Permissions (NextGenPSD2Only)	Object	For accounts, this field will be populated with an array of objects. The field name of the array denotes the level of access for the account provided within the array. This will be any one of the following: * `accounts` * `transactions` * `balances`[Code definitions](#permissions-1) can be found below.Each object within the array will contain the following strings: * `AccountId` * `AccountType` - One of: IBAN, BBAN, MSISDN * `currency` - Optional: ISO 4217 Alpha-3You will need to display the account information to the account holder along with the scope of access being requested for each account, so they are fully aware of what they are consenting to.
PaymentInformation	Object	If the scope is payments, this field contains an object with details of the payment being requested. The [schema and examples of PaymentInformation](#payment-information-schemas) can be found below.
ConsentRequestCreated	String	Date & time (UTC) that the consent request was created (NB this relates to the consent request, not the consent itself – a consent request must be completed within a defined period for security reasons)
ConsentRequestExpiry	String	Date & time (UTC) that the consent request expires (or expired)
ConsentGranted	String	Date & time (UTC) that the consent was granted (this will be null when you make an initial check prior to carrying out SCA)
ConsentExpiry	String	Date & time (UTC) that the consent expires / expired (this will be null when you make an initial check prior to carrying out SCA)
ConsentRevoked	String	Date & time (UTC) that the consent was revoked by the account holder (this will be null when you make an initial check prior to carrying out SCA or if the consent has not been revoked)

*** ## 4. Show consent & Approval Using the data returned above, you should present the Account Holder with a page displaying the information and prompting them to review and accept / reject it. For OBIE, the permissions provided will be for the consent itself. This means the Account Holder will be granting these permissions to all accounts selected during the authorisation process. You will need to allow the Account Holder to select which accounts they would like to grant access to. For NextGenPSD2, the permissions provided will be mapped against an account rather than against a consent as a whole. The accounts and their permissions will have already been provided when the Third Party Provider generates the consent, supplied by the PSU. In this instance, the PSU will be confirming the information supplied during the consent, therefore no account selection is required. ### ❯ Account Information If the scope is **accounts**, you should present the Account Holder with a list of all accounts that they have access to and allow them to select one or more. This allows us to tie the consent to a specific set of accounts and allows the account holder to limit the access. If they only have one account then you do not need to display this list, but you will still need to provide us with the AccountId in the next stage. ### ❯ Payment Initiation & Funds Confirmation If the request is for a **payment** or **fundsconfirmation**, you should also present the Account Holder with a list of accounts, but they may only select one account from the list. This indicates the accounts from which the payment will be debited, or against which the confirmation of funds will be performed. If the request is for a payment, please ensure that you display the full PaymentInformation object so the account holder can review and verify that the details are correct. At this stage you can optionally verify that you would accept this payment, but this is not essential. **You should not execute the payment at this stage** (that will come later). *** ## 5. Post Result After completing the authentication process, send the outcome to our **POST /consent** endpoint. This allows you to indicate if the request was successful (or not) and to provide a UserId and Accounts array. A UserId can be any id from your system which we will use to identify that account holder in the future. **ForNextGenPSD2 gateways**, you will need to also provide AccountIdMap array. This must strictly match the Permissions details returned in [GET /consent/\{ConsentId}](#3-get-consent-information) with the ResourceId attached. For payments, an additional process is made where we make a [POST /payment](doc:resources#-post-payment) request to your Resource API. **You will need to implement this resource first**. See API ↗ for full details. _Request_

Field	Description
ConsentId	ConsentId as per the requested resource
Outcome	Indicates if the account holder authentication has been successful and the consent has been accepted (“Pass”) or if either the authentication has failed, or the account holder has rejected the consent request (“Fail”). * Pass * Fail
UserId	Mandatory if Outcome is Pass. A unique ID for your account holder. This is the ID we will use in future interaction to request access to resources or to initiate a payment. We treat this as a string so can be in any format
Accounts	Mandatory if Outcome is Pass. An array of AccountIds which the account holder has approved for the consent. If the request is for a payment or fundsconfirmation, there must only be one account provided in the array. An AccountId is an identifier known to the account holder. This value (or values) will be stored by Tell against the consent and will be used to pre-validate any requests against the Consent. We treat an AccountId as a string so can be in any format
AccountIdMap	Mandatory if usingNextGenPSD2 _Not applicable if usingOBIE_ An array of resource IDs identifiable to yourselves, matched against the account identifiers that the PSU has provided consent for. N.B. Only the account identifiers provided in the consent can be provided in this array. All resource IDs in this array must match the account IDs provided in the `Accounts` field described above.

_Response:_ | Field | Description | | :------- | :--------------------------------------------------------------------------------------------------------------- | | Location | If applicable, this will contain a URL to which you should redirect the account holder (see Wrap up for details) | *** ## 6. Wrap up On completion of the step above, you will have received a response value of Location. If this field is populated with a URL, you should redirect the account holder back to the URL provided. If value is "na" then no need to do anything - just display a friendly "all done" message and prompt the account holder to go back to the third party provider site to continue their journey. This variation is designed to support different journeys i.e. if the account holder began on a different device. *** # Permission Code Definitions ## OBIE Permissions | Code | Resource | Definition | | :-------------------------- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------ | | ReadAccountsBasic | GET /account(s) | The TPP can make requests and will **not** see identifiable details of an account nor its account servicer. | | ReadAccountsDetail | GET /account(s) | The TPP can make requests and **will see** identifiable details of an account and its account servicer. | | ReadBalances | GET /balance | The TPP can make requests and read balances. | | ReadBeneficiariesBasic | GET /beneficiaries | The TPP can make requests and will **not** see identifiable details of a beneficiary account nor its account servicer. | | ReadBeneficiariesDetail | GET /beneficiaries | The TPP can make requests and **will see** identifiable details of a beneficiary account and its account servicer. | | ReadDirectDebits | GET /direct-debits | The TPP can make requests and read direct debits. | | ReadScheduledPaymentsBasic | GET /direct-debits | The TPP can make requests and will **not** see identifiable details of a creditor account nor its account servicer. | | ReadScheduledPaymentsDetail | GET /scheduled-payments | The TPP can make requests and **will see** identifiable details of a creditor account and its account servicer. | | ReadTransactionsBasic | GET /transactions | The TPP can make requests and will **not** see the balance, merchant details, creditor accounts, and debtor accounts. | | ReadTransactionsDetail | GET /transactions | The TPP can make requests and **will see** balance, merchant details, creditor accounts, and debtor accounts. | | ReadTransactionsCredits | GET /transactions | The TPP can make requests and will see credit transactions. | | ReadTransactionsDebits | GET /transactions | The TPP can make requests and will see debit transactions. | | ReadStatementsBasic | GET /statements | The TPP can make requests and will **not** see statement amounts. | | ReadStatementsDetail | GET /statements | The TPP can make requests and **will see** statement amounts. | | ReadStandingOrdersBasic | GET /standing-orders | The TPP can make requests and will **not** see creditor accounts. | | ReadStandingOrdersDetail | GET /standing-orders | The TPP can make requests and **will see** creditor accounts. | ## NextGenPSD2 Permissions | Code | Resource | Definition | | :----------- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------ | | accounts | GET /account(s) | The TPP can make requests and **will see** all data _including_ identifiable details of an account and its account servicer. | | transactions | GET /transactions | The TPP can make requests and **will see** all data _including_ balance, merchant details, creditor accounts, and debtor accounts. | | balances | GET /balance | The TPP can make requests and read balances. | # Payment Information Schemas ## OBIE (All PIS Payments) ### Specification

Field	Data Type	Used Where Payment Type Is	Description & Options
InstructionIdentification	String	All Payment Types	Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction
EndToEndIdentification	String	All Payment Types	Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain
InstructedAmount/Amount	String	* Domestic * Domestic Scheduled * International * International Scheduled * International Standing Order	The amount due to be paid expressed as number with two or three decimal points e.g. 12.34
InstructedAmount/Currency	String	* Domestic * Domestic Scheduled * International * International Scheduled * International Standing Order	Payment currency of debtor in ISO 4217 three-letter code format
CreditorAccount/SchemeName	String	All Payment Types	* UK.OBIE.SortCodeAccountNumber * UK.OBIE.IBAN * UK.OBIE.BBAN * UK.OBIE.CustomCodeIf SchemeName is SortCodeAccountNumber, the identification will be a concatenated sort-code followed by account number. If using CustomCode, identification is whatever is known to your account holder
CreditorAccount/Identification	String	All Payment Types	Identification of the creditor account. Format is dependent on SchemeName
CreditorAccount/Name	String	All Payment Types	Name of the creditor account
CurrencyOfTransfer	String	* International * International Scheduled * International Standing Order	Payment currency of creditor in ISO 4217 three-letter code format
RequestedExecutionDateTime	String	* Domestic Scheduled * International Scheduled	Date at which the requestor would like the payment to be made
Frequency	String	* Domestic Standing Order * International Standing Order	Frequency of the standing order See Resources for details
FirstPaymentDateTime	String	* Domestic Standing Order * International Standing Order	The date on which the first payment for a Standing Order schedule will be made in ISODateTime format.
FirstPaymentAmount/Amount	String	* Domestic Standing Order	The amount of the first Standing Order. This field will not always be provided
FirstPaymentAmount/Currency	String	* Domestic Standing Order	The currency of the first Standing Order in ISO 4217 three-letter code format. This field will only be provided if FirstPaymentAmount is present
RecurringPaymentAmount/Amount	String	* Domestic Standing Order	The amount of the recurring Standing Order expressed as number with two or three decimal points e.g. 12.34
RecurringPaymentAmount/Currency	String	* Domestic Standing Order	The currency of the recurring Standing Order in ISO 4217 three-letter code format
RemittanceInformation/Reference	String	* _(Optional)_* All Payment Types	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.

### Domestic Payment Examples ```json Domestic "PaymentInformation": { "InstructionIdentification": "c3f57611-58db-4f99-b5b4-d055f3", "EndToEndIdentification": "cd8bf3cf-a016-4281-803a-91c4d6", "InstructedAmount": { "Amount": "1.23", "Currency": "GBP" }, "CreditorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Name": "Joe Bloggs", "Identification": "12345612345678" } } ``` ```json Domestic Scheduled "PaymentInformation": { "InstructionIdentification": "d59b1fe6-e3b0-4278-9677-915303", "EndToEndIdentification": "1c23ab00-a788-4a04-bf37-96ce1b", "InstructedAmount": { "Amount": "1.23", "Currency": "GBP" }, "CreditorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Name": "Joe Bloggs", "Identification": "12345612345678" }, "RequestedExecutionDateTime": "2023-07-21T11:20:21+00:00" }, ``` ```json Domestic Standing Order "PaymentInformation": { "InstructionIdentification": "5c861bad-9adf-443a-87dc-ce5880", "EndToEndIdentification": "b9da5c36-e34c-43ea-9777-2432f3", "CreditorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Name": "Joe Bloggs", "Identification": "12345612345678" }, "Frequency": "EvryDay", "FirstPaymentDateTime": "2023-07-21T11:20:21+00:00", "FirstPaymentAmount": { "Amount": "1.23", "Currency": "GBP" }, "RecurringPaymentAmount": { "Amount": "1.23", "Currency": "GBP" } }, ``` ### International Payment Examples ```json International "PaymentInformation": { "InstructionIdentification": "c3f57611-58db-4f99-b5b4-d055f3", "EndToEndIdentification": "cd8bf3cf-a016-4281-803a-91c4d6", "InstructedAmount": { "Amount": "1.23", "Currency": "GBP" }, "CreditorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Name": "Joe Bloggs", "Identification": "12345612345678" }, "CurrencyOfTransfer": "EUR" } ``` ```json International Scheduled "PaymentInformation": { "InstructionIdentification": "154b7d24-e75f-4ba9-b641-379481", "EndToEndIdentification": "137eb1a3-bd8a-4a2e-8d3d-8c32ea", "InstructedAmount": { "Amount": "1.23", "Currency": "GBP" }, "CreditorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Name": "Joe Bloggs", "Identification": "12345612345678" }, "CurrencyOfTransfer": "EUR", "RequestedExecutionDateTime": "2023-07-21T11:20:21+00:00" }, ``` ```json International Standing Order "PaymentInformation": { "InstructionIdentification": "c769b34c-ea75-4257-8a7b-efbe8e", "EndToEndIdentification": "6d61a958-b811-455a-bcd0-dd213f", "InstructedAmount": { "Amount": "1.23", "Currency": "GBP" }, "CreditorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Name": "Joe Bloggs", "Identification": "12345612345678" }, "CurrencyOfTransfer": "EUR", "Frequency": "EvryDay", "FirstPaymentDateTime": "2023-07-21T11:20:21+00:00" }, ``` ## OBIE - (CBPII Funds Confirmation) This is a specification of the `PaymentInformation` when the consent type is of `"fundsconfirmation"`. **Note:** [CBPII Funds Confirmation](resources#❯-post-funds-confirmation) service is separate to PIS. ### Specification

Field	Data Type	Required?	Description & Options
ExpirationDateTime	String	No	Specified date and time the funds confirmation authorisation will expire. If this is not populated, the authorisation will be open ended.
DebtorAccount/Identification	String	Yes	Identification of the account. Format is dependent on SchemeName.
DebtorAccount/Name	String	No	Name of the account.
DebtorAccount/SchemeName	String	Yes	* UK.OBIE.SortCodeAccountNumber * UK.OBIE.IBAN If SchemeName is SortCodeAccountNumber, the identification will be a concatenated sort-code followed by account number.
DebtorAccount/SecondaryIdentification	String	No	This is secondary identification of the account, as assigned by the account servicing institution. This can be used by building societies to additionally identify accounts with a roll number (in addition to a sort code and account number combination).

### Example ```json "DebtorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Identification": "12345612345678" } ```
## NextGenPSD2 ### Specification ***** Account identifier for creditorAccount and debtorAccount will be **one of** `iban`, `bban`, or `msisdn`.

Field	Data Type	Used Where Payment Type Is	Description & Options
endToEndIdentification	String	Optional for: * SEPA Credit Transfer * SEPA Instant Credit Transfer * Target2Not available for: * Cross Border Credit Transfer	Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction.
instructedAmount/currency	String	All Payment Types	Payment currency of debtor in ISO 4217 three-letter code format.
instructedAmount/amount	String	All Payment Types	The amount given with fractional digits, where fractions must be compliant to the currency definition. Up to 14 significant figures. The decimal separator is a dot. Pattern: `[0-9]{1,14}(\.[0-9]{1,3})?`
debtorAccount/iban*****	String	All Payment Types	IBAN of the debtor account.
debtorAccount/bban*****	String	All Payment Types	Basic Bank Account Number (BBAN) of the debtor account. Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer.
debtorAccount/msisdn*****	String	All Payment Types	Mobile Station International Subscriber Directory Number (MSISDN) of the debtor account. Unique number that identifies a mobile subscriber.
creditorAccount/iban*****	String	All Payment Types	IBAN of the creditor account.
creditorAccount/bban*****	String	All Payment Types	Basic Bank Account Number (BBAN) of the creditor account. Identifier used nationally by financial institutions, i.e., in individual countries, generally as part of a National Account Numbering Scheme(s), which uniquely identifies the account of a customer.
creditorAccount/msisdn*****	String	All Payment Types	Mobile Station International Subscriber Directory Number (MSISDN) of the creditor account. Unique number that identifies a mobile subscriber.
creditorAgent	String	Optional for: * All Payment Types	BICFI. Pattern: `[A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}`
creditorName	String	Optional for: * All Payment Types	Name of the creditor account.
creditorAddress	String	Optional for: * All Payment Types	Address of the creditor account.
chargerBearer		Optional for: * Target2 * Cross Border Credit TransferNot available for: * SEPA Credit Transfer * SEPA Instant Credit Transfer	* DEBT _The Payer (sender of the payment) will bear all of the payment transaction fees_ * CRED _The Payee (recipient of the payment) will incur all of the payment transaction fees_ * SHAR _The Payer (sender of the payment) will pay all fees charged by the sending bank & the Payee (recipient of the payment) will pay all fees charged by the receiving bank_ * SLEV * As above, (same as SHAR) – the only option available for SEPA credit transfers_Specifies which party will bear the charges associated with the processing of the payment transaction.
remittanceInformationUnstructured	String	Optional for: * All Payment Types	Unstructured remittance information.