developer.lloydsbanking.com

1 Introduction

1.1 OVERVIEW

The Lloyds Banking Group (LBG) Sandbox is designed to replicate the functionality present in the LBG production environment. It is provided for the Third Party Providers (TPP) to be able to develop and test their APIs in a safe, controlled environment , without impacting the live environments.

This Sandbox enables TPPs to complete end-to-end testing of their products and allows them to use the same codebase when they move to the production environment.

The Sandbox, where possible and where appropriate, mirrors all the functionality of the production interface relating to Account Information Services (used by AISPs), Payment Initiation Services, including VRPs (used by PISPs), Confirmation of Funds Services (used by CBPIIs) , and Event Notifications delivered through Aggregated polling. There are, however, some key differences and this guide seeks to capture them.

This guide should be read in conjunction with the Technical Implementation Guide and the guide on How to Register using DCR , which are issued as part of the production environment.

1.2 KEY DIFFERENCES BETWEEN THE SANDBOX AND THE PRODUCTION INTERFACE

The functionality works like the production interface for all the happy paths and error scenarios. The exceptions to this are:

1.2.1 BRANDING

• Functionally, the Sandbox is agnostic to the different brands of the Lloyds Banking Group (LBG) like Lloyds, Halifax, Bank of Scotland and MBNA.

• The Sandbox UI is themed on a single common LBG brand unlike the production interface that are themed for the individual brands.

• The Sandbox provides a set of eight inbuilt PSUs as a representative sample of the differences in the data across brands and channels.

  • Lloyds - Retail, Retail Business Banking (RBB), Commercial

  • Halifax – Retail

  • BoS - Retail, Retail Business Banking (RBB), Commercial

  • MBNA – Retail

1.2.2 MOCK DATA

• Mock data includes the PSUs along with their accounts, transactions, balances, beneficiaries, direct debits, standing orders, scheduled payments and product.

• There is no relationship between the mock data and any real-world user details or credentials.

1.2.3 TPP ONBOARDING

• The TPPs must be registered to the Open Banking Sandbox directory (see Onboarding below), whereas, to access the production interface, TPPs must be registered with the Open Banking Production directory.

• App registration can only be done using Dynamic Client Registration (DCR).

• Only one app registration per software statement is possible.

• LBG Sandbox only supports PS256 signed SSAs without any backward compatibility for RS256.

1.2.4 PSU CONSENT JOURNEY

• TPPs are not required to be an LBG customer to use the Sandbox. Pre-defined PSU accounts have been established for TPP’s use as listed here .

  Journey Type	User Name	Password
  BoS Business	bab001	Password123
  BoS Commercial	bac001	Password123
  BoS Retail	bar001	Password123
  Halifax Retail	har001	Password123
  Lloyds Business	llb001	Password123
  Lloyds Commercial	llc001	Password123
  lloyds Retail	llr001	Password123
  MBNA Retail	mbr001	Password123

   

• The Sandbox only supports Primary authentication.

• The Sandbox does not support:

  • Step Up authentication

  • Two Factor authentication

  • App to App consent

  • Decoupled flows

1.2.5 PISP API - PAYMENT EXECUTION

• Though the Sandbox supports the PISP APIs, the payment transactions will not affect the actual account balance of a PSU. Hence the account balance will not change over time, irrespective of the number of times the TPP invokes the payment APIs.

1.2.6 UNSUPPORTED FEATURES

• Customer re-authorisation

• Fraud checks

• Daily limit checks

• Developer portal is not available in Sandbox

1.2.7 STRESS TESTING

• There is sufficient data capacity and performance to facilitate effective and realistic TPP testing. However, the Sandbox does not provide the capacity to replicate production volumes and hence cannot be used for stress/load testing.

1.2.8 API URL VERSIONING

• The API URLs in the sandbox test facility will use Major.Minor.Patch versioning (e.g. 3.1.10), as opposed to 3.1 in Production. This is to allow the sandbox test facility to potentially support multiple patch versions and allow TPPs to test implementations against differences in functionality between minor versions (JWS between 3.1.2 and 3.1.10 for example)

