Authorisation

๐Ÿ“™

ACCOUNT PROVIDER 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

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.

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 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:

FieldData TypeDescription & Options
ConsentIdStringConsentId as per the requested resource
EnvironmentStringIndicates the environment in which the Consent was created.

- sandbox
- integration
- production
GatewayIdStringUUID of your Gateway
GatewayDomainStringDomain name of your Gateway
TppNameStringName of the TPP through which the Consent originated
TppWebsiteStringWebsite of the TPP through which the Consent originated
AppNameStringName of the TPPโ€™s App โ€“ a TPP may have multiple apps
AppDescriptionStringDescription of the TPPโ€™s App
AppWebsiteStringWebsite of the TPPโ€™s App
ConsentStatusString- 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
ScopeString- accounts
- payments
- fundsconfirmations
ConsentedAccountsArray[String]Array of Account IDs associated with the consent. This will be null until the consent is authorised.
ConsentedUserIdStringUser ID associated with the consent. This will be null until the consent is authorised.
PaymentTypeStringFor 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 (OBIE Only)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
- ReadStatementsDetailCode definitions can be found below.
Permissions (NextGenPSD2 Only)ObjectFor 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

- balancesCode definitions 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.
PaymentInformationObjectIf the scope is payments, this field contains an object with details of the payment being requested. The schema and examples of PaymentInformation can be found below.
ConsentRequestCreatedStringDate & 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)
ConsentRequestExpiryStringDate & time (UTC) that the consent request expires (or expired)
ConsentGrantedStringDate & time (UTC) that the consent was granted (this will be null when you make an initial check prior to carrying out SCA)
ConsentExpiryStringDate & time (UTC) that the consent expires / expired (this will be null when you make an initial check prior to carrying out SCA)
ConsentRevokedStringDate & 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.

For NextGenPSD2 gateways, you will need to also provide AccountIdMap array. This must strictly match the Permissions details returned in GET /consent/{ConsentId} with the ResourceId attached. For payments, an additional process is made where we make a POST /payment request to your Resource API. You will need to implement this resource first.

See API โ†— for full details.

Request

FieldDescription
ConsentIdConsentId as per the requested resource
OutcomeIndicates 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
UserIdMandatory 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
AccountsMandatory 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
AccountIdMapMandatory if using NextGenPSD2
Not applicable if using OBIE

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:

FieldDescription
LocationIf 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

CodeResourceDefinition
ReadAccountsBasicGET /account(s)The TPP can make requests and will not see identifiable details of an account nor its account servicer.
ReadAccountsDetailGET /account(s)The TPP can make requests and will see identifiable details of an account and its account servicer.
ReadBalancesGET /balanceThe TPP can make requests and read balances.
ReadBeneficiariesBasicGET /beneficiariesThe TPP can make requests and will not see identifiable details of a beneficiary account nor its account servicer.
ReadBeneficiariesDetailGET /beneficiariesThe TPP can make requests and will see identifiable details of a beneficiary account and its account servicer.
ReadDirectDebitsGET /direct-debitsThe TPP can make requests and read direct debits.
ReadScheduledPaymentsBasicGET /direct-debitsThe TPP can make requests and will not see identifiable details of a creditor account nor its account servicer.
ReadScheduledPaymentsDetailGET /scheduled-paymentsThe TPP can make requests and will see identifiable details of a creditor account and its account servicer.
ReadTransactionsBasicGET /transactionsThe TPP can make requests and will not see the balance, merchant details, creditor accounts, and debtor accounts.
ReadTransactionsDetailGET /transactionsThe TPP can make requests and will see balance, merchant details, creditor accounts, and debtor accounts.
ReadTransactionsCreditsGET /transactionsThe TPP can make requests and will see credit transactions.
ReadTransactionsDebitsGET /transactionsThe TPP can make requests and will see debit transactions.
ReadStatementsBasicGET /statementsThe TPP can make requests and will not see statement amounts.
ReadStatementsDetailGET /statementsThe TPP can make requests and will see statement amounts.
ReadStandingOrdersBasicGET /standing-ordersThe TPP can make requests and will not see creditor accounts.
ReadStandingOrdersDetailGET /standing-ordersThe TPP can make requests and will see creditor accounts.

NextGenPSD2 Permissions

