Guide to using Lloyds Banking Group APIs
There is currently no standardised way for ASPSPs to communicate the differences in ASPSP implementations.
This covers both:
The above can generate challenges to TPPs as they will not know:
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.
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.
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.
Log into the Developer Portal by clicking the 'Log in with Open banking' 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 (This is used to identify who is calling our APIs). To create an application, log into the developer portal,v 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 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.
Follow the On-Board Using Dynamic Client Registration for onboarding instructions using DCR.
Access our consent domains from browser :
https://authorise.lloydsbank.co.uk/ib/pb/cwa/404
https://authorise.halifax-online.co.uk/ib/pb/cwa/404
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) – TLS Client Auth
Personal
Business
Commercial
Personal
Business
Commercial
Discovery Endpoints (eIDAS) - TLS Client Auth
Personal
Business
Commercial
Personal
Business
Commercial
"token_endpoint_auth_methods_supported":["tls_client_auth"]
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. (private_key_jwt), instead we support Mutual-TLS Client Authentication (tls_client_auth).
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.
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.
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 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'
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However, this is optional for the OBWAC, OB Transport.
client_credentials
The grant type being requested
c1d81a9a-609a-47be-9363- 8fa038b987da
The Client ID of your application registered in the developer portal
accounts
The scope being requested
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":{}}'
Please refer to the Other Useful Information section for all brand specific domains
Bearer
AAIkMDM5NDJmZTUtOGNiMi00NzVmL WIwMTItNDgyZjM0ZTE........
The access token obtained in step 1
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
{"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":{}}
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.
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.
code id_token
The OAuth flow type being used
c1d81a9a-609a-47be-9363-8fa038b987da
The Client ID of your application registered in the developer portal
12345
The state as specified by the TPP
openid accounts
The scope being requested
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.
4987594875485-j
The nonce as specified by the TPP
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
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).
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.
Following the OAuth2.0 protocol, you now exchange the access code for the access token required for step 6.
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 \
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However, this is optional for the OBWAC, OB Transport.
c1d81a9a-609a-47be-9363-8fa038b987da
Client ID of your application registered in the developer portal
Example Value:
authorisation_code
Description:
The grant type being requested
The redirect URL which must match that of the application registered in the developer portal
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
The authorisation code retrieved in step 3
Take note of the access token and ID Token in the response data.
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.
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'
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However, this is optional for the OBWAC, OB Transport.
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 0lnDggbvLwrHkw
The token obtained in step 5
When the TPP makes the token call to exchange the Access code for Access token using Authorization Code Grant Type, they get back a Refresh Token in addition to the Access Token. This Refresh Token is valid for 365 days and Access Token itself is valid for 90 days . TPPs will need to ensure that they make the token call with Refresh Token Grant Type to exchange the Refresh Token to get a new Access token and Refresh token before the existing Refresh Token expires to avoid customer having to complete a re-authentication journey. Refresh tokens are one time use tokens and each time the TPP uses it, they will receive a new set of Access and Refresh tokens.
Refresh Token is only available for consumers of Accounts and Transactions, Confirmation of Funds, and Variable Recurring Payment APIs.
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'
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
refresh_token
The grant type being requested
c1d81a9a-609a-47be-9363- 8fa038b987da
The Client ID of your application registered in the developer portal
AAImRufQlWgaSyEiT6aw0MhiivaI5daPew3iL9ulWrYkcH VZZutghJ86mRdxLL6NuKKsweP JwGWYqXR21TtqETuv0Xeov1iqJrHiqYFP65pwh6FU bIdTG3nLJ5MKAzmCda6ZfCB W6gYo0eGKBdqBC9CU35WV8zLLWtSXk83I GuvYtJemxUyh1P_vpNGEQXz MfCr7K4jiJmqyuETTFyLRPv495gvPAszcyDfHCciY vaQTgfiCcmvI_WOa6kImepD8 7Bcep1DHbV8dm6wcPSXxkb mTkw2UsNgpWhkNAGKjzvkgt 7LW2akF0IizRLFtpyVCbgiTw2yBeBR_kRMHTT6vR 7yzZgLzWAgWHIqOSxPEbaA HW6uIeZgcfSb4CkURs251sxe QtnudJRFywd0PQxNHweVBu9mDmlogGCF _PvmMb71OwyAGBBlm7oTG d4afIS_h0- i5_ByNtnBhu_d4sn0U2cN'
Refresh token received with the previous Access token
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/mtls-token-api/v1.1/authorize is for the Lloyds brand and the Retail segment
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 /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 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 customers.
There are several important implementation variations relating to our customer consent process that TPPs should be aware of. These are detailed in the table 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 customer 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 b e fully updated to all of our systems. During this period of synchronisation, it is technically possible for a customer to initiate a re-authentication, however given the actual account is closed we will not share balance or transaction data, nor would it be possible to execute a payment.
The timeout period for a customer undertaking an AISP, a PISP or a CoF journey is 20 minutes from the start of session, however the timeout also happens in case of 10 minutes of inactivity during this 20 minutes period. At the point of the timeout, the user will be redirected to the bank’s public site.
If during an AISP, a PISP or a CoF journey, a customer closes the browser by mistake, the customer will have to start the journey afresh with the TPP.
We are able to suspend and reactivate customer consents to TPPs, on a customer's behalf.
The following section contains useful information for TPPs who wish to initiate App to App re-direction for Lloyds Banking Group Mobile apps.
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.
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.
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 customers.
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 browser journey. 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
This section provides an overview of how to use our Account and transaction Services APIs. It is intended to help AISPs integrate applications and services with our APIs and details scope and any variations from Open Banking API specifications.
This detail should be read in conjunction with Open Banking Specifications and our API Products:
Account and Transaction Scope
The below table details the Account and Transaction Services that are supported by Lloyds Banking Group across our Channels and Products.
These are available to use to request Account and Transaction from Current and Savings accounts on our core brands Lloyds Bank, Bank of Scotland, Halifax (Retail only). In addition, we also support our core brands and MBNA brand for Retail Credit Cards.
Account Access Consent
✓
✓
✓
✓
✓
✓
✓
✓
Accounts
✓
✓
✓
✓
✓
✓
✓
✓
Balances
✓
✓
✓
✓
✓
✓
✓
✓
Transactions
✓
✓
✓
✓
✓
✓
✓
✓
Beneficiaries (Domestic)
✓
✓
✓
✓
✓
✓
Beneficiaries (International)
✓
✓
✓
✓
Direct Debit
✓
✓
✓
✓
✓
Standing Order
✓
✓
✓
✓
✓
Products
✓
✓
✓
✓
Offers
✓
✓
Parties
✓
✓
✓
✓
✓
✓
✓
Schedule Payments
✓
✓
✓
✓
✓
✓
Statements
✓
✓
✓
✓
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fields have also been implemented.
OBReadConsesntResponse1.Data
✓
✓
✓
ConsentId
✓
✓
✓
Account Request Id
✓
✓
Status
✓
✓
✓
CreationDateTime
✓
✓
✓
StatusUpdateDateTime
✓
✓
✓
Permissions
✓
✓
✓
ExpirationDateTime
✓
✓
✓
TransactionFromDateTime
✓
✓
✓
TransactionToDateTime
✓
✓
✓
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fields have also been implemented.
Data.Account
✓
✓
✓
AccountId
✓
✓
✓
Currency
✓
✓
✓
AccountType
✓
✓
✓
AccountSubType
✓
✓
✓
Maturity Date
✓
NickName
✓
✓
Opening Date
✓
✓
✓
SwitchStatus
✓
Data.Account.Account
✓
✓
✓
SchemeName
✓
✓
✓
Identification
✓
✓
✓
Name
✓
✓
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
GET /accounts
GET /accounts/{AccountId}
Field name “SwitchStatus”
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.
GET /accounts
GET /accounts/{AccountId}
Field name “Name”
The account name displayed for different customer segments are given below
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fields have also been implemented.
Data.Balance
✓
✓
✓
AccountId
✓
✓
✓
CreditDebitIndicator
✓
✓
✓
DateTime
✓
✓
✓
Type
✓
✓
✓
Data.Balance.Amount
✓
✓
✓
Amount
✓
✓
✓
Currency
✓
✓
✓
Data.Balance.CreditLine
✓
✓
✓
Included
✓
✓
✓
Type
✓
✓
✓
Data.Balance.CreditLine.Amount
✓
✓
✓
Amount
✓
✓
✓
Currency
✓
✓
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
GET /accounts/{AccountId}/balances
High Cost of Credit: Field name “Type”
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 customer 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
GET /accounts/{AccountId}/balances
Field name “Amount”
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.
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fields have also been implemented.
Data.Transaction
✓
✓
✓
AccountId
✓
✓
✓
TransactionReference
✓
✓
✓
Amount
✓
✓
✓
Currency
✓
✓
✓
CreditDebitIndicator
✓
✓
✓
Status
✓
✓
✓
BookingDateTime
✓
✓
✓
ValueDateTime
✓
✓
✓
TransactionInformation
✓
✓
✓
AddressLine
✓
✓
Data.Transaction.
BankTransactionCode
✓
✓
Code
✓
✓
SubCode
✓
✓
Data.Transaction.
ProprietaryBank
TransactionCode
✓
✓
✓
Code
✓
✓
✓
Issuer
✓
✓
✓
Data.Transaction.
Balance
✓
✓
Amount
✓
✓
Currency
✓
✓
CreditDebitIndicator
✓
✓
Type
✓
✓
Data.Transaction.
MerchantDetails
✓
✓
MerchantName
✓
✓
MerchantCategoryCode
✓
✓
Data.Transaction.
CardInstruments
✓
CardSchemeName
✓
Authorisation Type
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
/account/{AccountID}/Transactions
Transactions exception
For the following transaction there will be two records provided to 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.
/account/{AccountID}/Transactions
Partial Transactions
No partial transaction data will be provided to TPPs. Instead, the TPP will be sent a 400 response.
/account/{AccountID}/Transactions
Transaction reference
"TransactionReference" will only be provided for posted transactions that have Transaction Code "FPO".
/account/{AccountID}/Transactions
Transaction date and Time
Though we comply to the full ISO date time formats, Transaction “from” and “To” booking dates with time segment set can be subject to date roll which could affect the set of transactions served
/account/{AccountID}/Transactions
Credit card Transactions
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, 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.
/accounts/{AccountId}/Transactions
Merchant category code
The merchant category code for balance transfer and money transfer will not be returned to the TPP as these are used only for internal processing.
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.Beneficiary
✓
AccountId
✓
BeneficiaryId
✓
Reference
✓
Data.Beneficiary.SupplementaryData
✓
Data.Beneficiary.CreditorAccount
✓
SchemeName
✓
Identification
✓
Name
✓
Data.Beneficiary.CreditorAgent
✓
SchemeName
✓
Identification
✓
Name
✓
Data.Beneficiary.CreditorAgent.PostalAddress
✓
Country
✓
AddressLine
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
/accounts/{AccountId}/beneficiaries
Display order for beneficiaries
Beneficiaries are returned in the following order
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}/beneficiaries
Beneficiary postal address
This will contain the Beneficiary Address for the International Beneficiaries
/accounts/{AccountId}/beneficiaries
Field name “Name”
Name of the account, as assigned by the account servicing institution, in agreement with the account owner 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.
/accounts/{AccountId}/beneficiaries
Field name "SchemeName”
Name of the identification scheme, in a coded form as published in an external list
/accounts/{AccountId}/beneficiaries
Beneficiary
This includes Domestic, BACS and International beneficiaries for Commercial accounts.
All beneficiaries returned in this endpoint are “trusted” beneficiaries.
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.DirectDebit
✓
AccountId
✓
MandateIdentification
✓
DirectDebitStatusCode
✓
Name
✓
PreviousPaymentDateTime
✓
Frequency
✓
Data.DirectDebit.PreviousPaymentAmount
✓
Amount
✓
Currency
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
GET/accounts/{Accountid}/direct- debits
Commercial CBO
Maximum of 500 direct debit for commercial (CBO) customers per account are returned. For more information about Direct Debits not shown please visit our Support Centre.
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.StandingOrder
✓
AccountId
✓
Frequency
✓
Reference
✓
FirstPaymentDateTime
✓
FirstPaymentAmount
✓
Currency
✓
NextPaymentDateTime
✓
NextPaymentAmount
✓
Currency
✓
FinalPaymentDateTime
✓
FinalPaymentAmount
✓
Currency
✓
StandingOrderStatusCode
✓
Data.StandingOrder.CreditorAccount
✓
SchemeName
✓
Identification
✓
Name
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
GET /accounts/{AccountId}/standing-orders
Commercial CBO
Maximum of 500 standing orders for commercial (CBO) customers per account. For more information about Standing Orders not shown please visit our Support Centre.
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.Product
✓
ProductId
✓
ProductName
✓
SecondaryProductId
✓
Data.Product.PCA.ProductDetails
✓
ProductDetails
✓
CreditInterest
✓
Overdraft
✓
CreditInterest.TierBandSet
✓
TierValueMax
✓
OtherFeesCharges
✓
Data.Product.BCA.ProductDetails
✓
CreditInterest
✓
Overdraft
✓
OtherFeesCharges
✓
Data.Product.OtherProducts Type
✓
OtherProductType
✓
Name
✓
Description
✓
MaturityDate
✓
Data.Product.BCA.CreditInterest
✓
Calculation Method
✓
Destination
✓
TierValueMaximum
✓
DepositInterestAppliedCoverage
✓
BankInterestRateType
✓
BankInterestRate (O)
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
Supplementary product information
Supplementary product information and links to Terms and Conditions are provided in ‘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
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
Segment field
Optional “Segment” field is provided for PCA only to help provide account comparison.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
OBReadProduct2/Data/Product/BCA
Overdraft
Details of overdrafts will only be published if the customer currently uses the overdraft facility available on their account
Details about overdraft rates, fees & charges. Provided where applicable.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
OBReadProduct2/Data/Product/BCA
CreditInterest
Details about the interest that may be payable to the PCA, BCA account holders. Provided where applicable.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
TierBandMethod
The methodology of how overdraft is charged. It can be
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
Field name “TierValueMin”
Minimum value of Overdraft Tier/Band
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
Field name “TierValueMax”
Maximum value of Overdraft Tier/Band
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
Field name “EAR”
EAR means Effective Annual Rate and/or Equivalent Annual Rate (frequently used interchangeably), being the actual annual interest rate of an Overdraft.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/PCA
OBReadProduct2/Data/Product/BCA
OtherFeesCharges
Contains details of fees and charges which are not associated with either borrowing or features/benefits. Provided where applicable.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
OtherProductType
Other Product type will contain only Savings accounts. The values returned will be either Personal Savings Account or Business Savings Account.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
TierBandMethod
The methodology of how credit interest is paid/applied.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “Name”
Long name associated with the product
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “Description”
Description of the Product associated with the account
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “MaturityDate”
Maturity date for the account
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “Calculation Method”
Methods of calculating interest.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “Destination”
Describes whether accrued interest is payable only to the PSA/BSA or to another bank account.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “TierValueMinimum”
Minimum deposit value for which the credit interest tier applies.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “TierValueMaximum”
Maximum deposit value for which the credit interest tier applies.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “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/BSA
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “DepositInterestAppliedCoverage”
Amount on which interest is applied
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “FixedVariableInterestRateType”
Type of interest rate i.e. variable
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “AER”
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.
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “BankInterestRateType”
Interest rate types, other than AER, which financial institutions may use to describe the annual interest rate payable to the PSA/BSA
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “BankInterestRate (O)”
Bank Interest for the PSA/BSA product
/account/{AccountID}/Product
OBReadProduct2/Data/Product/BCA
Field name “Overdraft arrangements”
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: ‘Overdraft’ array. The above describes additional detail with regards to the application of the “UnauthorisedBorrowing” 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.
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.Offers
OfferId
✓
OfferType
✓
Description
✓
StartDateTime
✓
EndDateTime
✓
Rate
✓
Term
✓
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.Party
✓
PartyType
✓
Full Legal Name
✓
Legal Structure
✓
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.ScheduledPayment
✓
ScheduledPaymentId
✓
Reference
✓
DebtorReference
✓
Data.ScheduledPayment.CreditorAccount
✓
Name
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
/accounts/{AccountId}/scheduled payments
BACS schedule payments
BACS Scheduled Payments will be available for Lloyds Bank and Bank of Scotland business accounts only.
In addition to all mandatory fields defined in Account and Transaction API specifications, the following optional fieldshave also been implemented.
Data.Statement
✓
StatementId
✓
StatementDescription
✓
{StatementID}/File
✓
There are several important implementation variations that AISPs should be aware of. These are detailed in the table below.
/accounts/{AccountId}/statements
/accounts/{AccountId}/statements/{StatementId}/file
In scope statements Endpoints
Lloyds Banking Group has implemented these two endpoints for statements
/accounts/{AccountId}/statements
Business Credit Card
CSV file is available only for the Business Credit Cards and for last 6 months.
Lloyds Banking Group supports the following Proprietary Bank Transaction Codes:
Scenarios applicable to all AIS endpoints
TPP attempts to access a resource for which the access has been revoked at the ASPSP.
(Sub-scenario: Access token not revoked; consent has been changed to Rejected/Expired by ASPSP.)
Http Status: 403
Error
Code: UK.OBIE.Resource.InvalidConsentStatus
Error
Type: AuthoriseConsent
Create a new consent using a POST operation.
Take the PSU through an authentication journey
TPP attempts to access a resource using an access token that has expired.
(Sub-scenario: The underlying consent has expired.)
Http Status: 403
Error
Code: UK.OBIE.Resource.InvalidConsentStatus
Error
Type: AuthoriseConsent
Create a new consent using a POST operation.
Take the PSU through an authentication journey
TPP attempts to access a resource using an access token outside of the SCA period. The underlying consent has not expired
Typically this applies to AIS resources that do not benefit from RTS Article 10.
Http Status: 403
Error
Code: UK.OBIE.Reauthenticate
Error
Type: Reauthenticate
Take the user through a re-authentication journey using the existing consent.
TPP attempts to access a resource related to an account that is closed.
This also applies in situations where the account holder that has wound up, is under receivership, is deceased or if the account has been switched over to another bank.
Http Status: 403
Error
Code: UK.OBIE.Resource.NotFound
Error
Type: AccountPermanentlyUnavailable
Do not attempt to request information for this account again.
Take the user through a re-consent journey to remove this account from the consent.
TPP attempts to re-auth a consent where one or more account has got closed.
This also applies in situations where the account holder that has wound up, is under receivership, is deceased or if the account has been switched over to another bank.
Error message returned in redirect URL:
One or more accounts are closed or suspended. Please re-consent for eligible accounts
Error Type: AuthoriseConsent
Do not attempt to re-auth this consent again.
Take the user through a re-consent journey to remove the closed account(s) from the consent.
TPP attempts to access an endpoint for which permission had not been provided when the consent was created.
Http Status: 403
Error Code:
UK.OBIE.Resource.ConsentMismatch
Error
Type: AuthoriseConsent
Do not attempt to request information for this endpoint again.
Take the user through a re-consent journey to add the permission if required.
TPP attempts to access an endpoint with an incorrect AccountID.
Http Status: 400
Error Code:
UK.OBIE.Field.Invalid
ErrorType:
RequestWithValidDetails
Do not attempt to request information for this accountID again.
Try again with a valid AccountID.
Endpoint specific scenarios
/account-access-consents
TPP attempts to pass invalid or no permissions in request body.
Http Status: 400
Error Code:
UK.OBIE.Field.Invalid
Error
Type: AuthoriseConsent
Refer to OBIE specs.
Take the PSU through the consent journey with valid permissions.
/account-access-consents
TPP sends the request with one of the following date related issues:
Http Status: 400
Error Code:
UK.OBIE.Field.InvalidDate
ErrorType:
AuthoriseConsent
Take the PSU through the consent journey with a valid dates.
/transactions
TPP requests for transactions with one of the following date related issues:
Http Status: 400
Error Code:
UK.OBIE.Field.InvalidDate
ErrorType:
RequestWithValidDetails
Send the request with valid dates.
/transactions
TPP requests for transactions outside the consented date range.
Http Status: 403
Error Code:
UK.OBIE.Field.InvalidDate
ErrorType:
RequestWithValidDetails
Do not attempt to request information for this date range again.
Request for transactions within the consented date range
Take the user through a re-auth journey to extend or modify the date range.
/balances
Commercial scenario: TPP attempts to access balances for a commercial PSU who has created the consent but does not have sufficient entitlement (as a part of his/her role) to access the information.
Http Status: 403
Error Code:
UK.OBIE.Field.Unexpected
Error Type:
AuthoriseConsent
Inform the PSU that they don’t have sufficient entitlement to access the information.
Take the PSU through a re-consent journey after the PSU confirms that sufficient entitlements have been given to them.
Generic service unavailable error scenario
ASPSP downstream services or server is down.
Http Status: 500
Error Code:
UK.OBIE.UnexpectedError
ErrorType: RetryLater
Try again after some time.
This section provides an overview of how to use our Confirmation of Funds APIs. It is intended to help CBPII integrate applications and services with our APIs and details scope and any variations from Open Banking API specifications.
This detail should be read in conjunction with Open Banking Specifications and our API Products:
Confirmation of Funds Scope
The below table details the confirmation of funds Services that are supported by Lloyds Banking Group across our Channels and Products.
These are available to use to request Confirmation of funds on our core brands Lloyds Bank, Bank of Scotland, Halifax (Retail only). In addition, we also support our core brands and MBNA brand for Retail Credit Cards.
Funds confirmation consent
✓
✓
✓
✓
✓
✓
✓
✓
Funds confirmation
✓
✓
✓
✓
✓
✓
✓
✓
ERROR SCENARIOS
Scenarios applicable to CoF endpoints
TPP attempts to access a resource using an access token that has expired.
(Sub-scenario: The underlying consent has not expired.)
Http Status: 401
Error Code: Token expired
Error Type: Reauthenticate
If the TPP has a valid refresh token, use the refresh token to get a new access token.
If the refresh token has expired as well, take the user through a re-auth
TPP attempts to access a resource using an access token that has expired.
(Sub-scenario: The underlying consent has expired.)
Http Status: 403
Error
Code: UK.OBIE.Resource.InvalidConsentStatus
Error Type: AuthoriseConsent
Create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to access a resource related to an account that is closed.
This also applies in situations where the account holder that has wound up, is under receivership, is deceased or if the account has been switched over to another bank.
Http Status: 403
Error
Code: UK.OBIE.Resource.NotFound
Error
Type: AccountPermanentlyUnavailable
Do not attempt to request information for this account again.
Take the user through a re-consent journey to remove this account from the consent.
TPP attempts to re-auth a consent where one or more account has got closed.
This also applies in situations where the account holder that has wound up, is under receivership, is deceased or if the account has been switched over to another bank.
Error message returned in redirect URL:
One or more accounts are closed or s uspended. Please re-consent for eligible accounts
Error Type: AuthoriseConsent
Do not attempt to re-auth this consent again
Take the user through a re-consent journey to remove the closed account(s) from the consent.
/funds-confirmation-consents
TPP sends a past date in ExpirationDateTime field or the date format is incorrect.
Http Status: 400
Error Code:
UK.OBIE.Field.InvalidDate
Error Type: AuthoriseConsent
Take the PSU through the consent journey with a valid future ExpirationDateTime.
/funds-confirmation-consents
TPP sends an invalid value in the consents creation request in one of the following fields (i.e. validation fails):
Http Status: 400
Error Code: UK.OBIE.Field.Invalid
Error Type: AuthoriseConsent
Try again with a valid value as per OBIE specs
/funds-confirmation
TPP attempts to access the endpoint with an incorrect ConsentId
Http Status: 403
Error Code:
UK.OBIE.Resource.ConsentMismatch
ErrorType: RequestWithValidDetails
Do not attempt to request information for this ConsentID again.
Try again with a valid ConsentId.
/funds-confirmation
TPP attempts to access the endpoint with an invalid value in one of the following fields (i.e. validation fails):
Http Status: 400
Error Code: UK.OBIE.Field.Invalid
ErrorType: RequestWithValidDetails
Try again with a valid value in the request payload.
Generic service unavailable error scenario
ASPSP downstream services or server is down.
Http Status: 500
Error Code:
UK.OBIE.UnexpectedError
ErrorType: RetryLater
Try again after some time.
This section provides an overview of how to use our Payment Initiation Services APIs. It is intended to help PISPs integrate applications and services with our APIs and details scope and any variations from Open Banking API specifications.
This detail should be read in conjunction with Open Banking Specifications and our API Products:
Payment Initiation API Specification can be found here.
Variable Recurring Payments API Specification can be found here.
API Products can be found here.
Payments Scope
The below table details the Payment Initiation Services that are supported by Lloyds Banking Group for each Payment Type across our Channels and Products.
These are available to use to make payments from Current and Savings accounts on our core brands Lloyds Bank, Bank of Scotland, Halifax (Retail only). In addition, we also support our core brands and MBNA brand to make payments from Retail Credit Cards.
Domestic Payment (FPS)
✓
✓
✓
✓
✓
Domestic Payment (BACS)
✓
Domestic Payment (CHAPS)
✓
Domestic Payment (Balance Transfer / Money Transfer)
✓
Domestic Scheduled Payments
✓
✓
✓
✓
✓
Domestic Standing Orders
✓
✓
✓
✓
International Payments
✓
✓
✓
File Payments
✓
Variable Recurring Payments
✓
✓
There are several important variations relating to Payment Initiation APIs that PISPs should be aware of for our Domestic Payment endpoints – Immediate, Scheduled and Standing Orders. These are detailed in the table below.
/domestic-payment-consents
/domestic-scheduled-payment-consents
/domestic-standing-order-consents
Payment Schemes supported for Domestic journeys.
Schemes supported across all domestic journeys are:
For Domestic Payment – Balance Transfer and Money Transfer must use UK.OBIE.PAN.
UK.OBIE.Paym is not supported, in line with Pay.UK removing the service in March 2023.
Note: APIs will support UK IBANs or UK BBANs only.
/domestic-payment-consents
/domestic-scheduled-payment-consents
/domestic-standing-order-consents
Payment/Instructed Amount Field Validations.
Negative payment amounts are not allowed in any of the Lloyds Banking Group payment requests.
Amounts are restricted to 2 decimal places. Requests sent where the amount exceeds 2 decimal places will result in error response
For Balance Transfers and Money Transfers the minimum payment amount is £100
/domestic-payment-consents
/domestic-scheduled-payment-consents
/domestic-standing-order-consents
Payment Risk Categorisation must be provided in OBRisk.
For PISP initiated payments to be processed the payment must be categorised. Payment Context Code field in OBRisk is mandatory.
There are some payment categories that will not be supported for Payment Type, Channel or Products.
Domestic Payment – Balance Transfer / Money Transfer
Acceptable values are ‘Party to Party’ or ‘Transfer to Self’. All other Payment Context Codes will not be accepted.
Savings Accounts are not supported for
/domestic-payment-consents
/domestic-scheduled-payment-consents
/domestic-standing-order-consents
SCA Exemption requests from PISPs is not supported.
PISPs cannot use SCA Support Data block to request SCA Exemption as this is not supported. If consent request is received, this will not be processed and will result in an error response.
/domestic-payment-consents
/domestic-scheduled-payment-consents
/domestic-standing-order-consents
Multi Party Authorisation - Support for > ‘1 to sign’ payments
Some Business customers have set up Multi Party authorisation for > ‘1 to sign’ payments using Online Payment Control (OPC).
PISPs should include OBAuthorisation1 data block in consent requests for these customers. Completion Date Time functionality is not supported
For payments that require Multi Party authorisation, additional approvals occur in our direct channel before the payments are processed, due to which the terminal payment status may not be available.
/domestic-payment-consents
Balance Transfers – Mandatory Requirements
Local Instrument: Is a mandatory field and must be provided as UK.OBIE.BALANCETRANSFER
Creditor Account:
Debtor Account: must be pre-populated in the consent request with details as:
RemittanceInformation: must be sent with Offer code/ID in the Reference field
/domestic-payment-consents
Money Transfers – Mandatory Requirements
Local Instrument: Is a mandatory field and must be provided as UK.OBIE.MONEYTRANSFER
Creditor Account:
Debtor Account: must be pre-populated in the consent request with details as:
RemittanceInformation: must be sent with Offer code/ID in the Reference field
/domestic-payment-consents
Commercial Customers – Local Instrument Types supported
The following local instrument types are acceptable for Commercial Customers:
If the local instrument does not contain one of these values the consent request will be rejected
/domestic-payment-consents
/domestic-scheduled-payment-consents
Commercial Customers - Debit Account Reference
Commercial channel (CBO) customers can specify a debit account reference utilising Supplementary Data. The reference can be a maximum of 18 characters in length.
/funds-confirmation
Commercial Customer – Funds Confirmation Response
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) customers. This will be provided in Supplementary data.
/domestic-scheduled-payment-consents
Scheduled Payment Execution Date Rules.
Earliest “Payment Instructed” day is next working day for Scheduled Payments.
Requested Execution Date cannot be the same date as consent request. The payment can be requested to be executed from the next working day and up to 31 days in the future.
Any Execution Date provided outside of this time frame would result in an error response.
/domestic-standing-order-consents
Variable Amounts not supported for Standing Orders
Variable amount values are not supported for first and subsequent payments and will result in an error response if received in the request.
/domestic-standing-order-consents
Timezone in FirstPaymentDateTime field
Time zone for FirstPaymentDateTime field would be defaulted to system timezone in case it is not sent in the request.
/domestic-standing-order-consents
Standing Order Execution Date Rules.
Earliest First Payment Date is next working day for Standing Orders. It cannot be the same date as consent request.
/domestic-standing-order-consents
“Number of Payments” recurrence is not supported.
"Number of Payments" feature is not supported.
"Final Payment Date" can be set, otherwise the standing order will be open ended until customer takes action to cancel.
/domestic-standing-order-consents
Supported Standing Order Frequencies
Only the following frequencies are supported by Lloyds Banking Group Domestic Standing orders:
Note: First Payment date and Final Payment 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)
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.
/domestic-payments
/domestic-scheduled-payments
/domestic-standing-orders
Time between Consent Authorisation and Payment Submission
There is a maximum time limit of 45 minutes for PISPs to complete payment submission following a successful authorisation of consent request.
Note: Where a first-time submission is recorded within the time limit mentioned above, any subsequent (idempotent) requests will return the status of the payment.
/domestic-payments
/domestic-scheduled-payments
/domestic-standing-orders
Payment Message Details.
Data will get truncated where API fields contain more characters than supported by the FPS scheme (ISO8583) format.
This would result in the beneficiary bank receiving truncated information. PISPs should be aware and may wish to cater for this in their front-end validation.
/domestic-payments
Payment Status – Enquiry Window.
PISPs can make enquiry call to find out the final outcome of payment. If the payment status has not reached a terminal payment status within 3 days (72 hours) then PISPs will need to raise a query with the Lloyds Banking Group.
Do not continue to poll the endpoint to query the payment status as this will result in error responses.
/domestic-payments
Commercial Customers - Domestic Payment Cut-Off times
BACS – Payments received after 17:00 will 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.
/payment-details
Endpoints not supported.
The implementation for File Payments does not support following optional/conditional endpoints in the API specification:
All Endpoints
Characters Sets for Domestic Journeys
Characters in String fields are restricted to a specific char sets and special characters are not allowed - if received, those chars will not be propagated to onward payment records or may result in an error response.
All Endpoints
JWS Base64 Encoding
JWS must be created with Base64 encoding. Failure to use the correct encoding in the creation of the JWS would result in an error response.
There are several important variations relating to Payment Initiation APIs that PISPs should be aware of for our International Payment endpoints. These are detailed in the table below.
Note: These relate to Immediate International Payments only. International Scheduled Payments and International Standing Orders endpoints are not supported by Lloyds Banking Group.
/international-payment-consents
Creditor Postal Address is mandatory.
The Creditor Postal Address is mandatory and must be provided in the consent request. Maximum three lines of unstructured address. Must include at least one Address Line and Country.
/international-payment-consents
Creditor Agent Address Requirements.
Creditor Agent must have at least either of the pairs provided:
Scheme Name and Identification or Name and Postal Address
Option 1: Scheme Name and Identification
Scheme Name accepted as UK.OBIE.BICFI, and BIC must be sent in Identification.
Creditor Agent Name and Address block are optional.
Option 2: Name and Postal Address
Creditor Agent Name is mandatory. Creditor Agent Postal Address block is mandatory and must be populated in the following format:
/international-payment-consents
Country Requirements - Sending money to the EEA and UK.
BIC/SWIFT and IBAN are mandatory requirements when sending money to the EEA and UK. PISPs will need to provide this information when sending International Payments to the following 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.
Creditor Account Scheme Name must be set to UK.OBIE.IBAN.
Creditor Agent Scheme Name must be set to UK.OBIE.BICFI and BIC/SWIFT must be sent in Identification.
/international-payment-consents
Country Requirements - Sending money to the rest of the world.
Option 1: BIC/SWIFT and IBAN mandatory countries
BIC/SWIFT and IBAN are mandatory requirements when sending money to some non-EEA countries. PISPs will need to provide this information when sending International Payments to the following 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.
Creditor Account Scheme Name must be set to UK.OBIE.IBAN.
Creditor Agent Scheme Name must be set to UK.OBIE.BICFI and BIC/SWIFT must be sent in Identification.
Option 2: National Clearing Code mandatory countries
National Clearing Codes are mandatory for the following countries and are expected to be sent as detailed below 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
Creditor Account Scheme Name can be sent as BBAN or SCAN
Creditor Agent Scheme Name must be UK.LBG.Clearingcode
Option 3: All other countries
Creditor Account Scheme Name can be IBAN, BBAN or SCAN.
Creditor Agent Scheme Name must be set to UK.OBIE.BICFI when IBAN is provided for Creditor Account, and BIC/SWIFT must be sent in Identification.
Creditor Agent Address must be sent when BBAN or SCAN are provided for Creditor Account, with the additional details being mandatory:
/international-payment-consents
Payment Risk Categorisation must be provided in OBRisk.
For PISP initiated payments to be processed the payment must be categorised
Payment Context Code field in OBRisk is mandatory
/international-payment-consents
Initiation Parent Block – Request Field Validations.
Charge Bearer: Borne by Creditor is not supported. Consent requests with this value will result in an error response.
Currency Of Transfer:
Instruction Priority: Lloyds Banking Group do not offer Instruction priority for International Payment requests. All requests will be treated as ‘Normal’.
Local Instrument: No value is expected to be received in this field
/international-payment-consents
Exchange Rate Information – Request Field Validations
Contract Identification and Exchange Rate: This functionality for ‘Agreed’ rates is not supported and therefore these fields must not be sent in the request.
Rate Type: Only "Actual" is supported. All other Rate Types provided in the request will result in an error response
Note: Where payment requires multiple party authorisations the Exchange Rate Information displayed to user and sent in the response will be ‘Indicative’.
Unit Currency: is a mandatory field within the exchange rate block. If this block is provided in the request, then this must be sent as GBP
/international-payment-consents
Instructed Amount & Currency – Request Field Validations.
Most currencies support two decimal places for Instructed Amount e.g. GBP
Certain currencies support up to a maximum of three decimal places i.e. Kuwaiti Dinar.
Japanese Yen must be sent as a whole integer value. Zero decimal points are supported for this currency
Note: When Currency Of Transfer has been provided as GBP, the Instructed Amount Currency must also be GBP.
/international-payment-consents
SCA Exemption requests from PISPs is not supported.
PISPs cannot use SCA Support Data block to request SCA Exemption as this is not supported. If consent request is received, this will not be processed and will result in an error response.
/international-payment-consents
Multi Party Authorisation - Support for > ‘1 to sign’ payments.
Some Business customers have set up Multi Party authorisation for > ‘1 to sign’ payments using Online Payment Control (OPC).
PISPs should include OBAuthorisation1 data block in consent requests for these customers. Completion Date Time functionality is not supported.
For payments that require Multi Party authorisation, additional approvals occur in our direct channel before the payments are processed, due to which the terminal payment status may not be available.
/international-payment-consents
Payment Reason Code – Country Requirements
Some Countries mandate the need for the purpose or reason for payment. PISPs are expected to provide this information in Extended Purpose field in the consent request for it to be processed
Note: Data.Initiation.Purpose as defined in the API specifications will not be used and may lead to error responses.
United Arab Emirates and Jordan: These countries require reason codes specific to their own country requirements. Please refer to detailed section on acceptable values.
All Other Countries: A generic set of reasons are used. These are also detailed separately and should be referred to for acceptable values.
Note: In all cases, only the reason code should be sent, without the additional text description.
e.g. R24 should be sent. R24 School Fees would result in error response.
/payment-details
Endpoints not supported.
The implementation for File Payments does not support following optional/conditional endpoints in the API specification:
/international-payments
Time between Consent Authorisation and Payment Submission.
There is a maximum time limit of 90 seconds for PISPs to complete payment submission following a successful authorisation of consent request. This is due to live exchange rates being quoted for the transaction.
If the first payment submission request is received after 90 seconds this will result in the payment request being rejected.
/international-payment-consents
/international-payments
JWS Base64 Encoding
JWS must be created with Base64 encoding. Failure to use the correct encoding in the creation of the JWS would result in an error response.
Generic Countries – Payment Reason Code
Reason Description
Reason Description
United Arab Emirates– Payment Reason Code
Reason Description
Jordan – Payment Reason Code
Reason Description
Code
Reason Description
There are several important variations relating to Payment Initiation APIs that PISPs should be aware of for our File Payment endpoints. These are detailed in the table below.
/file-payment-consents
/file-payments
Functionality available for Business Customers only.
Currently only Business customers using Business Banking (O4B/BIB), or Mobile App can access file payment endpoints functionality.
Commercial Customers using Commercial Banking Online (CBO) will not be able initiate payments using File Payment endpoints.
/file-payment-consents
Multi Party Authorisation - Support for > ‘1 to sign’ payments.
Some Business customers have set up Multi Party authorisation for > ‘1 to sign’ payments using Online Payment Control (OPC).
PISPs should include OBAuthorisation1 data block in consent requests for these customers. Completion Date Time functionality is not supported.
For payments that require Multi Party authorisation, additional approvals occur in our direct channel before the payments are processed, due to which the terminal payment status may not be available.
/file-payment-consents
File Type Enumerations.
The File Type in consents request must contain one of the following values for the payment file type:
If any other value is sent in the request, then this will be rejected.
/file-payment-consents
Execution date will be determined from the file and not the consent request.
The ‘Requested Execution date’ will be ignored if it comes in the consent request payload.
The date of execution will be determined based on the payment date details provided within the file.
/file-payment-consents
SCA Exemption requests from PISPs is not supported.
PISPs cannot use SCA Support Data block to request SCA Exemption as this is not supported. If consent request is received, this will not be processed and will result in an error response.
/file-payment-consents
/file
Bulk Payment File Cut-Off Times.
Business customers 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.
/file
Payment File must be sent in csv. format.
Lloyds Banking Group will accept only two file specifications in a csv. file format:
The specification for these files including details of format, structure, field length and character sets are detailed in File Layout sections.
Any files received not in the given format for the File Type provided in the consent will be rejected.
/file-payments
Field Length, Truncations and Character Sets
Data will get truncated where csv. file fields contain more characters than supported by the schemes. Characters are restricted to specific sets; special characters are not allowed. If received, they will not be propagated to onward payment records.
Scheme standards are:
/file-payments
/payment-details
Endpoints not supported.
The implementation for File Payments does not support following optional/conditional endpoints in the API specification:
(Single character always H)
(Format yyyymmdd)
(10 character field)
(Count of credits within the file - max of 25)
(Total value of credits in the file)
(Single character always D)
(Format yyyymmdd)
(18 character field)
(15 character field with sort code-Account Number detailed)
(Single character of C must be present for each credit)
(Alpha numeric field containing beneficiaries name, maximum length 18 characters)
(numeric field must be 6 characters in length)
(numeric field must be 8 characters in length)
(18 character field)
(18 character decimal field)
(Single character always H)
(Format yyyymmdd)
(10 character field)
(Count of credits within the file - max of 25)
(Total value of credits in the file)
(Single character always D)
(18 character field)
(15 character field with sort code-Account Number detailed)
(Single character of C must be present for each credit)
(Alpha numeric field containing beneficiaries name, maximum length 18 characters)
(numeric field must be 8 characters in length)
(numeric field must be 6 characters in length)
(18 character field)
(18 character decimal field)
(For value today payments set to Y otherwise set to N)
(Format yyyymmdd, must be left blank if Payment ASAP is set to Y)
(256 character field)
There are several important variations relating to Variable Recurring Payment APIs that PISPs should be aware when using this service. These are detailed in the table below.
APIs support use cases that meet the definition of sweeping only.
Variable Recurring Payment under Sweeping Access will be allowed using VRP APIs. This restricts what values would be accepted in a consent request:
All other enumeration values provided in the specification are not accepted and would result in error response.
/domestic-vrp-consents
/domestic-vrps
APIs are not supported for Commercial Customers.
Commercial Customers using Commercial Banking Online (CBO) will not be able to set up Variable Recurring Payments.
Retail Customer using Internet Banking (IB) or Mobile App and Business Customers using Business Banking (O4B/BIB), or Mobile App will be able to set up Variable Recurring Payments.
/domestic-vrp-consents
Payment Risk Categorisation must be provided in OBRisk.
For PISP initiated payments to be processed the payment must be categorised. Payment Context Code field in OBRisk is mandatory.
Acceptable values are ‘Party to Party’ or ‘Transfer to Self’.
All other Payment Context Codes will not be accepted for Variable Recurring Payments under Sweeping Access.
/domestic-vrp-consents
Creditor Account details must be sent in consent request.
Initiation.CreditorAccount details must be populated in the consent request. Any requests not providing Creditor Account details will be rejected.
Schemes supported are:
/domestic-vrp-consents
Consents can be set up no more than 31 days in the future.
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 customer takes an action to revoke or delete consent.
/domestic-vrp-consents
Risk – Contract Present Indicator
OBRisk block will only accept the correct spelling for Contract Present Indicator field. Any requests received with the incorrect spelling will result in an error response.
/domestic-vrp-consents
/funds-confirmation
/domestic-vrps
Amount fields support up to 2 decimal places only.
Requests sent where the amount field exceeds 2 decimal places will result in error response.
Consents:
Consent funds-confirmation:
Payments:
/domestic-vrp-consents
Control Parameter Exceptions.
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 Period Type of Fortnight and Period Alignment of Calendar cannot be supported. Requests with this combination will result in an error response.
Consent requests that contain Period Alignment of Calendar will have the amount pro-rated for the first and last period.
Do not accept Maximum Individual Amount value as less than £1.00.
/funds-confirmation
Reference details must match.
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.
/payment-details
Endpoints not supported.
The implementation for Variable Recurring Payments does not support optional endpoint in the API specification:
GET /domestic-vrps/{DomesticVRPId}/payment-details
Header Error Responses
TPP attempts to use POST operation with invalid details in the header
Http Status: 400
Error Code:
UK.OBIE.Header.Invalid
Error Type:
InvalidRequestHeader
Re-attempt POST operation with a valid header
Corrective action required is provided in Error message. For example:
Message: x-fapi-customer-last-logged-time is invalid
TPP attempts to use POST operation with header details missing
Http Status: 400
Error Code:
UK.OBIE.Header.Missing
Error Type:
InvalidRequestHeader
Re-attempt POST operation with a valid header
Corrective action required is provided in Error message. For example:
Message: x-idempotency-key is missing in the request
TPP attempts to use POST operation with the same idempotency key after 24 hours
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Rules.
ResourceAlreadyExists
Error Type:
ResourceAlreadyExists
Idempotency supported for 24-hour period.
After 24 hours a new request should be created.
Signature Error Responses
TPP attempts to use POST operation with signature details missing
Http Status: 400
Error Code:
UK.OBIE.Signature.Missing
Error Type:
InvalidRequestSignature
Re-attempt POST operation with a valid signature included.
Corrective action required is provided in Error message. For example:
Message: x-jws-signature is missing in the header
TPP attempts to use POST operation with invalid details in the signature
Http Status: 400
Error Code:
UK.OBIE.Signature.Invalid
Error Type:
InvalidRequestSignature
Re-attempt POST operation with a valid signature
TPP attempts to use POST operation with a malformed signature
Http Status: 400
Error Code:
UK.OBIE.Signature.Malformed
Error Type:
InvalidRequestSignature
Re-attempt POST operation with a valid signature
Payload Error Responses
TPP attempts to set up a payment consent with mandatory field(s) missing from the request payload.
Http Status: 400
Error Code:
UK.OBIE.Field.Missing
Error Type:
InvalidRequestPayload
Create a new consent using a POST operation with a valid payload.
Take the PSU through an authentication journey.
Corrective action required is provided in Error message.
For example:
Message: Amount is missing in the request payload
Path: Data.Initiation.InstructedAmount.Amount
TPP attempts to set up a payment consent with invalid details provided in the request payload.
Http Status: 400
Error Code:
UK.OBIE.Field.Invalid
Error Type:
InvalidRequestPayload
Create a new consent using a POST operation with a valid payload.
Take the PSU through an authentication journey.
Corrective action required is provided in Error message. For example:
Message: PaymentContextCode is invalid format. Please refer to the OBIE specs.
Path: Risk.PaymentContextCode
TPP attempts to access a payment consent resource with an invalid consent id.
Http Status: 400
Error Code:
UK.OBIE.Resource.NotFound
Error Type:
InvalidRequestPayload
Reattempt with a valid Consent ID.
Else, create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to set up a payment consent for a date in the past.
Http Status: 400
Error Code:
UK.OBIE.Field.InvalidDate
Error Type:
InvalidRequestPayload
Create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to set up a payment consent with a future date that is not supported.
Http Status: 400
Error Code:
UK.OBIE.Field.InvalidDate
Error Type:
InvalidRequestPayload
Create a new consent using a POST operation.
Take the PSU through an authentication journey.
Valid future dates expected are documented in Implementation Guide.
TPP attempts to set up a payment consent with a scheme that is not supported.
Http Status: 400
Error Code:
UK.OBIE.Unsupported.Scheme
Error Type:
InvalidRequestPayload
Create a consent using a POST operation with a payment scheme that is supported.
Take the PSU through an authentication journey.
Payment journeys supported are documented in Implementation Guide.
TPP attempts to set up a payment consent with a Local Instrument that is not supported.
Http Status: 400
Error Code:
UK.OBIE.Unsupported.LocalInstrument
Error Type:
InvalidRequestPayload
Create a consent using a POST operation with a Local Instrument that is supported.
Take the PSU through an authentication journey.
Payment journeys supported are documented in Implementation Guide.
TPP attempts to set up a payment consent with a currency that is not supported.
Http Status: 400
Error Code:
UK.OBIE.Unsupported.Currency
Error Type:
InvalidRequestPayload
Create a new payment order consent using a POST operation with a currency that is supported.
Take the PSU through an authentication journey.
Currencies supported are documented in Implementation Guide.
TPP attempts to set up a payment consent with an Account Identifier that is not supported for the payment journey.
Http Status: 400
Error Code:
UK.OBIE. Unsupported.
AccountIdentifier
Error Type:
InvalidRequestPayload
Create a new payment consent using a POST operation with an Account Identifier that is supported by the payment journey.
Take the PSU through an authentication journey.
Supported Account Identifiers for payment journeys are documented in Implementation Guide.
TPP attempts to submit payment order using a Consent ID that has an invalid consent status.
Sub-scenario: The underlying consent status is not set to ‘AwaitingAuthorisation’
Http Status: 403
Error Code:
UK.OBIE.Resource.
InvalidConsentStatus
Error Type:
AuthoriseConsent
Take the PSU through an authentication journey.
TPP attempts to submit payment order using a Consent ID that has an invalid consent status.
Sub-scenario: The underlying consent status is set to ‘Rejected’ or ‘Consumed’
Http Status: 403
Error Code:
UK.OBIE.Resource.InvalidConsentStatus
Error Type:
InvalidRequestPayload
Create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to submit payment order using details that do not match the Consent resource.
Http Status: 403
Error Code:
UK.OBIE.Resource.ConsentMismatch
Error Type:
InvalidRequestPayload
Re-attempt POST operation with details that match consent resource.
Else, create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to submit payment order using a Consent ID that has expired.
Http Status: 403
Error Code:
UK.OBIE.Rules.
AfterCutOffDateTime
Error Type:
InvalidRequestPayload
Create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to submit payment order with a missing or invalid Consent ID
Http Status: 400
Error Code:
UK.OBIE.Field.Invalid
Error Type:
InvalidRequestPayload
Re-attempt POST operation with a valid Consent ID.
Else, create a new consent using a POST operation.
Take the PSU through an authentication journey.
ASPSP downstream services or server is down.
Http Status: 500
Error Code:
UK.OBIE.UnexpectedError
ErrorType:
ServerError
Retry Later.
Header Error Responses
TPP attempts to use POST operation with invalid details in the header
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Header.Invalid
Error Type:
InvalidRequestHeader
Re-attempt POST operation with a valid header
Corrective action required is provided in Error message.
For example:
Message: x-fapi-customer-last-logged-time is invalid
TPP attempts to use POST operation with header details missing
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Header.Missing
Error Type:
InvalidRequestHeader
Re-attempt POST operation with a valid header
Corrective action required is provided in Error message. For example:
Message: x-idempotency-key is missing in the request
TPP attempts to use POST operation with the same idempotency key after 24 hours
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Rules.
ResourceAlreadyExists
Error Type:
ResourceAlreadyExists
Idempotency supported for 24-hour period.
After 24 hours a new request should be created.
Signature Error Responses
TPP attempts to use POST operation with signature details missing
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Signature.Missing
Error Type:
InvalidRequestSignature
Re-attempt POST operation with a valid signature included
Corrective action required is provided in Error message. For example:
Message: x-jws-signature is missing in the header
TPP attempts to use POST operation with invalid details in the signature
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Signature.Invalid
Error Type:
InvalidRequestSignature
Re-attempt POST operation with a valid signature
TPP attempts to use POST operation with a malformed signature
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Signature.Malformed
Error Type:
InvalidRequestSignature
Re-attempt POST operation with a valid signature
Payload Error Responses
TPP attempts to set up a vrp consent with mandatory field(s) missing from the request payload.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Field.Missing
Error Type:
Invalid request parameters
Create a new consent using a POST operation with a valid payload.
Take the PSU through an authentication journey.
Corrective action required is provided in Error message. For example:
Message: Amount is missing in the request
Path: Data.ControlParameters.MaximumIndividualAmount.Amount
TPP attempts to set up a vrp consent with invalid details provided in the request payload.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Field.Invalid
Error Type:
Invalid request parameters
Create a new consent using a POST operation with a valid payload.
Take the PSU through an authentication journey.
Corrective action required is provided in Error message.
For example:
Message: PaymentContextCode is not in a valid format.
Path: Risk.PaymentContextCode
TPP attempts to set up a vrp consent with dates that are not supported.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Field.InvalidDate
Error Type:
Invalid request parameters
Create a new consent using a POST operation.
Take the PSU through an authentication journey.
Exception rules for accepted dates are documented in Implementation Guide.
TPP attempts to set up a vrp consent with a currency that is not supported.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Unsupported.Currency
Error Type:
InvalidRequestPayload
Create a new consent using a POST operation with a currency that is supported.
Take the PSU through an authentication journey.
TPP attempts to access a vrp consent resource that has been deleted or unknown.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Resource.NotFound
Error Type:
Resource not found
Reattempt with a valid Consent ID.
Else, create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to access a vrp consent resource that is expired.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Resource.
InvalidConsentStatus
Error Type:
Invalid consent status
Create a new consent using a POST operation.
Take the PSU through an authentication journey.
TPP attempts to use a vrp consent resource where the access has been revoked.
Http Status: 401 Unauthorized
Error Code:
UK.OBIE.Resource.
InvalidConsentStatus
Error Type:
Unauthorized
Take the PSU through the re-authentication journey.
TPP attempts to access a vrp payment resource that is unknown.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Resource.NotFound
Error Type:
Resource not found
Reattempt with a valid DomesticVRPID.
TPP attempts to access a vrp consent resource to make a payment that breaches control parameters set in the consent.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Rules.
FailsControlParameters
Error Type:
Invalid request parameters
Create a new request using a POST operation within the control parameters.
TPP attempts to access a vrp consent resource to do a funds-confirmation check or make a payment and the details do not match the consent.
Http Status: 400 BadRequest
Error Code:
UK.OBIE.Resource.
ConsentMismatch
Error Type:
Invalid request parameters
Create a new request using a POST operation with a valid payload that matches the consent.
ASPSP downstream services or server is down.
Http Status: 500 UnexpectedError
Error Code:
UK.OBIE.UnexpectedError
ErrorType:
UnexpectedError
Retry Later.
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 Supported scope of Aggregated Polling is accounts, fundsconfirmations, payments.
This detail should be read in conjunction with Open Banking Specifications and our API Products
AGGREGATED POLLING VARIATIONS
The Table lists down the Exceptions implemented for Aggregated Polling API :
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
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
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
Lloyds Banking Group will return up to 150 event notifications for every Aggregated Polling call made by the TPP.
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.
The LBG Aggregated Polling API returns event notifications for revoked consents only
How to register using DCR
This section applies to TPPs who are already registered with the OBIE and have a login for the OBIE directory
Certificate Signing Request (CSR) is needed to generate an SSA. Please refer to the Open Banking documentation on how to create CSRs.
After creating the CSR, retain the private keys and upload only the CSR to the Open Banking portal to generate the certificates.
Follow the OBIE Confluence page to generate the SSA
This applies to all TPPs who are not yet registered with OBIE, but are in possession of eIDAS certificates.
For those TPPs who are not registered with Open Banking, OBIE has provided APIs to do a soft onboarding, which can be used to generate an SSA which must be used during LBG dynamic client registration.
The SSA is a JSON Web Token (JWT) containing client metadata about an instance of TPP client software. The JWT is issued and signed by the Open Banking Directory.
The SSA's Lifetime / Validity period is not defined by Open Banking. ASPSPs in the Open Banking ecosystem are required to implement pragmatic time ranges in which to accept an SSA.
LBG has set the SSA validity to 24 hours for use in dynamic registration.
The APIs exposed by OBIE to register and generate an SSA are documented here
Please find the below typical steps to register with OBIE through directory services
Enroll your organization onto the Open Banking Directory through Directory Services 2.0.
Only TPPs can use this enrolment endpoint, so please set OrganizationType to tpp POST /organization/{OrganizationType}
Update the business or the technical contacts for the given organization. This is required for the LBG to create an user while creating an application. PUT /organization/{OrganizationType}/{OrganizationId} /contact/{ContactType}
Create a software statement on the directory POST /organization/{OrganizationType}/{OrganizationId} /software-statement
Update a software statement (if needed) PUT /organization/{OrganizationType}/{OrganizationId} /software-statement
Upload your eIDAS QSEAL against your organization. If OrganizationCertificateType is set to QWAC or QSEAL then the PEM file should contain a QWAC or a QSEAL certificate respectively. POST/organization/ {OrganizationType}/{OrganizationId}/certificate/ {OrganizationCertificateType}
Associate/de-associate a QSEAL certificate with the given software statement PUT/organization/ {OrganizationType}/{OrganizationId}/software-statement/ {SoftwareStatementId}/certificate/{OrganizationAssociativeCertificateType} /{CertificateOrKeyId}
Generate a Software Statement Assertion for the given SoftwareStatementID (LBG will accept SSAs generated within last 24 hours). GET/organization/{OrganizationType}/{OrganizationId} /software-statement/{SoftwareStatementId}/software- statement-assertion If you have any further questions about your enrolment request please contact Open Banking: by emailing servicedesk@openbanking.org.uk
The /register endpoint should be called with the appropriate request body and appropriate transport certificate.
Sample Client Registration request and data dictionary are mentioned below -
{
"iss": "0BiJUzrOPVHz7zDbKLu6mP",
"aud": "0015800000jf9GgAAI",
"jti": "d2040fa9-e0d6-5289-9a94-b05e84859e7e",
"response_types": [
"code id_token"
],
"redirect_uris": [
"https://developer.lloydsbanking.com"
],
"token_endpoint_auth_method": "client_secret_basic",
"grant_types": [
"authorization_code"
],
"scope": "openid accounts payments",
"software_statement": "eyJhbGciOiJQUzI1NiIsImtpZCI6I...",
"application_type": "web",
"id_token_signed_response_alg": "PS256",
"request_object_signing_alg": "PS256",
"token_endpoint_auth_signing_alg": "PS256",
"iat": 1595435113,
"exp": 1595438713
}
The audience for the request. This should be the unique identifier for the ASPSP issued by the issuer of the software statement. An ASPSP processing the software statement may validate the value of the claim and reject software statements for which the ASPSP is not the audience.
The value must be a Base62 encoded GUID.
The time at which the request expires expressed as seconds since the epoch.
An ASPSP processing the request must reject requests where the current time is greater than the time specified in the claim.
A JSON array specifying what the TPP can request to be supplied to the token endpoint as exchange for an access token
The time at which the request was issued by the TPP expressed as "seconds since the epoch
Algorithm which the TPP expects to sign the id_token, if an id_token is returned.
Identifier for the TPP.
This value must be unique for each TPP registered by the issuer of the SSA.
The value must be a Base62 encoded GUID.
For SSAs issued by the OB Directory, this must be the software_id
Registered URIs the TPP will use to interact with the ASPSP AS.
If the software statement defines a master set of redirect URIs, this must match or be a subset of the redirect URIs in the SSA.
Each of the URIs must adhere to the following rules:
The URI MUST use the https scheme
The URI MUST NOT contain a host with a value of localhost
If the request_uris metadata element is omitted from the request, the entire contents of the software_redirect_uris element in the SSA are considered to be requested by the TPP.
A JSON array specifying what the TPP can request to be returned from the ASPSP authorisation endpoint.
ASPSPs MAY reject the request if any of the requested response_types are not supported by it (as advertised at its .well-known end-points)
Defaults to code id_token if not specified.
Scopes the client is asking for (if not specified, default scopes are assigned by the AS).
This consists of a list scopes separated by spaces.
Software statement assertion issued by the issuer.
The data model for the software statements issued by the Open Banking directory are documented as part of the Directory Specification.
Algorithm which the TPP uses to authenticate with the token endpoint if using private_key_jwt or client_secret_jwt.
Must be specified if token_endpoint_auth_method is private_key_jwt or client_secret_jwt
Specifies which Token endpoint authentication method the TPP wants to use.
private_key_jwt : if requested the OP should extract the TPPs JWKS location from the software statement assertion included.
It should be noted that only tls_client_auth and private_key_jwt are FAPI compliant.
client_secret_basic
client_secret_post
tls_client_auth
client_secret_basic OR client_secret_post OR tls_client_auth
Follow the below steps to create an application –
OB Transport, OBWAC:https://secure-api.lloydsbank.com
OBWAC, QWAC:https://secure-api-eidas.lloydsbank.com/
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate (Full chain)
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Valid JWS token
Construct the request payload as the OBIE Dynamic Client Registration V3.2
If dynamic registration response completed successfully, based on the scopes sent in the request object, the appropriate API Products will be auto subscribed and auto approved and will become available for immediate consumption.
Follow the below steps to update an application if needed –
In this step you obtain an Access Token using a Client Credentials Grant Type. The access expires within 10 minutes after the generation. 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 \
For Authentication method - tls_client_auth:
curl -k -X POST \
OB Transport, OBWAC:https://secure-api.lloydsbank.com
OBWAC, QWAC:https://secure-api-eidas.lloydsbank.com/
Please refer to the Other Useful Information section for all brand specific domains
client_credentials
The grant type being requested
c1d81a9a-609a-47be-9363-8fa038b987da
Your LBG application Client ID
qJ4dE5yO6xK2oM0fQ5wR0tF4kV0uL4xR5kO6dB7dJ4iU7qI0yB
Your LBG application client_secret, its not required for tls_client_auth method
openid accounts
The scope being requested.
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.
Using the Access Token obtained in the previous step, invoke Update Client Application API.
curl –request PUT \
OB Transport, OBWAC:https://secure-api.lloydsbank.com
OBWAC, QWAC:https://secure-api-eidas.lloydsbank.com/
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Valid JWS token
Construct the request payload as the OBIE Dynamic Client Registration V3.2
Follow the below steps to update an application if needed –
In this step you obtain an Access Token using a Client Credentials Grant Type. The access expires within 10 minutes after the generation. 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 \
For Authentication method - tls_client_auth:
curl -k -X POST \
OB Transport, OBWAC:https://secure-api.lloydsbank.com
OBWAC, QWAC:https://secure-api-eidas.lloydsbank.com/
Please refer to the Other Useful Information section for all brand specific domains
client_credentials
The grant type being requested
c1d81a9a-609a-47be-9363- 8fa038b987da
Your LBG application Client ID
qJ4dE5yO6xK2oM0fQ5wR0tF 4kV0uL4xR5kO6dB7dJ4iU7qI0 yB
Your LBG application client_secret, its not required for tls_client_auth method
openid accounts
The scope being requested
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Using the Access Token obtained in the previous step, invoke View Client Application API.
curl -k -X GET\
OB Transport, OBWAC:https://secure-api.lloydsbank.com
OBWAC, QWAC:https://secure-api-eidas.lloydsbank.com/
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Follow the below steps to update an application if needed –
In this step you obtain an Access Token using a Client Credentials Grant Type. The access expires within 10 minutes after the generation. 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 \
For Authentication method - tls_client_auth:
curl -k -X POST \
OB Transport, OBWAC:https://secure-api.lloydsbank.com
OBWAC, QWAC:https://secure-api-eidas.lloydsbank.com/
Please refer to the Other Useful Information section for all brand specific domains
client_credentials
The grant type being requested
c1d81a9a-609a-47be-9363- 8fa038b987da
Your LBG application Client ID
qJ4dE5yO6xK2oM0fQ5wR0tF 4kV0uL4xR5kO6dB7dJ4iU7qI0 yB
Your LBG application client_secret, its not required for tls_client_auth method
openid accounts
The scope being requested
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
Using the Access Token obtained in the previous step, invoke Delete Client Application API.
curl –request DELETE \
OB Transport, OBWAC:https://secure-api.lloydsbank.com
OBWAC, QWAC:https://secure-api-eidas.lloydsbank.com/
Please refer to the Other Useful Information section for all brand specific domains
Combination of Root & Intermediate
Must provide in the request if the QWAC transport certs are being used. However this is optional for the OBWAC, OB Transport.
TPPs who already have anOBIE directory login will be able to use it to login to the LBG developer portal and view/amend the newly created app using dynamic registration,using the email ID of the first contact inside the SSA, which was used during dynamic registration.
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.
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 customer that in exceptional circumstances the product available at the point of application may differ from that at the point of comparison.
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’.
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:
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
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:
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.
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.
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.
Contact and support
For general queries, please email :- obresponseteam@lloydsbanking.com
We will be able to respond from 9am to 5pm Monday to Friday, except public holidays.
For technical Issues please log a ticket via the OBSD:- Sign in - Open Banking
FAQs
How should I use the Open Banking Model Bank
The OBIE has set up a ‘Developer Zone’ for TPP developers. This contains the Open Banking API specifications and Data Standards required to build your own applications. You should use these as the standards against which you should develop your applications.
The OBIE Developer Zone can found here.
Do you have a Sandbox environment for me to do my development against?
We do not currently support a Sandbox environment. The OBIE has built a Sandbox environment (Model Bank) to enable developers to prototype solutions against its specifications.
We strongly recommend that you develop and test your application using this environment as you are likely to be asked to show successful requests/responses as part of troubleshooting any issues you are facing. You can find the link to the OBIE’s Sandbox page here.
How do I register an application?
Log in with your Open Banking credentials and click on ‘Applications’ in the main menu. Then click on 'Register an application'. Once you have provided an application name, redirect url and SSA from the App that you have registered in Open Banking Directory, you will be shown your application client ID and client secret. You must supply these when you call an API that requires you to identify your application.
Make a note of your client secret because it is only displayed once.
Which OIDC flows are you supporting?
We are supporting OIDC hybrid flow with the response type code ID token and code. We have also exposed our discovery endpoint with Open Banking, which has all the necessary information for our OIDC. This information can be found on the Open Banking Directory here.
When should I come to LBG to deal with development issues and when should I go to Open Banking Ltd?
As a first port of call, you should refer to the OBIE’s Developer Zone. If you have fulfilled all of the requirements documented there, and you would like to raise an issue with us directly, please use the Issue form in the Support section of our Developer Portal.
You may well be asked for successful request / response calls that have been made against Open Banking Model Bank to assist in troubleshooting.
Do you have a set of known issues that you can share with us?
We will communicate known issues to you via email.
Lloyds Banking Group Sandbox
The Sandbox is designed to replicate the LBG production environment. It provides a safe, controlled environment for registered TPPs to develop and test APIs.
Before you start we recommend users view and familiarise themselves with the Sandbox Developer Guide on this page.
App set up
Register your Applications using Dynamic Client Registration (DCR) the details of which can be found in the below documents.
Lloyds Banking Group Sandbox Developers Guide
How to Register using DCR
This guide provides a technical overview of how to use the LBG Sandbox.
Screen Scraping Plus
This guide provides an overview of how to use our Screen Scraping Plus interface. It is intended to help TPPs carry out connectivity testing of the interface.
High level information is included about:
This guide provides a technical overview of how to use the LBG Screen Scraping Plus.