• The recommendation is to use the RS Discovery endpoint to obtain endpoint URLs (see section 2.4)

2. COMPLETING AN END-TO-END API JOURNEY

This section explains how to on-board onto the Lloyds Banking Group Sandbox, and how to complete an end-to-end API journey. In this instance, the example used is an Account Information API journey.

2.1 ON-BOARDING ONTO THE SANDBOX

2.1.1 FIRST TIME USERS

• To use the Sandbox, TPPs must be registered with the Open Banking Sandbox Directory

• TPPs should get familiarized with the following documents:

  • Open Banking Directory Specification v1.5

  • Open Banking Security Profile v1.1.2

  • Open Banking Read/Write Data API Specification

  • Dynamic Client Registration Specification v3.2

2.1.2 PRE-REQUISITES FOR REGISTERING APPLICATIONS IN THE SANDBOX

• Certificate Signing Request (CSR) and private keys for transport and signing.

  • TPPs should use their own key generation tool and management policies and must create the CSRs and the private keys, each for transport and signing.

• Software Statement Assertion (SSA) to identify the TPP’s Open Banking application.

  • Navigate to the organization summary page on the Open Banking Sandbox Directory

  • Click ‘Add new Software Statement’ under ‘Software Statements’ tab.

  • Complete ‘Add new Software Statement form’

  • Click ‘Add new Organisation Certificate’ under ‘Certificates’ tab and upload the OB Seal and OB Wac CSRs and keep note of the KID

  • Check if the new Software Statement creation has been completed.

  • Generate the Software Statement Assertion (SSA) and copy to clipboard for future use in on-boarding.

• Digital certificates(PEM files) required for transport and signing.

  • Under the “Software Statements” tab, once you select the Software statement that was created, there is a section “Keys/certificates” where you can find all the associated certificates. Once you locate your certificates using KID, by using the three dot menu besides it, you get an option saying “Get PEM” which gives you the link to download the PEM file.

     

  • You can also go to the “Certificates” tab directly and locate your KID and use the “Get PEM” button besides it to get the PEM files.

     

  • Alternatively, you can decrypt the SSA using tools like https://jwt.io/ and get the “software_jwks_endpoint”. Visit this “software_jwks_endpoint” link, locate the releavent entry using the KID and download the PEM files for transport and signing.

     

2.2 LIST OF APIS AVAILABLE FOR TESTING

The following list of APIs are in scope for testing

AISP

CBPII

PISP

International Scheduled Payment and International Standing Order APIs are not available.

VRP

Event Notifications

2.3 PSU CONSENT USING HYBRID FLOW

• As part of PSU consent, TPP will be redirected to the LBG login page.

• TPP will provide the PSU credentials in the login page. These credentials are available in the PSU page as specified under section 2.1.4

• Based on the API request (AISP, PISP and CBPII) TPP will see the relevant screen post Login page.

• AIS Consent Page.

  • Available accounts for the PSU are listed with an option to choose specific accounts for consent.

  • The page will have additional details on the information to be shared with the TPPs

  • Options are available to either agree by clicking the ‘Continue’ button or to cancel the request.

• PIS Consent Page

  • Payment details page will be shown with the amount to be paid to the merchant/PISP provider along with the bank details

  • An account can be selected from where the amount can be debited

  • Option is available to either agree to pay by clicking the ‘Continue’ button or to cancel the request

• VRP Consent Page

  • The payment permission details page will be shown with the control parameters along with the beneficiary bank details

  • An account can be selected from where the payments will be made from on recurring basis

  • Option is available to either agree to set up the payment permission by clicking the ‘Continue’ button or to cancel the request

• CoF Consent Page

  • The account number sent by TPP for the confirmation of funds will be displayed on the screen.

  • The page will have expiry date for the consent to be shared with the TPPs (The expiry date displayed will depend on the customer choice or will display as No Expiry date or long lived consent.)

  • The note related to confirmation of funds is displayed.

  • Options are available to either agree by clicking the ‘Continue’ button or to cancel the request.