CodeResourceDefinition
accountsGET /account(s)The TPP can make requests and will see all data including identifiable details of an account and its account servicer.
transactionsGET /transactionsThe TPP can make requests and will see all data including balance, merchant details, creditor accounts, and debtor accounts.
balancesGET /balanceThe TPP can make requests and read balances.

Payment Information Schemas

OBIE (All PIS Payments)

Specification

FieldData TypeUsed Where Payment Type IsDescription & Options
InstructionIdentificationStringAll Payment TypesUnique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction
EndToEndIdentificationStringAll Payment TypesUnique 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/AmountString- 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/CurrencyString- Domestic
- Domestic Scheduled
- International
- International Scheduled
- International Standing Order
Payment currency of debtor in ISO 4217 three-letter code format
CreditorAccount/SchemeNameStringAll 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/IdentificationStringAll Payment TypesIdentification of the creditor account. Format is dependent on SchemeName
CreditorAccount/NameStringAll Payment TypesName of the creditor account
CurrencyOfTransferString- International
- International Scheduled
- International Standing Order
Payment currency of creditor in ISO 4217 three-letter code format
RequestedExecutionDateTimeString- Domestic Scheduled
- International Scheduled
Date at which the requestor would like the payment to be made
FrequencyString- Domestic Standing Order
- International Standing Order
Frequency of the standing order

See Resources for details
FirstPaymentDateTimeString- 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/AmountString- Domestic Standing OrderThe amount of the first Standing Order. This field will not always be provided
FirstPaymentAmount/CurrencyString- Domestic Standing OrderThe currency of the first Standing Order in ISO 4217 three-letter code format. This field will only be provided if FirstPaymentAmount is present
RecurringPaymentAmount/AmountString- Domestic Standing OrderThe amount of the recurring Standing Order expressed as number with two or three decimal points e.g. 12.34
RecurringPaymentAmount/CurrencyString- Domestic Standing OrderThe currency of the recurring Standing Order in ISO 4217 three-letter code format
RemittanceInformation/ReferenceString(Optional) All Payment TypesReference 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

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

"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"
}
"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"
  },
"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 service is separate to PIS.

Specification

FieldData TypeRequired?Description & Options
ExpirationDateTimeStringNoSpecified date and time the funds confirmation authorisation will expire. If this is not populated, the authorisation will be open ended.
DebtorAccount/IdentificationStringYesIdentification of the account. Format is dependent on SchemeName.
DebtorAccount/NameStringNoName of the account.
DebtorAccount/SchemeNameStringYes- UK.OBIE.SortCodeAccountNumber
- UK.OBIE.IBAN
If SchemeName is SortCodeAccountNumber, the identification will be a concatenated sort-code followed by account number.
DebtorAccount/SecondaryIdentificationStringNoThis 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

"DebtorAccount": {
    "SchemeName": "UK.OBIE.SortCodeAccountNumber",
    "Identification": "12345612345678"
}

NextGenPSD2

Specification

* Account identifier for creditorAccount and debtorAccount will be one of iban, bban, or msisdn.

FieldData TypeUsed Where Payment Type IsDescription & Options
endToEndIdentificationStringOptional 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/currencyStringAll Payment TypesPayment currency of debtor in ISO 4217 three-letter code format.
instructedAmount/amountStringAll Payment TypesThe 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*StringAll Payment TypesIBAN of the debtor account.
debtorAccount/bban*StringAll Payment TypesBasic 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*StringAll Payment TypesMobile Station International Subscriber Directory Number (MSISDN) of the debtor account.

Unique number that identifies a mobile subscriber.
creditorAccount/iban*StringAll Payment TypesIBAN of the creditor account.
creditorAccount/bban*StringAll Payment TypesBasic 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*StringAll Payment TypesMobile Station International Subscriber Directory Number (MSISDN) of the creditor account.

Unique number that identifies a mobile subscriber.
creditorAgentStringOptional for:

- All Payment Types
BICFI.

Pattern: [A-Z]{6,6}[A-Z2-9][A-NP-Z0-9]([A-Z0-9]{3,3}){0,1}
creditorNameStringOptional for:

- All Payment Types
Name of the creditor account.
creditorAddressStringOptional for:

- All Payment Types
Address of the creditor account.
chargerBearerOptional 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.
remittanceInformationUnstructuredStringOptional for:

- All Payment Types
Unstructured remittance information.