📙

ACCOUNT PROVIDER GUIDE

🤔 Is this the right developer guide for me?

🎨

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:

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

Response:

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

NextGenPSD2 Permissions

Payment Information Schemas

OBIE (All PIS Payments)

Specification

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

Example

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

NextGenPSD2

Specification

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