2.4 OTHER USEFUL INFORMATION

1. LBG Sandbox APIs are behind the following domains – these are over MA-TLS – hence the TPPs should present their OB-signed client cert against these domains to validate if the SSL handshake is working as expected (e.g. by using an appropriate openSSL command, in chrome etc.)

   https://matls.as.aspsp.sandbox.lloydsbanking.com/open-banking/mtlsTest
   https://matls.as.aspsp.sandbox.lloydsbanking.com:443/open-banking/mtlsTest
   https://matls.rs.aspsp.sandbox.lloydsbanking.com/open-banking/mtlsTest
   https://matls.rs.aspsp.sandbox.lloydsbanking.com:443/open-banking/mtlsTest

2. Discovery Endpoints

   1. API discovery

      https://rs.aspsp.sandbox.lloydsbanking.com/open-banking/discovery

   2. Well-known endpoint

      https://as.aspsp.sandbox.lloydsbanking.com/oauth2/.well-known/openid-configuration

3. We support OIDC Hybrid Flow.

4. All APIs are secured with TLS Mutual Authentication where Certs are signed by Open Banking CA.

5. The DCR call should be made to the registration endpoint described in the AS well-known endpoint (above)

   Registration endpoint https://matls.as.aspsp.sandbox.lloydsbanking.com/open-banking/register/

   This document should be read in conjunction with the Production guide: How to Register using DCR

6. The authorise url journey in the browser uses Open Banking signed certificates. Hence the Open Banking Sandbox root and issuer certificates should be added to the trust store to avoid untrusted certificate issues in the browser. The Open Banking sandbox root and issuer certificates are available for download from the Open Banking confluence page

2.5 TESTING THE ACCOUNT INFORMATION APIS

2.5.1 SETUP CLIENT CREDENTIALS TOKEN

 

In this step, the AISP obtains an Access Token using the “client_credentials” grant type. When an Access Token expires, you will need to re-request for another Access Token.

• curl -X POST \

  --key <TRANSPORT_PRIVATE_KEY_FILE> \

  --cert <TRANSPORT_PEM_FILE> \

  https://matls.as.aspsp.sandbox.lloydsbanking.com/oauth2/access_token

  -H 'Content-Type: application/x-www-form-urlencoded' \

  -H 'cache-control: no-cache' \

  -d 'grant_type=client_credentials&scope=accounts&client_id=<CLIENT_ID>'

Data

Note down the “access_token” in the response for further use.

2.5.2 INVOKE THE ACCOUNT REQUEST API

Using the Access Token obtained in the previous step, invoke the Accounts Consent API with the desired permissions in the request body.

curl -X POST \

--key <TRANSPORT_PRIVATE_KEY_FILE> \

--cert <TRANSPORT_PEM_FILE> \

https://matls.rs.aspsp.sandbox.lloydsbanking.com/open-banking/v3.1.6/aisp/account-access-consents \ <Value of ‘URL’ from the API Discovery Endpoint >

-H 'Accept: application/json' \

-H 'Authorization: Bearer <ACCESS_TOKEN_FROM_THE_PREVIOUS_STEP>' \

-H 'Content-Type: application/json' \

-H 'cache-control: no-cache' \

-H 'x-fapi-financial-id: <Value of ‘FinancialId’ from the API Discovery Endpoint >' \

-d '{

"Data": { "Permissions": [

                       LBG Sandbox User Guide            

"ReadAccountsDetail", "ReadBalances"

]

},

"Risk": {}

}'

Headers

Body

Please refer here for a full list of the allowed permissions.

Note down the AccountRequestID or ConsentId in the response data. This is required in the next step to be used in the claims body.

2.5.3 AUTHORISE CONSENT – HYBRID FLOW

In this step, create the authorization request (using a signed JWT request containing the AccountRequestId or ConsentId as a claim) for the customer to consent to the account consent request.

Using a web browser, invoke the URL below to emulate the customer giving consent after changing the parameterized values as required.

