Guide to using Lloyds banking Group APIs
In this Article
INTRODUCTION
BACKGROUND
There is currently no standardised way for ASPSPs to communicate the differences in ASPSP implementations.
This covers both:
- Differences in on-boarding and directory interactions
- Differences in capability delivered for the Read/Write APIs
The above can generate challenges to TPPs as they will not know:
- What processes to follow in order to onboard with each ASPSP
- Which API endpoints they can call
- What data elements they can receive from different ASPSPs, and for unstructured data - what format they receive it
Furthermore, TPPs have different sets of requirements for the Read/Write APIs. This is because of their business models, applications and service offerings. Therefore TPPs need the ability to identify which ASPSP implementations are suitable match to their offerings. This will ensure they can offer a good end user experience.
PURPOSE OF THIS DOCUMENT
This Implementation Variations Guide outlines the variations in Lloyds Banking Group’s Open Banking API endpoint and API response implementation. Information contained within this document aims to make the development of applications by TPPs using Read/Write APIs faster and easier.
COMPLETING AN END-TO-END API JOUNEY
This section explains how to on-board onto the Lloyds Banking Group Developer Portal and how to complete an end-to-end API journey. In this instance the example used is an Account Information API journey.
ON-BOARD ONTO THE DEVELOPER PORTAL
-
Log into the Developer Portal by clicking the 'Log in with Openbanking' button on the top right of the portal. You will need to have logon credentials for a company listed on the Open Banking Production Directory. When you log in, your user is placed into a new Developer Organization corresponding to your company (or it will add you to the organization if it already exists).
-
To use our APIs, you must have an application, which is effectively a Client ID and Client Secret (these are used to identify who is calling our APIs). To create an application, click on 'Apps' in the menu bar and then click 'Create new App'.
-
When creating your new application, give it a name and a description. You must also provide a Software Statement Assertion (SSA), which can be obtained from the Open Banking Directory. Your SSA will expire 24 hours after it is issued to you, so make sure you create the application when the SSA is still valid. If you use an SSA after it has expired, you will be presented with an error message. Once the application is created, you will be issued a Client ID & Client Secret and in the next 5 minutes the list of products will be subscribed to the app. You will be subscribed to the required products based on the Software roles in the SSA and to view the list of products subscribed, please visit the Apps page and select the newly created app.
-
Once the subscription is completed, you can now test the APIs.
OTHER USEFUL INFORMATION
-
Access our consent domains from browser :
https://authorise.lloydsbank.co.uk/ib/pb/cwa/404
https://authorise.halifax-online.co.uk/ib/pb/cwa/404m
https://authorise.bankofscotland.co.uk/ib/pb/cwa/404
https://authorise.mbna.co.uk/ib/pb/cwa/404 -
Our APIs themselves all sit behind the following domains – these are over MA-TLS – so we would like you to try presenting your OB-signed client cert against these to validate the SSL handshake is working as expected (e.g. by using an appropriate openSSL command, in chrome etc.).
https://secure-api.lloydsbank.com
https://secure-api.halifax.co.uk
https://secure-api.bankofscotland.co.uk
https://secure-api.mbna.co.uk -
Our APIs themselves all sit behind the following domains – these are over MA-TLS – so you will be required to present your eIDAS QWAC client cert against these to validate the SSL handshake is working as expected (e.g. by using an appropriate openSSL command, in chrome etc.).
https://secure-api-eidas.lloydsbank.com/
https://secure-api-eidas.halifax.co.uk/
https://secure-api-eidas.bankofscotland.co.uk/
https://secure-api-eidas.mbna.co.uk/The list of supported QTSPs is available in the OBIE Transparency Calendar –
https://openbanking.atlassian.net/wiki/spaces/AD/pages/1130594843/Lloyds+Bank+PLC
-
Discovery Endpoints (OBIE) – Client Secret Basic and Client Secret Post
BrandDiscovery Endpoint (OBIE)LloydsHalifaxBOSPersonal
Business
https://authorise-api.lloydsbank.co.uk/prod01/channel/lyds/business/.well-known/openid-configuration
Commercial
-
Discovery Endpoints (OBIE) – TLS Client Auth
BrandDiscovery Endpoint (OBIE)LloydsPersonal
Business
Commercial
HalifaxBOSPersonal
Business
Commercial
-
Discovery Endpoints (eIDAS) - Client Secret Basic and Client Secret Post
BrandDiscovery Endpoint (eIDAS)LloydsPersonal
Business
Commercial
HalifaxBOSPersonal
Business
Commercial
-
Discovery Endpoints (eIDAS) - TLS Client Auth
BrandDiscovery Endpoint (eIDAS)LloydsPersonal
Business
Commercial
HalifaxBOSPersonal
Business
Commercial
"token_endpoint_auth_methods_supported": ["client_secret_basic","client_secret_post"]
"token_endpoint_auth_methods_supported":["tls_client_auth"]
Please note that as part of token end point call, the Client ID should not be populated in the body of the request.
-
We support Refresh Tokens for fundsconfirmations, accounts, payments (only VRP) scopes.
-
Lloyds Banking Group’s Public Keys are available at the Keystore set up by Open Banking Ltd.
-
All APIs are secured with TLS Mutual Authentication where Certs are signed by Open Banking CA.
-
We do not support JWS client assertion. Please use your client ID and client secret in the basic auth header.
-
Nonce String Limit: When submitting an AISP or PISP request, the maximum length a nonce string can be is 100 characters. Beyond this, the consent will not be activated.
-
As part of our implementation we support registration of an application with multiple Oauth redirect URLs. TPPs can register multiple redirect URLs when creating an application on the Developer Portal, however once an application has been created and the Client ID and Client Secret generated it cannot be amended and additional redirect URLs cannot be added.
-
For digital signatures we will support PS256 from 13th March 2019, please see Discovery Endpoints for more information. The digital signatures generated by LBG will only use PS256.
TESTING THE ACCOUNT INFORMATION APIS
-
Set up Client Credentials Token
In this step you (the AISP) obtain an Access Token using a Client Credentials Grant Type. When an Access Token expires, you will need to re-request for another Access Token.
For Authentication methods - client_secret_basic and client_secret_post:
curl -k -X POST
--key ./private-cert.key \
--cert ./public-cert.pem \
--cacert ./ca-cert.pem \
--url {secure-domain}/prod01/lbg/lyds/oidc-api/v1.1/token \
--header 'accept: application/json' \
--header 'cache-control: no-cache' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials&client_id=c1d81a9a-609a-47be-9363-8fa038b987da&client_secret=qJ4dE5yO6xK2oM0fQ5wR0tF4kV0uL4xR5kO6dB7dJ4iU7qI0yB&scope=accounts'
For Authentication method - tls_client_auth:
curl -k -X POST \
--key ./private-cert.key \
--cert ./public-cert.pem \
--cacert ./ca-cert.pem \
--url {secure-domain}/ prod01/lbg/lyds/mtls-token-api/v1.1/token\
--header 'accept: application/json' \
--header 'cache-control: no-cache' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=client_credentials&client_id=c1d81a9a-609a-47be-9363-8fa038b987da& scope=accounts'
URL
Parameter: secure-domainDescription:
Please refer to the Other Useful Information section for all brand specific domains
Certs
Parameter: CACertExample Value:
Combination of Root & Intermediate
Description:
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Data
Parameter: grant_typeExample Value:
client_credentials
Description:
The grant type being requested
Parameter: client_idExample Value:
c1d81a9a-609a-47be-9363- 8fa038b987da
Description:
The Client ID of your application registered in the developer portal
Parameter: client_secretExample Value:
qJ4dE5yO6xK2oM0fQ5wR0tF 4kV0uL4xR5kO6dB7dJ4iU7qI0 yB
Description:
The Client Secret of your application registered in the developer portal,its not required for tls_client_auth method
Parameter: scopeExample Value:
accounts
Description:
The scope being requested
-
Invoke the Account Request API
Using the Access Token obtained in the step 1, invoke the Accounts API.
curl -k -v --request POST \
--key ./private-cert.key \
--cert ./public-cert.pem \
--cacert ./root-ca.pem \
--compressed \
--url {secure-domain}/prod01/lbg/lyds/open-banking/v3.1/aisp/account-access-consents \
--header 'authorization: Bearer AAIkMDM5NDJmZTUtOGNiMi00NzVmLWIwMTItNDgyZjM0ZTExYzI5ujAPRjg9HCsXYdEx15e-1h8ZdUQvTtI2Q3lkxQl3tv3n1zVlTnK0jbC1xzhnx6XRH7KBbLCr8qzYUBN0pGDSjdKGgYfFw5om5YF zRrq7j4I8_b6KSlgZ1F4Cs7SvpLLJmHSKL0tGPIA0VSsaAyHilg' \
--header 'content-type: application/json; charset=UTF-8' \
--header 'x-fapi-customer-ip-address: REPLACE_THIS_VALUE' \
--header 'x-fapi-customer-last-logged-time: REPLACE_THIS_VALUE' \
--header 'x-fapi-financial-id: REPLACE_THIS_VALUE' \
--header 'x-fapi-interaction-id: REPLACE_THIS_VALUE' \
--header 'x-jws-signature: REPLACE_THIS_VALUE' \
--data '{"Data":{"Permissions":["ReadBeneficiariesBasic"],"ExpirationDateTime":"2018-08-28T15:39:19.515Z","TransactionFromDateTime":"2016-04-02T11:59:32.044Z","TransactionToDateTime":"2017-07-16T17:59:09.521Z"},"Risk":{}}'
URL
Parameter: secure-domainDescription:
Please refer to the Other Useful Information section for all brand specific domains
Headers
Parameter: authorizationExample Value:
Bearer
AAIkMDM5NDJmZTUtOGNiMi00NzVmL WIwMTItNDgyZjM0ZTE........Description:
The access token obtained in step 1
Certs
Parameter: CACertExample Value:
Combination of Root & Intermediate
Description:
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Body
Parameter: DataExample Value:
{"Data":{"Permissions":["ReadBeneficiarie sBasic"],"ExpirationDateTime":"2010-08- 28T15:39:19.515Z","TransactionFromDat eTime":"2016-04- 02T11:59:32.044Z","TransactionToDateTi me":"2017-07- 16T17:59:09.521Z"},"Risk":{}}
Description:
The permissions being requested
Please refer here for a full list of the allowed permissions.
Take note of the AccountRequestID in the response data. This is required in the next step.
-
Authorize Consent
In this step, you create the authorization request (using a signed JWT request containing the AccountRequestId as a claim) for the customer to consent to the account request directly with the ASPSP. Hybrid Flow support is optional in the OB Security Profile.
Using a web browser, invoke the URL below to emulate the customer giving consent (changing the values as required).
Please note for App to App the same consent authorisation endpoints are used. Please refer to section 7 for a full list of Consent Authorisation URLs and Section 9 for an overview of App to App.
URL Parameters
Parameter: response_typeExample Value:
code id_token
Description:
The OAuth flow type being used
Parameter: client_idExample Value:
c1d81a9a-609a-47be-9363-8fa038b987da
Description:
The Client ID of your application registered in the developer portal
Parameter: StateExample Value:
12345
Description:
The state as specified by the TPP
Parameter: scopeExample Value:
openid accounts
Description:
The scope being requested
Parameter: redirect_uriExample Value:
Description:
The redirect URL of the application registered in the developer portal. This must match the redirect URL from your software statement on the Open Banking Directory.
Parameter: nonceExample Value:
4987594875485-j
Description:
The nonce as specified by the TPP
Parameter: requestExample Value:
eyJhbGciOiJSUzI1NiIsImtpZCI6Ikd4bElpd 2lhblZxc0R1dXNoZ2pFME9UVXhPVGsif Q.eyJpc3MiOiJodHRwczovL2FwaS5hbHB oYWJhbmsuY29tIiwiYXVkIjoiczZCaGRSa 3F0MyIsInJlc3BvbnNlX3R5cGUiOiJjb2RlI GlkX3Rva2VuIiwiY2xpZW50X2lkIjoiczZCa GRSa3F0MyIsInJlZGlyZWN0X3VyaSI6Im h0dHBzOi8vYXBpLm15dHBwLmNvbS9jYi IsInNjb3BlIjoib3BlbmlkIHBheW1lbnRzIGFj Y291bnRzIiwic3RhdGUiOiJhZjBpZmpzbG RraiIsIm5vbmNlIjoibi0wUzZfV3pBMk1qIiw ibWF4X2FnZSI6ODY0MDAsImNsYWltcyI 6eyJ1c2VyaW5mbyI6eyJvcGVuYmFua2lu Z19pbnRlbnRfaWQiOnsidmFsdWUiOiJ1c m46YWxwaGFiYW5rOmludGVudDo4OD M3OSIsImVzc2VudGlhbCI6dHJ1ZX19LC JpZF90b2tlbiI6eyJvcGVuYmFua2luZ19pb nRlbnRfaWQiOnsidmFsdWUiOiJ1cm46Y WxwaGFiYW5rOmludGVudDo4ODM3OSI sImVzc2VudGlhbCI6dHJ1ZX0sImFjciI6ey Jlc3NlbnRpYWwiOnRydWUsInZhbHVlcyI 6WyJ1cm46b3BlbmJhbmtpbmc6cHNkMjp zY2EiLCJ1cm46b3BlbmJhbmtpbmc6cHN kMjpjYSJdfX19fQ.ehVeTgyYW7w9Gbbwp 53h5JyghKc_KV3XU8vSkioJEiTRHj4dUmvjlleLb 7GcohKBI7wHULjQjRTam1Zds_WAtiH2b k86YNQalzf9mt3SVzpIdtCaJdGiMYkD7e Pf2mKDDluSH_HWgiLzy-B5diH5JKtwHVMmxoaLbG4lzoCdo
Description:
This is an OIDC request object containing a claim identifying the accounts that needs to be authorized. To modify it to support your test scenario use the debugger at https://jwt.io
Follow the UI flow and at the end of the flow take note of the authorization code and id token appended to the URL (e.g. https://example.com/redirect?code=xxxxxxxxxxxxx&id_token=xxxxxxxxxx).
-
Validate the c_hash and the s_hash of the ID Token
At this point, you will now introspect the ID Token and use it as a detached signature to check:
-
The hash of the Authorization Code to prove it hasn't been tampered with during redirect (comparing the hash value against the c_hash attribute in ID Token)
-
The hash of the state to prove it hasn't been tampered with during redirect (comparing the state hash value against the s_hash attribute in the ID Token)
Also validate the signatures using the Lloyds Banking Group public key obtained from the OBIE.
-
-
Get the Access Token required to access the Account
Following the OAuth2.0 protocol, you now exchange the access code for the access token required for step 6.
For Authentication methods- client_secret_basic and client_secret_post:
curl -k -v -u <client_id>:<client_secret> \
--key ./22uobbpbcf1ztrsvxfoaj4.key \
--cert ./22uobbpbcf1ztrsvxfoaj4_open_banking_test_issuing_ca_.pem \
--compressed \
-X POST \
-d 'grant_type=authorization_code&redirect_uri=https://example.com/redirect&code=gktvoeyJlbm MiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiUlNBMV81Iiwia2lkIjoicTQtMjAxNy1tMi1ib3MifQ.cB1t7 tqgnQ_5Mu0XH2yR3oPfF_8HgrHi7uVSZY67Z77Qu-8K9c_6FVASDyoa-
9O0Yi5f XqKMua_FrGveJ1Jur715HNqVaVPrR9v1M3akH8J92Af7nxED1R3647jKeftBkvy89h58 98Aexa6q1nMAsFL9N0W-5239ztqzNY00Qys4EfqEdKyyUZYvTRcgg0Z8Snw9c4_J48twgHY4DLl5DvGjekPPlLCEe-YebWgIUcb21z8JCudJKFnvQoZNryiT0oYbBeuu_7IVAUzJPvG5KiicnczWssgGX2WRTAj2-i6OGVcOcRpjcdE0RNKLwbBC2q9-HiD9_plMr5VjrkFn9A.9JwONmpP8iZKJh4sXdOskw.3cr4SulCTjU0tSzMrvp3K4zfbJ6t4bXkaq6v 9V-qvnnkGg7Pm8Vwfi906kALBpL3m5FKh19XV1mL7miQonlgRXbeHehkmG7IU-dXmq-suJnb-y4WCSFkHhZDYh2wsxDVY_l9BRZOyknSPjqdorlnwOnZRU0PALwPWhBB3BQFrRxaNLIAETv qjMMmTZssadVt9lZ10DFbfIsGIE78B8pkg-hoHdmFpXVCadnq8JgKi8knwKmUJ6bZqyfZbyR2isXvlAc5Bx1C5VK7png2fw0nPTUBt7H9euU 2gy-UsKo6OInJeDwHpxkQDFM8GFZyMOXyjEae6Zozj4pXAyHAmdKfFwy1Kbv2jyUXq4FCeQHph I 4wKvhgSNOVvA_asOExj8DlGPaIgzphMKseXmKTzWMpv3gRsmIGdZvH7lMhGsq7EZnlheYW UK3f MymJCQXu7jzEBP7DsJfNsCG6S9yG8Aih72_mrAvXjXEU_pqqbL6d8gWJJ4mnwIln-VxBxyO0M759VNgTw4tP93rNAjiPmJGwHQrtBxmg5lR-ET2oxTF_LyZWYFyVmIOiEPwabfvTrZxpcdwTRJK_mXfYGeWABxEZZXlZE7pWHoxusxRdnyl en4s35MHcZjWjCa8DddglkngYAF8l6otGyeuRZqHN6cu32uH5zHx9Z7E_rZmXT3h_uu9QK-
lfhIIaCr8OWMOrDOL.0HPU-Bu1wR8RYCq-5QV0tQ' \
{secure-domain}/prod01/lbg/lyds/oidc-api/v1.1/token
For Authentication methods – tls_client_auth:
curl -k -v \
--key ./22uobbpbcf1ztrsvxfoaj4.key \
--cert ./22uobbpbcf1ztrsvxfoaj4_open_banking_test_issuing_ca_.pem \
--compressed \
-X POST \
-d 'client_id=c1d81a9a-609a-47be-9363-
8fa038b987da&grant_type=authorization_code&redirect_uri=https://example.com/redirect&cod e=gktvoeyJlbmMiOiJBMTI4Q0JDLUhTMjU2IiwiYWxnIjoiUlNBMV81Iiwia2lkIjoicTQtMjAxNy1tMi 1ib3MifQ.cB1t7tqgnQ_5Mu0XH2yR3oPfF_8HgrHi7uVSZY67Z77Qu-8K9c_6FVASDyoa-9O0Yi5f XqKMua_FrGveJ1Jur715HNqVaVPrR9v1M3akH8J92Af7nxED1R3647jKeftBkvy89h58 98Aexa6q1nMAsFL9N0W-
5239ztqzNY00Qys4EfqEdKyyUZYvTRcgg0Z8Snw9c4_J48twgHY4DLl5DvGjekPPlLCEe-YebWgIUcb21z8JCudJKFnvQoZNryiT0oYbBeuu_7IVAUzJPvG5KiicnczWssgGX2WRTAj2-i6OGVcOcRpjcdE0RNKLwbBC2q9-HiD9_plMr5VjrkFn9A.9JwONmpP8iZKJh4sXdOskw.3cr4SulCTjU0tSzMrvp3K4zfbJ6t4bXkaq6v 9V-qvnnkGg7Pm8Vwfi906kALBpL3m5FKh19XV1mL7miQonlgRXbeHehkmG7IU-dXmq-suJnb-y4WCSFkHhZDYh2wsxDVY_l9BRZOyknSPjqdorlnwOnZRU0PALwPWhBB3BQFrRxaNLIAETv qjMMmTZssadVt9lZ10DFbfIsGIE78B8pkg-hoHdmFpXVCadnq8JgKi8knwKmUJ6bZqyfZbyR2isXvlAc5Bx1C5VK7png2fw0nPTUBt7H9euU 2gy-UsKo6OInJeDwHpxkQDFM8GFZyMOXyjEae6Zozj4pXAyHAmdKfFwy1Kbv2jyUXq4FCeQHph I 4wKvhgSNOVvA_asOExj8DlGPaIgzphMKseXmKTzWMpv3gRsmIGdZvH7lMhGsq7EZnlheYW UK3f MymJCQXu7jzEBP7DsJfNsCG6S9yG8Aih72_mrAvXjXEU_pqqbL6d8gWJJ4mnwIln-VxBxyO0M759VNgTw4tP93rNAjiPmJGwHQrtBxmg5lR-ET2oxTF_LyZWYFyVmIOiEPwabfvTrZxpcdwTRJK_mXfYGeWABxEZZXlZE7pWHoxusxRdnyl en4s35MHcZjWjCa8DddglkngYAF8l6otGyeuRZqHN6cu32uH5zHx9Z7E_rZmXT3h_uu9QK-
lfhIIaCr8OWMOrDOL.0HPU-Bu1wR8RYCq-5QV0tQ' \
{secure-domain}/prod01/lbg/lyds/mtls-token-api/v1.1/token \
URL
Parameter: secure-domainDescription:
Please refer to the Other Useful Information section for all brand specific domains
Certs
Parameter: CACertExample Value:
Combination of Root & Intermediate
Description:
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Body
Parameter: client_idExample Value:
c1d81a9a-609a-47be-9363-8fa038b987da
Description:
Client ID of your application registered in the developer portal
Parameter: client_secretExample Value:
qJ4dE5yO6xK2oM0fQ5wR0tF4kV0uL4xR 5kO6dB7dJ4iU7qI0yB
Description:
Client Secret of your application registered in the developer portal, its not required for tls_client_auth method
Parameter: grant_typeExample Value:
authorisation_code
Description:
The grant type being requested
Parameter: redirect_uriExample Value:
Description:
The redirect URL which must match that of the application registered in the developer portal
Parameter: codeExample Value:
gktvoeyJlbmMiOiJBMTI4Q0JDLUhTMjU2I iwiYWxnIjoiUlNBMV81Iiwia2lkIjoicTQtMjA xNy1tMi1ib3MifQ.cB1t7tqgnQ_5Mu0XH2y R3oPfF_8HgrHi7uVSZY67Z77Qu8K9c_6FVASDyoa9O0Yi5fXqKMua_FrGveJ1Jur715HNqVaV PrR9v1M3akH8J92Af7nxED1R3647jKeftB kvy89h5898Aexa6q1nMAsFL9N0W5239ztqzNY00Qys4EfqEdKyyUZYvTRcgg 0Z8Snw9c4_J48twgHY4DLl5DvGjekPPlL CEeYebWgIUcb21z8JCudJKFnvQoZNryiT0oY bBeuu_7IVAUzJPvG5KiicnczWssgGX2W RTAj2- i6OGVcOcRpjcdE0RNKLwbBC2q9- HiD9_plMr5VjrkFn9A.9JwONmpP8iZKJh4 sXdOskw.3cr4SulCTjU0tSzMrvp3K4zfbJ6t 4bXkaq6v9VqvnnkGg7Pm8Vwfi906kALBpL3m5FKh19 XV1mL7miQonlgRXbeHehkmG7IU-dXmqsuJnby4WCSFkHhZDYh2wsxDVY_l9BRZOykn SPjqdorlnwOnZRU0PALwPWhBB3BQFrR xaNLIAETvqjMMmTZssadVt9lZ10DFbfIsG IE78B8pkghoHdmFpXVCadnq8JgKi8knwKmUJ6bZq yfZbyR2isXvlAc5Bx1C5VK7png2fw0nPTU Bt7H9euU2gyUsKo6OInJeDwHpxkQDFM8GFZyMOXyj Eae6Zozj4pXAyHAmdKfFwy1Kbv2jyUXq4 FCeQHphII4wKvhgSNOVvA_asOExj8DlG PaIgzphMKseXmKTzWMpv3gRsmIGdZv H7lMhGsq7EZnlheYWUK3fMymJCQXu7j zEBP7DsJfNsCG6S9yG8Aih72_mrAvXjX EU_pqqbL6d8gWJJ4mnwIlnVxBxyO0M759VNgTw4tP93rNAjiPmJGw HQrtBxmg5lRET2oxTF_LyZWYFyVmIOiEPwabfvTrZxp cdwTRJK_mXfYGeWABxEZZXlZE7pWHo xusxRdnylen4s35MHcZjWjCa8DddglkngY AF8l6otGyeuRZqHN6cu32uH5zHx9Z7E_r ZmXT3h_uu9QKlfhIIaCr8OWMOrDOL.0HPUBu1wR8RYCq-5QV0tQ
Description:
The authorisation code retrieved in step 3
Take note of the access token and ID Token in the response data.
-
Validate the at_hash of the ID Token
At this point, you will now introspect the ID Token and use it as a detached signature to check:
-
The hash of the access token to prove it hasn't been tampered with during redirect (comparing the hash value against the at_hash attribute in ID Token)
Also validate the signature of the ID Token using the Lloyds Banking Group public key obtained from the OBIE.
-
-
Get Accounts
You can use the Access Token to retrieve Accounts (bulk or specific). The following examples are from the Account and Transaction API Specification.
Where the initial Access Token expires, you must obtain a new Access Token.
curl --request GET \
--key ./private-cert.key \
--cert ./public-cert.pem \
--carcert ./root-ca.pem \
--compressed \
--url {secure-domain}/prod01/lbg/lyds/open-banking/v3.1/aisp/accounts \
--header 'accept: application/json; charset=UTF-8' \
--header 'authorization: Bearer gktvoeyJhbGciOiJSUzI1NiIsImtpZCI6InE0LTIwMTctbTEtYm9zIn0.eyJpc3MiOiJsbG95ZHMiLCJ wcml2YXRlIjoiQUFJa01ETTVOREptWlRVdE9HTmlNaTAwTnpWbUxXSXdNVEl0TkRneVpqTT BaVEV4WXpJNXFhRWU5Z0RCQnAwbjBRQU9xRXo4Ti16UTYwbUhPOFZHU1BQTGhkajdzY jFMYV9wX05mYmJkSnQySHRZc0QyakRXMHdYaS13ZVhZV2s5aHhPSWZrb0d3dE9OamZo SU56RFMtYWFxLVlhaW1OWmFQbDMtd1MzUFdva0I0OG5WZW4wMF81NGczeU1zMEhlMk VhdUVhcEZlX3hTeEFRVGt2Q2NHWnhyRmRaWDVHRm9FUEh3UEFjUnptSWhpZ3NZczNiRn RsWkVmR0V3dURTU1V0SWpRQVAzU1ZNNmJxd1ZJQThab3hwazVvRnptWEJLMUl1dHppS 0pMX0IwN0ZhYldHOE5qaWtUWHREcXFudDNLbVVhNjVac2dGT3BZT2VUQUFXTkdmdnBK MDhZRnV2MnhvOVRjcmRlejYxdjZCSFBaZkdpLW9tMF9BUjk5NnZRSDJqOTZONE5XM0lNM 0VIWGpVZG9lMWpoU0ZpcTc4eGhxWXU5MENicHhnSDJ4eng1Y2h6QlN1WHJNalY2VnVSZ2 ZMMUZoRXNZRjlTY1FKQlRuNmlIVjhLODZDQ0RtZGJuZjFGQjVybTNQWkZFdFZid0RCYmhB dmhQeXI4bkp6ei1lZkJnVzBrcWNnIn0.dmev3qQ4I14Vgps9Z7rjAJn31Zsepw8m15GWCqeSHL OvlGvbi2RS_uUdDpKAQg3aUpSvJUbffLP0RfG4RVLlYVI2vPlSKzO9L1eHZj7QM_S7p03g1cX CFowZye8IgWolBsVNd4MOIq9rQWHW3ywrS8Fx9S9tum7wIvn8tqIluQqLRa5c-oKthWW5uz66M8IHfrigeMCOYWsboG5uF0aKni20C1sLHGFWMDZU1M3n25bV0AZh7INvDoB 7EloIgr8IQiOZj0BSPKNtIDMGTXlixM8uVlW6eUJS3Z9dgvO7' \
--header 'x-fapi-customer-ip-address: REPLACE_THIS_VALUE' \
--header 'x-fapi-customer-last-logged-time: REPLACE_THIS_VALUE' \
--header 'x-fapi-financial-id: REPLACE_THIS_VALUE' \
--header 'x-fapi-interaction-id: REPLACE_THIS_VALUE'
URL
Parameter: secure-domainDescription:
Please refer to the Other Useful Information section for all brand specific domains
Certs
Parameter: CACertExample Value:
Combination of Root & Intermediate
Description:
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Headers
Parameter: authorizationExample Value:
Bearer
gktvoeyJhbGciOiJSUzI1NiIsImtpZCI6InE0 LTIwMTctbTEtYm9zIn0.eyJpc3MiOiJsbG9 5ZHMiLCJwcml2YXRlIjoiQUFJa01ETTVO REptWlRVdE9HTmlNaTAwTnpWbUxXSX dNVEl0TkRneVpqTTBaVEV4WXpJNXFh RWU5Z0RCQnAwbjBRQU9xRXo4Ti16UT YwbUhPOFZHU1BQTGhkajdzYjFMYV9w X05mYmJkSnQySHRZc0QyakRXMHdYa S13ZVhZV2s5aHhPSWZrb0d3dE9OamZ oSU56RFMtYWFxLVlhaW1OWmFQbDMt d1MzUFdva0I0OG5WZW4wMF81NGcze U1zMEhlMkVhdUVhcEZlX3hTeEFRVGt2 Q2NHWnhyRmRaWDVHRm9FUEh3UEFj UnptSWhpZ3NZczNiRnRsWkVmR0V3dU RTU1V0SWpRQVAzU1ZNNmJxd1ZJQTh ab3hwazVvRnptWEJLMUl1dHppS0pMX0I wN0ZhYldHOE5qaWtUWHREcXFudDNL bVVhNjVac2dGT3BZT2VUQUFXTkdmdn BKMDhZRnV2MnhvOVRjcmRlejYxdjZCS FBaZkdpLW9tMF9BUjk5NnZRSDJqOTZ ONE5XM0lNM0VIWGpVZG9lMWpoU0Zp cTc4eGhxWXU5MENicHhnSDJ4eng1Y2h 6QlN1WHJNalY2VnVSZ2ZMMUZoRXNZ RjlTY1FKQlRuNmlIVjhLODZDQ0RtZGJuZ jFGQjVybTNQWkZFdFZid0RCYmhBdmh QeXI4bkp6ei1lZkJnVzBrcWNnIn0.dmev3q Q4I14Vgps9Z7rjAJn31Zsepw8m15GWCq eSHLOvlGvbi2RS_uUdDpKAQg3aUpSvJ UbffLP0RfG4RVLlYVI2vPlSKzO9L1eHZj7 QM_S7p03g1cXCFowZye8IgWolBsVNd4 MOIq9rQWHW3ywrS8Fx9S9tum7wIvn8tq IluQqLRa5coKthWW5uz66M8IHfrigeMCOYWsboG5u F0aKni20C1sLHGFWMDZU1M3n25bV0A Zh7INvDoB7EloIgr8IQiOZj0BSPKNtIDMG TXlixM8uVlW6eUJS3Z9dgvO7- LxJrphDeg26ZrYQyMFDxVXjA8VmP2KB 0lnDggbvLwrHkwDescription:
The token obtained in step 5
REFRESH TOKEN
TPP can obtain a new Access Token by using a previously issued Refresh Token and Refresh Token Grant Type. This will have to be done before the expiry of the Refresh Token TTL.
Refresh Token is only available for consumers of fundsconfirmations, accounts and payments (only Variable Recurring Payments). TPP will receive the Refresh Token in response while exchanging the Access Code for Access Token.
curl -k -X POST \
--key ./private-cert.key \
--cert ./public-cert.pem \
--cacert ./ca-cert.pem \
--url {secure-domain}/prod01/lbg/lyds/mtls-token-api/v1.1/token \
--header 'accept: application/json' \
--header 'cache-control: no-cache' \
--header 'content-type: application/x-www-form-urlencoded' \
--data 'grant_type=refresh_token&client_id=c1d81a9a-609a-47be-9363-8fa038b987da&refresh_token=AAImRuf QlWgaSyEiT6aw-0MhiivaI5daPew3iL9ulWrYkcHVZ-ZutghJ86mRdxLL6NuKKswePJwGWYqXR21TtqETu-v0Xeov1iqJrHiqYFP65pwh6FUbIdTG3nLJ5MKAzmCda6ZfCBW6gYo0eGKBd-qBC9CU35WV8zLLWtSXk83IGuvYtJemxUyh1P_vpNGEQXzMfCr7K4jiJmqyuETT-FyLRPv495gvPAszcyDfHCciYvaQTgfiCcmvI_WOa6kImepD87Bcep1DHbV8dm6wcPSXxkbmT kw2UsNgpWhkNAGKjzvkgt7LW2akF0IizRLFtpyV-CbgiTw2yBeBR_kRMHTT6vR7yzZgLzWAgWHIqOSxPEbaAHW6uIeZgcfSb4CkURs251sxeQtn udJRFywd-0PQxNHweVBu9mDmlogGCF_PvmMb71OwyAGBBlm7oTGd4afIS_h0-i5_ByNtnBhu_d4sn0U2cN'
URL
Description:
Please refer to the Other Useful Information section for all brand specific domains
Certs
Example Value:
Combination of Root & Intermediate
Description:
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Data
Example Value:
refresh_token
Description:
The grant type being requested
Example Value:
c1d81a9a-609a-47be-9363- 8fa038b987da
Description:
The Client ID of your application registered in the developer portal
Example Value:
AAImRufQlWgaSyEiT6aw0MhiivaI5daPew3iL9ulWrYkcH VZZutghJ86mRdxLL6NuKKsweP JwGWYqXR21TtqETuv0Xeov1iqJrHiqYFP65pwh6FU bIdTG3nLJ5MKAzmCda6ZfCB W6gYo0eGKBdqBC9CU35WV8zLLWtSXk83I GuvYtJemxUyh1P_vpNGEQXz MfCr7K4jiJmqyuETTFyLRPv495gvPAszcyDfHCciY vaQTgfiCcmvI_WOa6kImepD8 7Bcep1DHbV8dm6wcPSXxkb mTkw2UsNgpWhkNAGKjzvkgt 7LW2akF0IizRLFtpyVCbgiTw2yBeBR_kRMHTT6vR 7yzZgLzWAgWHIqOSxPEbaA HW6uIeZgcfSb4CkURs251sxe QtnudJRFywd0PQxNHweVBu9mDmlogGCF _PvmMb71OwyAGBBlm7oTG d4afIS_h0- i5_ByNtnBhu_d4sn0U2cN'
Description:
Refresh token received with the previous Access token
ACCOUNT INFORMATION SERVICE APIS: ADDITIONAL INFORMATION
SPECIFICATION
The OBIE has provided a set of mandatory and optional Account Information specifications for ASPSPs, which can be found here
Within the AISP API specifications, Lloyds Banking Group supports following types of banking accounts: Current Accounts, Saving Accounts and Credit Card Accounts. In addition to all mandatory AISP API specifications which Lloyds Banking Group has implemented, the following tables show which optional Account Information API specifications are currently implemented for each API.
-
Accounts
NameCurrent AccountsV3.1Saving AccountsV3.1Credit Card AccountsV3.1DescriptionAccountId✓
✓
✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Currency✓
✓
✓
Identification of the currency in which the account is held.
Usage: currency should only be used in case one account number covers several currencies and the initiating party needs to identify which currency needs to be used for settlement on the account.
AccountType✓
✓
✓
Specifies the type of account (personal or business).AccountSubType✓
✓
✓
Specifies the sub type of account (product family group).NickName✓
✓
The nickname of the account, assigned by the account owner in order to provide an additional means of identification of the account.Opening Date✓
✓
✓
Date on which the account and related basic services are effectively operational for the account ownerMaturity Date✓
Maturity date for the account.SwitchStatus✓
This field will be returned and populated with the value UK.CASS.SwitchCompleted only when an account has been switched out to a different bank. Applicable for retail and business current accounts.AccountProvides the details to identify an account.SchemeName✓
✓
✓
Name of the identification scheme, in a coded form as published in an external listIdentification✓
✓
✓
Identification assigned by an institution to identify an account. This identification is known by the account owner.Name✓
✓
✓
The account name displayed for different customer segments are given below
Retail Customers: This will be the name of the person who owns the account.
Business Customers (O4B): This field will be the legal entity name of the business that owns the account.
Commercial Clients (CBO): This will be the name that the account holder gave the account when they opened the account.
* This includes Commercial non-Sterling accounts.
-
Balances
NameCurrent AccountsV3.1Saving AccountsV3.1Credit Card AccountsV3.1DescriptionAccountId✓
✓
✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Amount✓
✓
✓
Amount of money of the cash balance.Currency✓
✓
✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds"CreditDebitIndicator✓
✓
✓
Indicates whether the balance is a credit or a debit balance.
Usage: a zero balance is considered to be a credit balance.
Type**✓
✓
✓
Balance type, in a coded formDateTime✓
✓
✓
Indicates the date (and time) of the balance.CreditLineSet of elements used to provide details on the credit line.Included✓
✓
✓
Indicates whether or not the credit line is included in the balance of the account.
Usage: if not present, credit line is not included in the balance amount of the account.
Amount***✓
✓
✓
Amount of money of the credit line.Currency✓
✓
✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".Type**✓
✓
✓
Limit type, in a coded form.* This includes Commercial non-Sterling accounts.
** Due to High Cost of Credit (HCC) regulatory requirements the ‘Available’ balance (balance including pending transactions) returned by the /balance endpoint will no longer include the pre-agreed credit (overdraft) the account may have. The ‘Available’ balance shown to the PSU in the PISP consent journeys will also change in line with these requirements. In addition, to align with our online channels we will be removing the ‘Credit’ and ‘Available’ optional fields from the Credit line sub section of the /balance endpoint. These changes will only apply to PCAs and BCAs.
*** The credit line amount returned for commercial customers who are registered for LBG CBO(Commercial Banking Online) channel are of advisory value only as it may not reflect the complex overdraft and credit facilities available to these customers.
-
Account Access Consent / Account Requests
NameCurrent AccountsV3.1Saving AccountsV3.1Credit Card AccountsV3.1DescriptionConsentId✓
✓
✓
Unique identification as assigned to identify the account request resource.AccountRequestId✓
✓
Unique identification as assigned to identify the account request resource.Status✓
✓
✓
Specifies the status of the account request resource.CreationDateTime✓
✓
✓
Date and time at which the resource was created.StatusUpdateDateTime✓
✓
✓
Date and time at which the resource status was updated.Permissions✓
✓
✓
Specifies the Open Banking account request types. This is a list of the data clusters being consented by the PSU, and requested for authorisation with the ASPSP.ExpirationDateTime✓
✓
✓
Specified date and time the permissions will expire.
If this is not populated, the permissions will be open ended.
TransactionFromDateTime✓
✓
✓
Specified start date and time for the transaction query period.
If this is not populated, the start date will be open ended, and data will be returned from the earliest available transaction.
TransactionToDateTime✓
✓
✓
Specified end date and time for the transaction query period.
If this is not populated, the end date will be open ended, and data will be returned to the latest available transaction.
* This includes Commercial non-Sterling accounts. Commercial Clients will be presented with applicable Sterling and non-Sterling accounts during authorisation.
-
Product
NameCurrently AvailableV3.1DescriptionAccountId✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.ProductIdentifierIdentifier within the parent organization for the product. Must be unique in the organization.ProductId✓
Identifier within the parent organization for the product. Must be unique in the organization.ProductType✓
Descriptive code for the product category - BCA/PCAProductName✓
The name of the product used for marketing purposes from a customer perspective i.e. what the customer would recogniseSecondaryProductIdentifierIdentifier within the parent organization for the product. Must be unique in the organization.SecondaryProductId✓
Identifier within the parent organization for the product. Must be unique in the organization.PCAProductDetails✓
CreditInterest✓
Details about the interest that may be payable to the PCA account holders. Provided where applicable.Overdraft✓
Details about overdraft rates, fees & charges. Provided where applicable.TierBandMethod✓
The methodology of how overdraft is charged. It can be:
'Whole' Where the same charge/rate is applied to the entirety of the overdraft balance (where charges are applicable).
'Tiered' Where different charges/rates are applied dependent on overdraft maximum and minimum balance amount tiers defined by the lending financial organisation
'Banded' Where different charges/rates are applied dependent on overdraft maximum and minimum balance amount bands defined by a government organisation.
TierValueMin✓
Minimum value of Overdraft Tier/BandTierValueMax✓
Maximum value of Overdraft Tier/BandEAR✓
EAR means Effective Annual Rate and/or Equivalent Annual Rate (frequently used interchangeably), being the actual annual interest rate of an Overdraft.OtherFeesCharges✓
Contains details of fees and charges which are not associated with either borrowing or features/benefits. Provided where applicable.BCAProductDetails✓
CreditInterest✓
Details about the interest that may be payable to the BCA account holders. Provided where applicable.Overdraft✓
Details about overdraft rates, fees & charges. Provided where applicable.OtherFeesCharges✓
Contains details of fees and charges which are not associated with either borrowing or features/benefits. Provided where applicable.Other ProductsOtherProductType✓
Other Product type will contain only Savings accounts. The values returned will be either Personal Savings Account or Business Savings Account.Name✓
Long name associated with the productDescription✓
Description of the Product associated with the accountMaturityDate✓
Maturity date for the account.CreditInterestRateTierBandMethod✓
The methodology of how credit interest is paid/applied.
- Whole (INWH) - The same interest rate is applied irrespective of the PSA/BSA balance
- Tiered (INTI) - Interest rates are tiered i.e. increasing rate for each tier as balance increases, but interest paid on tier is fixed for that tier and not on whole balance.
- Banded (INBA) - Interest rates are banded i.e. increasing rate on whole balance as balance increases.
Calculation Method✓
Methods of calculating interest.Destination✓
Describes whether accrued interest is payable only to the PSA/BSA or to another bank account.TierValueMinimum✓
Minimum deposit value for which the credit interest tier applies.TierValueMaximum✓
Maximum deposit value for which the credit interest tier applies.Applicationfrequency✓
How often interest is applied to the PSA/BSA for this tier/band i.e. how often the financial institution pays accumulated interest to the customer's PSA/BSADepositInterestAppliedCover age✓
Amount on which interest is appliedFixedVariableInterestRateTy pe✓
Type of interest rate i.e. variableAER✓
The annual equivalent rate (AER) is interest that is calculated under the assumption that any interest paid is combined with the original balance and the next interest payment will be based on the higher account balance. Overall, this means that interest can be compounded several times in a year depending on the number of times that interest payments are made.BankInterestRateType✓
Interest rate types, other than AER, which financial institutions may use to describe the annual interest rate payable to the PSA/BSABankInterestRate (O)✓
Bank Interest for the PSA/BSA product -
Standing Orders
NameCurrently AvailableV3.1DescriptionAccountId✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.Frequency✓
Reference✓
Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.FirstPaymentDateTime✓
The date on which the first payment for a Standing Order schedule will be made.FirstPaymentAmount✓
The amount of the first Standing OrderCurrency✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of theinternational standard ISO 4217 "Codes for the representation of currencies and funds".NextPaymentDateTime✓
The date on which the next payment for a Standing Order schedule will be made.NextPaymentAmount✓
The amount of the next Standing OrderCurrency✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".FinalPaymentDateTime✓
The date on which the final payment for a Standing Order schedule will be madeFinalPaymentAmount✓
The amount of the final Standing OrderCurrency✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".StandingOrderStatusCode✓
Specifies the status of the standing order in code form.CreditorAccountProvides the details to identify the beneficiary account.SchemeName✓
Name of the identification scheme, in a coded form as published in an external list.Identification✓
Unique and unambiguous identification of the servicing institution.Name✓
Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account -
Direct Debits
NameCurrently AvailableV3.1DescriptionAccountId✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.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.DirectDebitStatusCode✓
Specifies the status of the direct debit in code form.Name✓
Name of Service User.PreviousPaymentDateTime✓
Date of most recent direct debit collection.Frequency✓
Regularity with which direct debit instructions are to be created and processedPreviousPaymentAmount✓
The amount of the most recent direct debit collectionCurrency✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds". -
Beneficiaries
NameCurrently AvailableV3.1DescriptionAccountId✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account ownerBeneficiaryId✓
A unique and immutable identifier used to identify the beneficiary resource. This identifier has no meaning to the account owner.
Only available for BACS Beneficiaries.
Reference✓
Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.SupplementaryDataAdditional information that cannot be captured in the structured fields and/or any other specific block.Beneficiary Address✓
This will contain the Beneficiary Address for the International BeneficiariesCreditorAccountProvides the details to identify the beneficiary account.SchemeName✓
Name of the identification scheme, in a coded form as published in an external list.Identification✓
Identification assigned by an institution to identify an account. This identification is known by the account owner.Name✓
Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.
Usage: The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number.
Creditor Agent(Not available for BACS beneficiaries)SchemeName✓
Name of the identification scheme, in a coded form as published in an external list
Identification✓
Unique and unambiguous identification of the servicing institution
Name✓
Name by which an agent is known and which is usually used to identify that agent
Postal AddressCountry✓
Nation with its own government
AddressLine✓
Information that locates and identifies a specific address, as defined by postal services, presented in free format text
* This includes Domestic, BACS and International beneficiaries for Commercial accounts.All beneficiaries returned in this endpoint are “trusted” beneficiaries.
-
Transactions
NameCurrent AccountsV3.1Saving AccountsV3.1Credit Card AccountsV3.1DescriptionAccountId✓
✓
✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.TransactionReference✓
✓
Unique reference for the transaction. This reference is optionally populated, and may as an example be the FPID in the Faster Payments context.Amount✓
✓
✓
Amount of money in the cash transaction entry.Currency✓
✓
✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds".CreditDebitIndicator✓
✓
✓
Indicates whether the transaction is a credit or a debit entryStatus✓
✓
✓
Status of a transaction entry on the books of the account servicer.
Lloyds Banking Group will support only Booked and Pending status code.
BookingDateTime✓
✓
✓
Date and time when a transaction entry is posted to an account on the account servicer's books.
Usage: booking date is the expected booking date, unless the status is booked, in which case it is the actual booking date.
ValueDateTime✓
✓
✓
Date and time at which assets become available to the account owner in case of a credit entry, or cease to be available to the account owner in case of a debit transaction entry.
Usage: if transaction entry status is pending and value date is present, then the value date refers to an expected/requested value date.
For transaction entries subject to availability and for which availability information is provided, the value date must not be used. In this case the availability component identifies the number of availability days
TransactionInformation✓
✓
✓
Further details of the transaction. This is the transaction narrative, which is unstructured text.AddressLine✓
✓
Information that locates and identifies a specific address for the transaction entry, includes the city and the country.BankTransactionCodeSet of elements used to fully identify the type of underlying transaction resulting in an entry.
Code✓
✓
Specifies the family within a domain.SubCode✓
✓
Specifies the sub-product family within a specific family.ProprietaryBankTransactionCodeSet of elements to fully identify a proprietary bank transaction code.Code✓
✓
✓
Proprietary bank transaction code to identify the underlying transaction.
For credit card transactions, the value returned in this field is very specific to Lloyds Banking Group’s internal processing, and hence can be disregarded by the TPPs.
Issuer✓
✓
✓
Identification of the issuer of the proprietary bank transaction code.BalanceSet of elements used to define the balance as a numerical representation of the net increases and decreases in an account after a transaction entry is applied to the accountAmount✓
✓
Amount of money of the cash balance after a transaction entry is applied to the account.Currency✓
✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds”. Indicates whether the balance is a credit or a debit balance.
Usage: a zero balance is considered to be a credit balance.
CreditDebitIndicator✓
✓
Indicates whether the balance is a credit or a debit balance.
Usage: a zero balance is considered to be a credit balance
Type✓
✓
Balance type, in a coded formMerchantDetailsDetails of the merchant involved in the transaction.MerchantName✓
✓
Name by which the merchant is known.MerchantCategoryCode✓
✓
Category code conform to ISO 18245, related to the type of services or goods the merchant provides for the transaction.CardInstrumentsSet of elements to describe the card instrument used in the transaction.CardSchemeName✓
Name of the card scheme.Authorisation Type✓
The card authorisation type* This includes non-Sterling Commercial accounts .
-
Statements
NameCurrently AvailableCurrent AccountsV3.1Saving AccountsV3.1Credit Card AccountsV3.1DescriptionAccountId✓
✓
✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.StatementId✓
✓
✓
Unique identifier for the statement resource within a servicing institution. This identifier is both unique and immutableType✓
✓
✓
RegularPeriodicStartDateTime✓
✓
✓
Date and time at which the statement period starts.EndDateTime✓
✓
✓
Date and time at which the statement period endsCreationDateTime✓
✓
✓
Date and time at which the resource was created.StatementDescription✓
✓
✓
Other descriptions that may be available for the statement resourceStatement/FileAccountId✓
✓
✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account ownerStatementId✓
✓
✓
Unique identifier for the statement resource within a servicing institution. This identifier is both unique and immutable.{StatementID}/File✓
✓
✓
Return a PDF/CSV file for a specific StatementID received in the request i.e. application/pdf/csv file*** CSV file is available only for the Business Credit Cards and for last 6 months.
-
Scheduled-Payments
NameCurrently AvailableV3.1DescriptionAccountId✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.ScheduledPayment✓
ScheduledPaymentId✓
A unique and immutable identifier used to identify the scheduled payment resource. This identifier has no meaning to the account owner.ScheduledPaymentDateTime✓
The date on which the scheduled payment will be madeScheduledType✓
Specifies the scheduled payment date type requested.Reference✓
Unique reference, as assigned by the creditor, to unambiguously refer to the payment transaction.DebtorReference✓
A reference value provided by the PSU to the PISP while setting up the scheduled payment.Amount✓
A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217Currency✓
A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 "Codes for the representation of currencies and funds"CreditorAccountProvides the details to identify the beneficiary accountSchemeName✓
Name of the identification scheme, in a coded form as published in an external list.Identification✓
Unique and unambiguous identification of the servicing institutionName✓
Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account.* This includes Commercial non-Sterling accounts.
-
Offers
NameCurrently AvailableCurrent AccountsV3.1Saving AccountsV3.1Credit Card AccountsV3.1DescriptionAccountId✓
A unique and immutable identifier used to identify the account resource. This identifier has no meaning to the account owner.OfferId✓
A unique and immutable identifier used to identify the offer resource. This identifier has no meaning to the account owner.OfferType✓
Balance Transfer or Money TransferDescription✓
Further details of the offer.StartDateTime✓
Date and time at which the offer starts.EndDateTime✓
Date and time at which the offer ends.Rate✓
Rate associated with the offer typeTerm✓
Further details of the term of the offer -
Party
NameCurrently AvailableCurrent AccountsV3.1Saving AccountsV3.1Credit Card AccountsV3.1DescriptionPartyId✓
✓
✓
A unique and immutable identifier used to identify the customer resource. This identifier has no meaning to the account owner.PartyType✓
✓
✓
Party TypeFull Legal Name✓
✓
✓
The full legal name of the party.Legal Structure✓
✓
✓
Legal standing of the party -
Proprietary Bank Transaction Codes
Lloyds Banking Group supports the following Proprietary Bank Transaction Codes:
Proprietary Bank Transaction CodeText DescriptionDDDIRECT DEBITFPIFASTER PAYMENTS INBOUNDFPOFASTER PAYMENTS OUTBOUNDMPIMOBILE PAYMENT INMPOMOBILE PAYMENT OUTSALSALARYBPBILL PAYMENTSCHQCHEQUE(S)CHGCHARGECORCORRECTIONDEBDEBIT CARDSOSTANDING ORDERBNSBONUSBGCBANK GIRO CREDITINTINTRESTCPTCASHPOINTCSHCASHCSQCASH/CHEQUE(S)DEPDEPOSITDIVDIVIDENDEFTELECTRONIC FUNDS TRANSFEREUREURO CHEQUEFEFOREIGN EXCHANGEFEESERVICE FEELTBBANK TRANSFERMTGMORTGAGE PAYMENTNSNATIONAL SAVINGS DIVIDENDNSCNATIONAL SAVINGS CERTIFICATEOTHOTHERPAYCOUNTER WITHDRAWALPSBPREMIUM SAVINGS BONDPSVPAYSAVESPBCASHPOINTTCTRUSTCARD PAYMENTTDTRANSFERREDTDGTRANSFERRED INTEREST GROSSTDITRANSFERRED INTERESTTDNTRANSFERRED INTEREST NETTFRFUNDS TRANSFERUTUNIT TRUSTCOMCOMMISSIONIBINTERNET BANKINGDROVERDRAWN BALANCESDCCOLLECTION CREDITSCRREFUND DEBITSDDCOLLECTION DEBITSDRREVERSAL CREDITSUREXCESS MANAGEMENT REVERSALNote: Click here for a link to the full list of Proprietary Bank Transaction Codes
ACCOUNT INFORMATION API RULES AND EXCEPTIONS
There are a number of important implementation variations relating to our Account Information APIs that TPPs should be aware of. These are listed below:
For cheque transactions (identified by Transaction Code "CHQ") that are currently pending, there will be 2 records provided to the TPP::
- a "pending" record - for this record LBG will apply the "Value Date" to the "Booking Date" field
- a "booked" record - for this record LBG will apply the "Booking Date" to the "Value Date" field
For combined Cash + Cheque transactions (identified by Transaction Code "DEP") where the cheque amount is currently pending, there will be 2 records provided to the TPP:
- a "pending" record - for this record LBG will apply the "Value Date" to the "Booking Date" field
- a "booked" record - for this record LBG will apply the "Booking Date" to the "Value Date" field
Lloyds Banking Group have provided supplementary product information and links to Terms and Conditions in the ‘Notes’ field. This contains important details about conditions that apply to accounts, and about thresholds for credit interest.
This data should be published alongside product details to ensure that products are presented clearly and do not mislead customers.
Lloyds Banking Group have provided supplementary product information in the ‘Notes’ field. This contains important details about conditions that apply to accounts.
This data should be published alongside product details to ensure that products are presented clearly and do not mislead customers.
Please find below the breakdown of the information provided and the section to which it applies:
“Please be aware:
The information provided reflects a normal Credit Interest arrangement.”
- Applies to: ‘CreditInterest’ array.
“Overdraft arrangement fees may apply.”
- Applies to: ‘Overdraft’ array.
Due to technical constraints, Lloyds Banking Group are unable to provide account-specific data in relation to Overdraft arrangement fees.
“The first time you go overdrawn, without an agreed overdraft facility, or exceed your agreed limit with us by £50 or more, you may be charged an Unauthorised Borrowing Fee (UBF) of £15. After that, the UBF is applied every time you increase your unauthorised borrowing by £50 or more from the previous day’s closing balance, unless a higher limit is agreed with us or until the account is within its existing limit or in credit.”
- Applies to: ‘OtherFeesCharges’ array.
- The above relates to the value provided as the “ServiceCAccountFeeMonthly” fee.
“The Account Monthly Fee provided is the standard value associated with this product.”
Applies to: ‘OtherFeesCharges’ array.
- The above relates to the value provided as the “ServiceCAccountFeeMonthly” fee.
Credit cards only: Transactions are returned in a reversed chronological order. However, if the statement is created with payments pending, they will be posted in the following statement period and may appear out of sequence.
Business Credit card:
In addition to credit cards only; for business credit card posted transaction, which are posted will be displayed starting with Primary card transactions followed by Subsidiary cards transactions and transactions within Primary card and subsidiary card will be displayed in reverse chronological order.
When a Get beneficiaries call is made the following will be the order of display
- Domestic beneficiaries
- International beneficiaries
- BACS beneficiaries
Domestic beneficiaries will be displayed in one page. When the last domestic beneficiary is displayed or where no domestic beneficiaries are available selection of the next link will display international beneficiaries where available. When the last international beneficiary is displayed or where no international beneficiaries are available selection of the next link will display BACS beneficiaries where available. Once the last record is displayed or where no record is available the next link will not be presented.
The beneficiaries endpoint response may include the same beneficiary listed under both domestic and BACS beneficiaries for a given Account ID.
/accounts/{AccountId}/statements/{StatementId}
/accounts/{AccountId}/statements/{StatementId}
/file
Access Token Expiry:
Consent Request will result in the issuance of an Access Token for 90 days with a Refresh Token. TPPs will need to ensure that they call the token endpoint before the Access Token expires to avoid customer having to complete a reauthentication journey.
CONFIRMATION OF FUNDS SERVICE APIS: ADDITIONAL INFORMATION
SPECIFICATIONS
The OBIE has provided a set of mandatory and optional confirmation of funds specifications for ASPSPs, which can be found here.
Refer to the request and response structure and data dictionary in OBIE specification, which can be found here.
FUNDS CONFIRMATION CONSENT
✓
✓
✓
Specifies the status of consent resource in code form
- Awaiting Authorisation
- Authorised
- Rejected
- Revoked
✓
✓
Specified date and time the funds confirmation authorisation will expire.
If this is not populated, the authorisation will be open ended.
✓
✓
✓
✓
FUNDS CONFIRMATION
✓
✓
✓
✓
✓
✓
✓
✓
CONFIRMATION OF FUNDS API RULES AND EXCEPTIONS
There are a number of important implementation variations relating to our Confirmation of Funds APIs that TPPs should be aware of. These are listed below:
Access Token Expiry:
Consent Request will result in the issuance of an Access Token for 90 days with a Refresh Token. TPPs will need to ensure that they call the token endpoint before the Access Token expires to avoid customer having to complete a re-authentication journey.
PAYMENT INITIATION APIS: ADDITIONAL INFORMATION
SPECIFICATIONS
The OBIE has provided a set of mandatory and optional Payment Initiation specifications for ASPSPs, which can be found here (v3.1).
Our implementation of these APIs supports the following customer segments:
DOMESTIC PAYMENT INITIATION API RULES AND EXCEPTIONS
There are a number of important implementation variations relating to our Payment Initiation APIs that TPPs should be aware of. These are listed below:
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Negative payment amounts are not allowed in any of the Lloyds Banking Group payment requests.
Payment amounts are restricted to 2 decimal places.
For Balance Transfers and Money Transfers the minimum payment amount is £100.
For Paym the minimum payment amount is £1 and the maximum payment amount is £300.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Payment Risk Categorisation must be included in OBRisk.
Payment Context Code
In order for PISP initiated payments to be processed correctly we require each payment to be categorised as per the OBIE specifications.
TPPs must correctly classify payments into the following categories:
Ecommercegoods Ecommerceservices BillPayment Other PartytoParty BillingGoodsAndServicesInAdvance BillingGoodsAndServicesInArrears PispPayee EcommerceMerchantInitiatedPayment FaceToFacePointOfSale TransferToSelf TransferToThirdParty
Payment Context Code Field in the Risk Section is a mandatory requirement.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Only the following frequencies are supported by Lloyds Banking Group Domestic Standing orders:
- Weekly
- Four Weekly
- Monthly
- Quarterly
- Half Yearly
- Yearly
- Two Monthly
Domestic Standing Orders v3.1
Note: First Payment date and expiry date must have the same day value excluding Weekly and Four Weekly.
Example: Frequency: Monthly
First Payment date: (26/02/2019)
Final Payment date: (26/03/2019)
Result: Payment accepted
Exception is in place for month end i.e. 31/01/2019 with the next payment date 28/02/2019. This would be an acceptable date.
Lloyds Banking Group does not support PAN as a payment scheme for -
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
For Balance Transfers Lloyds Banking Group will need the following mandatory information:
Creditor Account
- SchemeName as UK.OBIE.PAN
- Identification/Credit Card number
- Name
Debtor Account
- SchemeName as UK.OBIE.PAN
- Identification/Credit Card number
- Name
RemittanceInformation
- Offer code/ID
For Money Transfers Lloyds Banking Group will need the following mandatory information:
Creditor Account>
- SchemeName as UK.OBIE. UK.OBIE.SortCodeAccountNumber
- Identification/Credit Card number
- Name
Debtor Account>
- SchemeName as UK.OBIE.PAN
- Identification/Credit Card number
- Name
RemittanceInformation>
- Offer code/ID
The following information is mandatory for Paym transactions:
- Creditor scheme should be UK.OBIE.Paym
- Creditor identification / mobile number should be a UK mobile number. The following formats are valid:
<+44><10 digit number>
<0044><10 digit number>
<44><10 digit number>
<0><10 digit number >
- Paym is only applicable for Retail Customers and for the ‘PartytoParty’ context code.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Base64 Encoded:
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1
Domestic Single Immediate Payments v3.1
INTERNATIONAL PAYMENT INITIATION API RULES AND EXCEPTIONS
There are a number of important implementation variations relating to our International Payment Initiation APIs that TPPs should be aware of. These are listed below:
2 options are available
Case 1: Where a BIC is available>
BIC to be sent in Creditor Agent field with a scheme of “UK.OBIE.BICFI”. In this case the address of the recipient bank is optional
Case 2: Where BIC is not available>
Creditor Agent Address is mandatory in the following format
- 2 lines of address
- Town name
- Country code
All fields are mandatory in this case
Country Type 1: IBAN mandatory country
Creditor Account Type must be set to IBAN and Creditor Agent Type must be set to BIC. Creditor Agent should be sent with the scheme as “UK.OBIE.BICFI”.
TPPs will need to quote a BIC/SWIFT and IBAN when sending International Payments to the following countries:
All EU and EEA countries: Albania, Austria, Belgium, Bosnia and Herzegovina, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Guernsey, Hungary, Iceland, Republic of Ireland, Italy, Jersey, Latvia, Liechtenstein,Lithuania, Luxembourg, Malta, The Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain, Sweden and UK
and also the following non EU and EEA countries: Andorra, Bahrain, Faroe Islands, Georgia, Gibraltar, Greenland, Isle of Man, Israel, Jordan, Kuwait, Lebanon, Macedonia, Montenegro, Moldova, Monaco, Pakistan, Palestine, Qatar, San Marino, Saudi Arabia, Switzerland, Tunisia, Turkey, and United Arab Emirates.
Country Type 2: National clearing code mandatory countries
Account number can be in BBAN or SCAN format but Creditor Agent should be sent with the Scheme as "UK.LBG.Clearingcode". The following Clearing codes are expected to be sent for each respective country:
Australia: Bank-State-Branch (BSB) Code
Canada: Canadian Transit Number
Hong Kong: Bank Code of Hong Kong
India: IFSC - Indian Financial Sys Code
New Zealand: New Zealand National Clearing Code
South Africa: South Africa National Clearing
United States: Fedwire code
Country Type 3: All other countries (excluding Country Type 1 or 2)
Creditor Account Type accepted: BBAN, SCAN or IBAN
Creditor Agent: If IBAN is provided a BIC has to be provided
Creditor Agent: for BBAN and SCAN scenarios the following is expected:
- Required in the Parent block - Creditor Agent Name
- Required in the Postal Address block: 2 lines of address, Town Name and Country code
Local instrument: No value is expected in this field for Retail and Business Banking customers
Creditor Postal Address is mandatory for all country types. Maximum of 3 lines of unstructured address and minimum of 1 line of address is required.
Currency of Transfer - Validation: Currency of transfer for Retail and O4B should be either GBP or Instructed Amount currency
Currency of Transfer if GBP: Where currency of transfer is GBP the instructed amount should also be GBP
Chargebearer: BornebyCreditor is not supported
Ratetype: Only "Actual" is supported. However where a payment requires multiple users to authorise then the rates displayed to the user will be indicative, all other rate types will be rejected for Retail and Business banking customers
Unit currency is a mandatory field within the exchange rate block. If mentioned it should always be GBP.
Contract identification is not supported for Retail and Business Banking customers
For certain countries the purpose or reason for payment is mandatory. TPPs are expected to provide this in the below format only:
For the following countries Reason for Payment to be provided in Data.Initiation.ExtendedPurpose
NOTE: Data.Initiation.Purpose as defined in the Specifications will not be used and may lead to rejections. TPPs will need to provide this information in Data.Initiation.ExtendedPurpose as prescribed below.
For the following countries – generic countries
Reason for payment to be chosen from this list.Note: ONLY the R codes should be sent in the supplementary data for the above countries. Any other format will be rejected. Correct format – R24; incorrect format – R24 School Fees
Reason codes for generic countries (note - text associated with the codes should not be sent)
R24 School Fees
R27 Inheritance
R23 House Purchase Resident
R28 Relocation
R29 Mortgage payment
R16 Salary
R01 Charitable Donation
R02 Expenses
R03 Family maintenance
R04 Fx Ccy Non-Res Deposit
R05 Fees
R06 Gift
R07 Holiday
R08 Hotel
R09 Invoice
R10 Loan
R11 Medical
R12 Own Account Transfer
R13 Pension
R14 Personal Transfer
R15 Rent
R17 Tax
R18 Wages
R20 Commission
R21 Purchase of Shares
R22 Grant
R26 House Purchase Non-Res
R25 Other
For Jordan and UAE
Please refer to the reason codes published here:https://www.bankofscotland.co.uk/onlinebankinghelp/internationalpayments/help-guidance.html
For UAE only the code should be sent in extended purpose i.e. ACM
Additionally any Payment reference added under RemittanceInformation. Reference will be concatenated with the purpose code provided as above up to a maximum of 35 characters.
For most currencies i.e. GBP only 2 decimal places are supported. Certain currencies i.e. Kuwaiti Dinar support up to a maximum of 3 decimal places.
For Japanese Yen 0 decimal places are supported
Payment Risk Categorisation must be included in OBRisk.
PaymentContextCode
In order for PISP initiated payments to be processed correctly we require each payment to be categorised as per the OBIE specifications.
TPPs must correctly classify payments into the following categories:
- Ecommercegoods
- Ecommerceservices
- BillPayment
- Other
- PartytoParty
- BillingGoodsAndServicesInAdvance
- BillingGoodsAndServicesInArrears
- PispPayee
- EcommerceMerchantInitiatedPayment
- FaceToFacePointOfSale
- TransferToSelf
- TransferToThirdParty
Payment Context Code Field in the Risk Section is a mandatory requirement.
Certain Business banking customers have enabled Multi Party authorisation and hence TPP should mention if they are happy to continue with the journey using the OBAuthorisation1 data element.
For International Payments where multi party authorisation applies only an indicative rate is displayed in the primary customer consent journey and the actual rate is shown during the secondary/final customer consent journey. This behaviour will be indicated back to TPPs in the submission call.
There is a maximum time limit of 90 seconds for a TPP to complete submission following successful consent of an international payment due to live exchange rates being quoted for the transaction. If the first submission request is received after 90 seconds this will result in a rejection of the submission request.
On PISP versions 3.1.4 and above the JWS should created with Base64 encoding. Failure to use the correct encoding in the creation of the JWS would result in the rejection of a payment request.
SCASupportData block is not supported by LBG. If received in the request, would result in the failure of the payment request.
VARIABLE RECURRING PAYMENT APIS: ADDITIONAL INFORMATION
SPECIFICATIONS
The OBIE has provided a set of mandatory and optional Variable Recurring Payments specifications for ASPSPs, which can be found here (v3.1).
The implementation of Variable Recurring Payment APIs will support use cases that meet the OBIE Definition of Sweeping. (Variable Recurring Payment under Sweeping Access).
Variable Recurring Payment endpoints will only be available to TPPs once Lloyds Banking Group have communicated the availability of these endpoints via TPP communications.
VARIABLE RECURRING PAYMENT API RULES AND EXCEPTIONS
There are a number of important implementation variations relating to our Variable Recurring Payment APIs that TPPs should be aware of. These are listed below:
Commercial Clients using Commercial Banking Online (CBO) will not be able to set up Variable Recurring Payments.
Retail customers using Internet Banking (IB) or Mobile App and Business Clients using Business Banking (O4B/BIB) or Mobile App will be able to set up Variable Recurring Payments.
Will only accept VRPType in consent request as UK.OBIE.VRPType.Sweeping.
Will only accept PSUAuthenticationMethods in consent request as UK.OBIE.SCANotRequired
Initiation.CreditorAccount details must be populated in the consent request. Any requests not providing Creditor Account details will be rejected.
Schemes supported are:
- UK.OBIE.SortCodeAccountNumber
- UK.OBIE.BBAN
- UK.OBIE.IBAN
ValidFromDateTime cannot occur more than 31 days in the future.
Where no date is provided, then creation date will be used to determine consent is active.
ValidToDateTime cannot be the same date as consent request and must fall after ValidFromDateTime.
Where no date is provided, then consent will remain active until a point PSU takes an action to revoke ordelete consent.
Requests sent where the amount field exceeds 2 decimal points will result in error response.
Consent request:
- MaximumIndividualAmount.Amount
- PeriodLimits.Amount
Consent funds-confirmation request:
- InstructedAmount.Amount
Payment request:
- Instruction.InstructedAmount.Amount
Consent request can support up to six instances of Period Limits within one request, however the period type cannot be duplicated within that same consent request
The combination of PeriodType of Fortnight and PeriodAlignment of Calendar cannot be supported. Requests will this combination will result in an error response
Consent requests that contain PeriodAlignment of Calendar will have the amount pro-rated for the first and last period.
Do not accept MaximumIndividualAmount.Amount value as less than £1.00.
A funds confirmation request must include the same reference as provided in the original consent request. The request will be rejected if this is not provided or does not match
Consent Request will result in the issuance of an Access Token for 90 days with a Refresh Token. TPPs will need to ensure that they call the token endpoint before the Access Token expires to avoid customer having to complete a re-authentication journey.
Endpoints not supported by VRP implementation:
GET /domestic-vrps/{DomesticVRPId}/payment-details
AGGREGATED POLLING FOR REVOKED CONSENTS: ADDITIONAL INFORMATION
OBIE SPECIFICATIONS FOR AGGREGATED POLLING
The OBIE have defined an Aggregated Polling API (POST /events) which allows an ASPSP to aggregate and deliver multiple signed event notifications to TPPs through the use of polling. The POST /events endpoint allows a TPP to poll and acknowledge and receive event notifications.
-
The POST method allows the TPP to transmit their polling parameters and event notification acknowledgements.
-
The ASPSP responds accordingly, sending event notifications as indicated by the TPPs polling parameters.
The OBIE specifications for Aggregated Polling, and sample requests and responses, can be found here.
LLOYDS BANKING GROUP EXCEPTIONS FOR THE AGGREGATED POLLING API
Lloyds Banking Group has implemented the Aggregated Polling API as specified by the OBIE but with the following exceptions:
-
The LBG Aggregated Polling API returns event notifications for revoked consents only.
-
Long polling is not supported as described within the OBIE specification – see ‘Polling Parameters’.
-
The response from the LBG Aggregated Polling API signs the whole response and not individual event notifications.
EVENT RECYCLING FREQUENCY
Lloyds Banking Group used JTIs to send event notifications. A unique JTI is generated each time the TPP calls the Aggregated Polling API. JTIs do not expire.
POLLING FREQUENCY
Lloyds Banking Group will restrict each TPP App to calling the Aggregated Polling API 10 times within 24 hours for each brand, e.g. a TPP may call the Lloyds Aggregated Polling API 10 times, and the Halifax endpoint 10 times within the same 24 hours.
POLLING PARAMETERS
-
Lloyds Banking Group will return up to 150 event notifications for every Aggregated Polling call made by the TPP.
-
Long Polling is not supported.
TPP REGISTRATION OF THE LLOYDS BANKING GROUP AGGREGATED POLLING API
If you are a new TPP currently on-boarding then you will be automatically registered to the Aggregated Polling API. If you are an existing TPP then you will be required to follow the instructions in section 2 of this document to use the Aggregated Polling API.
OPERATING WITHOUT ACKNOWLEDGEMENTS
Lloyds Banking Group provides aggregated polling without expecting acknowledgements.
CUSTOMER CONSENT
CUSTOMER CONSENT PROCESS
The customer consent process is described in Section 3.
CONSENT AUTHORISE ENDPOINTS
The below table describes all the Authorisation endpoints required to initiate the customer consent process. Consent authorisation endpoints are segment and brand specific e.g. https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/personal/oidc-api/v1.1/authorize is for the Lloyds brand and the Retail customer segment
For Authentication methods client_secret_basic and client_secret_post:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/personal/oidc-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/personal/oidc-api/v1.1/authorize
Halifax
https://authorise-api.halifax-online.co.uk/prod01/lbg/hfx/personal/oidc-api/v1.1/authorize
MBNA
https://authorise-api.mbna.co.uk/prod01/lbg/mbn/personal/oidc-api/v1.1/authorize
For Authentication method tls_client_auth:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/personal/mtls-token-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/personal/mtls-token-api/v1.1/authorize
Halifax
https://authorise-api.halifax-online.co.uk/prod01/lbg/hfx/personal/mtls-token-api/v1.1/authorize
MBNA
https://authorise-api.mbna.co.uk/prod01/lbg/mbn/personal/mtls-token-api%20/v1.1/authorize
For Authentication methods client_secret_basic and client_secret_post:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/business/oidc-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/business/oidc-api/v1.1/authorize
For Authentication method tls_client_auth:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/business/mtls-token-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/business/mtls-token-api/v1.1/authorize
For Authentication methods client_secret_basic and client_secret_post:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/oidc-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/oidc-api/v1.1/authorize
For Authentication method tls_client_auth:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/mtls-token-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/mtls-token-api/v1.1/authorize
Note: App to App functionality is not supported for Lloyds Bank and Bank of Scotland Commercial Clients.
RULES AND EXCEPTIONS
There are a number of important implementation variations relating to our customer consent process that TPPs should be aware of. These are listed below:
Article 10A exemptions will apply; this means for an active consent no further SCA is required for balance and transaction requests. LBG will apply SCA if requested by the AISP for the purpose of responding with transaction data sets beyond 90 days and/or other AIS endpoints (other than balance), or where objective reasons allow LBG to ‘step-up’ such as fraud management.
When an access token, which has a validity of 90 days, expires, then the TPP can request for a new access token by using a refresh token that is issued along with the access token when a consent is authorised. The PSU will not be required to do a reauthentication for the TPP to get a new access token.
However, if the refresh token, which has a validity of 365 days, is also expired, then the TPP will need to initiate a reauthentication to get a fresh set of access and refresh tokens.
Please note:
When an account is closed, it can take up to 24hrs for the account holding record to be fully updated to all of our systems. During this period of synchronisation, it is technically possible for a PSU to initiate a reauthentication, however given the actual account is closed we will not share balance or transaction data, nor would it be possible to execute a payment.
App to App functionality is not supported for Lloyds Bank and Bank of Scotland Commercial Clients. TPPs should use the authorization_endpoint URI detailed in the well-known discovery endpoint:
For Authentication methods client_secret_basic and client_secret_post:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/oidc-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/oidc-api/v1.1/authorize
For Authentication method tls_client_auth:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/mtls-token-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/mtls-token-api/v1.1/authorize
BUSINESS AND COMMERCIAL CUSTOMERS
OVERVIEW
As well as Retail customers, Lloyds Banking Group’s API channel also enables TPPs to initiate payments and access data from Online for Business (O4B), Business Internet Banking (BIB) and Commercial Banking Online (CBO) customers.
RULES AND EXCEPTIONS
Notable implementation variations relating to our Business and Commercial customers are listed below:
Online Payment Control (OPC) support is currently available for PISP payments via the API channel for version 3.1 only. The Authorisation Type indicator is applicable to both Business Customers (O4B) and Commercial Clients (CBO).
For accounts that support > ‘1 to sign’ payments, the secondary approval occurs in direct channel. The payment status post initiation stage will not be available, therefore the final payment status will be ‘AcceptedSettlementInProcess’ or ‘Rejected’.
Domestic Single Immediate Payment v3.1
Domestic Scheduled Payments v3.1
International Payments v3.1 (Business Only)
File Payments v3.1 (Business Only)
App to App functionality is not supported for Lloyds Bank and Bank of Scotland Commercial Clients. TPPs should use the authorization_endpoint URI detailed in the wellknown discovery endpoint:
For Authentication methods client_secret_basic and client_secret_post:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/oidc-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/oidc-api/v1.1/authorize
For Authentication method tls_client_auth:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/mtls-token-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/mtls-token-api/v1.1/authorize
This applies for all AISP/PISP journeys.
Lloyds Bank and Bank of Scotland Commercial (CBO) journeys are not currently supported.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Commercial (CBO) functionality is currently being developed and will be available in due course.
File Payments v3.1
File Payments v3.1
The file type must contain one of these values. This is the Namespaced Enumeration that details the payment file type
UK.LBG.O4B.BULK.BACS
UK.LBG.O4B.BATCH.FPS
If the file type contains any other value the request will be rejected
Execution date will be calculated from the supplied file contents.
File Payments v3.1
The ‘Requested Execution date’ will be ignored if it comes in the consents journey message payload.
Execution date will be ascertained from the file contents.
File Payments v3.1
Characters in String fields are restricted to a specific char set and special characters are not allowed. If received, those chars will not be propagated to onward payment or records.
FPS scheme (ISO8583) format
BACS Scheme Standard 18
CHAPS Scheme SWIFT format
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
File Payments v3.1
For Commercial (CBO) clients:
BACS – Payments received after 17:00will be rejected
CHAPS – Payments received after 17:25 will be rejected
FPS – Payments received after 23:55 will be processed the next day
IAT – Transfers received after 23:45 will be rejected
For Business (O4B) clients:
Business (O4B) clients processing a Bulk payment file will see a warning message displayed on the Lloyds Banking Group Secure Payments Gateway screens from 17:45. This warns of the impending cut off time. This will be displayed until 18:00 which is the hard cut-off time.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
File Payments 3.1
Due to the use of complex credit facilities and the manual payment referrals process, the confirmation of funds service will provide an explanatory message for Commercial (CBO) clients. This will be provided in Supplementary data.
Data will get truncated where CSV file fields contain more characters than supported by the BACS, CHAPS and FPS payment schemes
FPS scheme (ISO8583) format
BACS Scheme Standard 18
CHAPS Scheme SWIFT format
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
File Payments v3.1
The following local instrument types are acceptable for Commercial Clients:
UK.OBIE.BACS
UK.OBIE.CHAPS
UK.OBIE.FPS
UK.LBG.IAT
If the local instrument does not contain one of these values the consent request will be rejected.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
File Payments v3.1
Commercial (CBO) clients will not have access to the following end points:
Products
Offers
Statements
International Payments
IFile Payments
Account Information v3.1
File Payments v3.1
International Payments v3.1
International Scheduled Payments v3.1
International Standing Orders v3.1
Business clients (O4B) will not have access to the following end points:
GET /file-payments/{FilePaymentId}/report-file;
GET /file-payments/{FilePaymentId}/paymentdetails
File Payments v3.1
SCASupportData block is not supported by LBG. If received in the request, would result in the failure of the payment request.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1 (Businessonly)
International Payments v3.1 (Business only)
Lloyds Banking Group display maximum of 500 direct debit for commercial (CBO) client per account. For more information about Direct Debits not shown please visit our Support Centre.
This applies for commercial (CBO) journeys.
Lloyds Banking Group display maximum of 500 standing orders for commercial (CBO) client per account. For more information about Standing Orders not shown please visit our Support Centre.
Payment Risk Categorisation must be included in OBRisk.
Payment Context Code
In order for PISP initiated payments to be processed correctly we require each payment to be categorised as per the OBIE specifications.
TPPs must correctly classify payments into the following categories:
- Ecommercegoods
- Ecommerceservices
- BillPayment
- Other
- PartytoParty
- BillingGoodsAndServicesInAdvance
- BillingGoodsAndServicesInArrears
- PispPayee
- EcommerceMerchantInitiatedPayment
- FaceToFacePointOfSale
- TransferToSelf
- TransferToThirdParty
Payment Context Code Field in the Risk Section is a mandatory requirement.
Please note that for Commercial customers, only PartytoParty is applicable.
Domestic Single Immediate Payments v3.1
Domestic Scheduled Payments v3.1
Domestic Standing Orders v3.1 (Business only)
International Payments v3.1 (Business only)
If final payment status is not “AcceptedSettlementCompleted” or “Rejected” then payment status can be enquired up to 3 days (72 hours) from original transaction. After that TPPs will need to raise query with bank to check the status.
Domestic Single Immediate Payments v3.1 (Business Only)
File Payments (Batch Payments) (Business Only)
APP TO APP
The following section contains useful information for TPPs who wish to initiate App to App re-direction for Lloyds Banking Group Mobile apps.
OVERVIEW
App to App enables TPPs to the initiate the Authorisation and Consent journey via the Lloyds Banking Group Personal and Business Banking mobile applications. This allows the TPP to redirect a user from the TPP application (in a mobile web browser or mobile app) to the Lloyds Banking Group mobile application installed on the user’s device and deep link the user into the Lloyds Banking Group mobile application login screen. The user is then authenticated on their Lloyds Banking Group mobile application using the same credentials/methods as normally used when the user logs into their account using the application (e.g. biometric). In the scenarios where the user does not have the Lloyds Banking Group mobile application installed, they will be redirected to the Lloyds Banking Group browser journey as normal. In the scenarios where the user does not have the Lloyds Banking Group mobile application installed, they will be redirected to the Lloyds Banking Group browser journey as normal.
APP TO APP IMPLEMENTATION
There is no additional changes required by the TPP to implement App to App. The consent authorisation endpoints listed in Section 7 will automatically re-direct customers to the relevant Lloyds Banking Group mobile app. If TPPs support a desktop journey only then the authorisation endpoints in Section 7 will continue to re-direct customers to the Lloyds Banking Group desktop consent authorisation journey.
RULES AND EXCEPTIONS
Notable implementation variations relating to App to App and Browser to App.
App to App functionality is not supported for Lloyds Bank and Bank of Scotland Commercial Clients. TPPs should use the authorization_endpoint URI detailed in the well-known discovery endpoint:
For Authentication methods client_secret_basic and client_secret_post:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/oidc-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/oidc-api/v1.1/authorize
For Authentication method tls_client_auth:
Lloyds Bank
https://authorise-api.lloydsbank.co.uk/prod01/lbg/lyds/commercial/mtls-token-api/v1.1/authorize
Bank of Scotland
https://authorise-api.bankofscotland.co.uk/prod01/lbg/bos/commercial/mtls-token-api/v1.1/authorize
When non-Chrome browsers (like Samsung browser or Firefox browser) are used to perform the journey and/or are default browsers in the phone, they don’t let the universal link open the native application, even if the native application is already installed. They force the user to stay in the browserjourney. To enable the journey to continue in the native app, “Open links in native app” setting must be enabled in these browsers or Chrome browser, which always works with universal links, should be used.
This is applicable for both App to App and Browser to App journeys.
OPEN DATA APIS
The following section contains useful information for TPPs who wish to consume Lloyds Banking Group’s Open Data APIs, broken down by each group of APIs.
ATM / BRANCH
For ATMs that are linked to a physical branch, ATM API Branch Identification = Branch API Branch Identification.
For ATMs that are not linked to a physical branch, the ATM API Branch Identification’s final 2 digits are ‘99’.
PCA
The data standard does not currently allow for conditions to be associated with certain fees and benefits. Lloyds Banking Group has addressed this by including notes with the related items. TPPs should be aware of this when consuming the data in the API. For example, as at launch of the API, the following notes were included in the data for certain products:
Notes from OtherFeesCharges for Club Lloyds:
The Club Lloyds monthly account fee comprises of:
Club Lloyds monthly account fee is Free or £3 per month.
The £3 fee is waived for each month you pay in at least £1,500 into your account. If in any month you don't pay in this amount, you will need to pay the £3 monthly account fee.
Notes from OtherFeesCharges for Club Lloyds Platinum:
The Club Lloyds Platinum monthly account fee comprises of:
- Platinum Account monthly account fee of £17 per month
- Club Lloyds monthly account fee is Free or £3 per month
The £3 fee is waived for each month you pay in at least £1,500 into your account. If in any month you don't pay in this amount, you will need to pay the £3 monthly account fee.
Maximum combined monthly account fee of £20 per month.
Notes from FeaturesBenefits for Halifax Reward:
£3 reward each month you pay in £750 or more, pay out at least 2 different direct debits and stay in credit. If in any month you miss out on the £3 reward, you can still get it in future months too (when you meet the qualifying requirements.
Notes from FeaturesBenefits for Halifax Ultimate Reward Account:
A lower monthly fee of £12 applies if in the previous calendar month you pay in £750 or more and pay out at least 2 different direct debits and remain in credit.
You also need to keep your account open/not change it to a different current account until the fee is due to be debited (by the 2nd working day of the following calendar month).
Lloyds Banking Group has the following products that do not provide an overdraft facility, and has referenced this as a product Note on the PCAMarketingState tab
- Lloyds Basic Account
- Lloyds Under 19’s Account
- Bank of Scotland Basic Account
- Bank of Scotland Under 19’s Account
- Halifax Basic Account
- Halifax ExpressCash Account
Account Information API can only be linked to the Open Data for front book (on sale) products. Where Product Identifier is returned for a particular customer account (following a call to Account Information /accounts/{AccountId}/product) it means that the customer is on a product for which the terms, features and benefits can be found in the Open Data. This Product Identifier can be used to locate that product in the Open Data PCA API
This linking mechanism is only available at a product level so if multiple marketing state variations exist in Open Data for that product then the TPP should engage in further dialogue with the account holder to determine which applies to their present situation.
For example, for the Lloyds Bank Student product terms vary depending on the academic year the student is in. These are represented as marketing states in the Open Data API, so while the linkage will allow a TPP to identify if the customer has a student product it will not facilitate the identification of the year of study, therefore the TPP will have to gather further information from the customer to identify the relevant PCA information.
Distinction between promotion ending and destination products:
- Promotions are detailed on the MarketingState within each applicable product. For example, in URCA, the Marketing State section indicates that there is a promotional offer available on the product, the duration and what this relates to, e.g. overdraft switcher offer for 6 months. There is then a promotional section with details of the overdraft offer and a regular section with the standard overdraft details. The promotional section includes notes on the promotion and the fee is showing as zero, whereas in the regular tab it has 1p per £7 borrowed.
- Destination products – on a student account, the customer will eventually graduate and not be eligible. The next account is not detailed.
Lloyds Banking Group has the following products that offer Credit Interest on account balances within a defined tier and this will be reflected on the CreditInterest tab. Any account balance outside of the defined tier values will not receive credit interest.
- Lloyds Under 19’s Account
- Lloyds Club Lloyds Account
- Lloyds Club Platinum Account
- Halifax ExpressCash Account
- Bank of Scotland Under 19’s Account
- Bank of Scotland Classic Vantage Account
- Bank of Scotland Platinum Vantage Account
BUSINESS CURRENT ACCOUNTS (BCAS) - £0 - £1M TURNOVER
Overdraft/Notes
OverdraftFeeCharge Cap/Notes
FeeChargeDetail(ID)/ FeeType
FeeChargeDetail(ID)/ OtherFeeType
FeeChargeDetail(ID)/ FeeCategory
FeeCategory to FeeType mapping from CodeList references different enumerations compared to DD and Swagger specifications; the reason for this because the stated enumerations do not accurately reflect the categorisation of Fees and Charges by Lloyds Banking Group.
This will not impact consumption of the data because the enumeration mappings are not forced within the Swagger.
FeeChargeDetail(ID)/ FeeAmount
FeeChargeDetail(ID)/ Notes
For some FeeTypes, the corresponding FeeAmount fields may be blank because:
Conditions may apply which determine what price is charged for a particular transaction.
The price of a particular transaction may vary depending on Customer and/or Account behaviour.
The price of a particular transaction may be controlled/determined by a third party (i.e. not Lloyds Banking Group).
Prices for a particular non-standard transaction are available via a discussion with the Customer.
Anywhere where the FeeAmount field is blank will be explained/supported within the corresponding Notes field, linked via the corresponding FeeChargeDetail (ID) value.
Transactional data made available via the Account Information API can only be linked/mapped to the Open Data API for front book (on sale) products only; these include products which may have elements within them which are no longer offered (e.g. discontinued overdraft offerings no longer available for new lending).
Where a Product Identifier is returned for a particular customer account (following a call to Account Information /accounts/{AccountId}/product) it means that the account is on a product for which the terms and conditions, features and benefits, and pricing information can be found in the Open Data API content. This Product Identifier can be used to locate that product within the Open Data BCA API content.
Exceptions to the above will be where an underlying product may be shared by different customer segments (e.g. which have distinct Terms and Conditions which will apply) each of which is published via the Open Data API, but where customer and/or segment level (in addition to Account-level) information would be required to determine the correct mapping; this complexity for specialist BCA products is not supported at this time. Examples of these products would be the Schools Account, Treasurers’ Account and Credit Union Account.
SME BUSINESS CURRENT ACCOUNTS (BCAS) - TURNOVER £1M-25M
Several fees have been bundled under the ‘Other’ FeeCategory as the codelist supplied did not sufficiently represent the type of fee (description).
Fees and charges are generally unsorted. It was unknown whether they should be sorted according to FeeCategory, how we as a bank should wish to sort them or how a TPP would approach sorting and display to the customer. In addition, if sorted by FeeCategory the fees under the ‘Other’ FeeCategory may be badly ‘positioned’ in a list. Criteria for sorting or presentation of data may also apply equally to features and benefits.
Where fees have been represented under the ‘Other’ FeeCategory the description of the fee will reside under the ‘OtherFeetype’ construct.
Where fee amounts (FeeAmounts) could not be represented by a single value then they are defined under the FeeChargeDetail construct.
SME LOANS (SMELS) - £0 - £1M TURNOVER
SME LOANS (SMELS) - £1M - £25M TURNOVER
BUSINESS CREDIT CARDS
DATA LATENCY IN LLOYDS BANKING GROUP OPEN DATA API
TPPs should be aware that on the initial release of Open Data v2.1.1, in some circumstances (for example Bank of England rate changes), the Open Data API may be up to 18 hrs out of sync with equivalent data presented via the bank’s public website. TPPs can expect full synchronicity at the latest by 18:00 each day.
TPPs are advised to consider the possibility of this latency in the design of their services, communications with PSUs and, in the case of price comparison uses, take steps to advise the PSU that in exceptional circumstances the product available at the point of application may differ from that at the point of comparison.