https://as.aspsp.sandbox.lloydsbanking.com:443/oauth2/authorize?response...<CLIENT_ID_FROM_THE_FIRST_STEP>&state=<STATE>& nonce=<NONCE>&scope=openid%20accounts&redirect_uri=<REDIRECT_URI_USED_DURIN G_ONBOARDING>&request=<SIGNED_CLAIMS_IN_BASE64>

URL Parameters

A sample claims body syntax that may be used for signing (Replace <xxxx> values with actuals):

                
                {
                  "sub": "urn-example-bank",
                  "exp": <EXPIRY_IN_SECONDS_SINCE_EPOCH>,
                  "iat": <ISSUED_AT_IN_SECONDS_SINCE_EPOCH>,
                  "iss": "<CLIENT_ID_FROM_THE_FIRST_STEP>",
                  "aud": "<Value of the issuer in the> well-known endpoint>", 
                  "response_type": "code id_token",
                  "client_id": "<CLIENT_ID_FROM_THE_FIRST_STEP>",
                  "redirect_uri": "<REDIRECT_URI_USED_DURING_ONBOARDING>",
                  "scope": "openid accounts",
                  "state": "<STATE>",
                  "nonce": "<NONCE>",
                  "claims": {
                    "userinfo": {
                      "openbanking_intent_id": {
                        "value": "<ACCOUNT_REQ_ID_OR_CONSENT_ID>",
                        "essential": true
                      }
                    },
                    "id_token": {
                      "openbanking_intent_id": {
                        "value": "<ACCOUNT_REQ_ID_OR_CONSENT_ID>",
                          "essential": true
                      },
                      "acr": {
                        "value": "urn:openbanking:psd2:sca",
                        "essential": true
                      }
                    }
                  }
                }      
              
            

Follow the UI flow using the credentials of any of the static PSU user accounts supplied with the Sandbox as described under section 2.1.4

If there were untrusted certificate issues when the authorize url was launched in the browser, ensure instructions under section 2.4(6) is completed.

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

2.5.4 GET THE ACCESS TOKEN REQUIRED TO ACCESS THE ACCOUNT

Following the OAuth2.0 protocol, exchange the access code for the access token required in the next step, using the “authorization_code” grant type.

Once the below call is made, you will get access token along with refresh token. This refresh token can be in turn used for procuring new access token when it expires.

curl -X POST \

--key <TRANSPORT_PRIVATE_KEY_FILE> \

--cert <TRANSPORT_PEM_FILE> \

https://matls.as.aspsp.sandbox.lloydsbanking.com/oauth2/access_token

-H 'Content-Type: application/x-www-form-urlencoded' \

-H 'cache-control: no-cache' \

-d 'grant_type=authorization_code&code=<CODE_FROM_THE_PREVIOUS_STEP>&redirect_ uri=<REDIRECT_URI_USED_DURING_ONBOARDING>&client_id=<CLIENT_ID>'

Body

Take note of the “access_token” in the response data for further use.

2.5.5 GET ACCOUNTS

You can use the Access Token to retrieve data using the AISP APIs.

The following example is from the Account API v3.1.10 Specification.

Where the initial Access Token expires, you must obtain a new Access Token using refresh token.

curl -X GET \

--key <TRANSPORT_PRIVATE_KEY_FILE> \

--cert <TRANSPORT_PEM_FILE> \

https://matls.rs.aspsp.sandbox.lloydsbanking.com/open- banking/v3.1.6/aisp/accounts ><Value of ‘URL’ from the API Discovery Endpoint>

-H 'Accept: application/json' \

-H 'Authorization: Bearer <ACCESS_TOKEN_FROM_THE_PREVIOUS_STEP>' \

-H 'Content-Type: application/json' \

-H 'cache-control: no-cache' \

-H 'x-fapi-financial-id: <Value of ‘FinancialId’ from the API Discovery Endpoint >'\

-H 'x-idempotency-key: <IDEMPOTENCY_KEY>'

Headers