Registering your Sandbox App
In order to get your app registered with Metro Bank to access our APIs, you need to follow the two step procedure
Step 1: Complete Application Registration Form
To register your application, the first step is to complete the Registration form.
Metro Bank is not currently accepting registrations from organisations that are not authorized for Account Information Requests (AIS) and Payment Initiation Requests (PIS) by the Financial Conduct Authority (FCA).
The Registration form requires the details of the application you are registering and some important details such as your FCA registration number.
When the form is sent to Metro Bank, we will verify your FCA registration before continuing with the registration.
When the Metro Bank verification of your FCA listing is complete, the following shall be made available:
- A Metro Bank issued TLS certificate
- On-boarding app key and secret (discover these in My Apps)
Step 2: Dynamic Client Registration
The first app created upon registration is the on-boarding app. On-boarding app key and secret can be found here. Metro Bank requires API requests are made over a connection secured with mutual TLS for both sandbox and production.
To verify the identity of Metro Bank, the certificate keyset to trust in your app can be found by consuming the API https://api.metrobankonline.co.uk/oauth/v1/.well-known/openid-configuration.
Please note, you would require mutual TLS certificate to access all of the API endpoints on both sandbox and production.
To complete the sandbox app registration process, you need to follow the steps outlined below in order.
Step 2.1: Obtain access token
Trigger a token request to production host (https://api.metrobankonline.co.uk) using the on-boarding app key and secret, client credentials grant type and a scope of manage.register.
More details about token generation can be found here.
Step 2.2 Obtain software statement assertion (SSA)
With the obtained access token supplied as a bearer token in an authorization header, post a request to the /ssa resource to the production host (https://api.metrobankonline.co.uk). More details about /ssa resource can be found here.
The SSA request must reference your FCA registration number - this should be the same as the FCA registration number supplied on the registration form.
The API response includes the newly generated SSA; a JSON Web Token (JWT). When you receive the SSA, we recommend that you verify the signature using the Metro Bank public key.
Step 2.3 Register sandbox app via API
The JWT payload for /register must be signed using your public/private key pair issued after completing the registration form. The public key is the Metro Bank certificate that was issued to you.
The SSA expires after 60 minutes. If the registration is not complete before the SSA expires then a new SSA must be requested.
Below is an example of a decoded JWT used for registration:
"software_id": "OpenBanking TPP Software Unique ID",
In the JWT header:
Important points to note about the above example:
- alg: We support RS256 and ES256
- kid: X.509 Certificate SHA-1 Thumbprint. The thumprint of the signing certificate - this is the certificate issued to you by Metro Bank. Please ensure the thumbprint is used for the kid to enable registration to complete.
In the JWT body:
- iss: This is a mandatory field. This should be your client ID for your on-boarding app
- iat: This is a mandatory field. Time of issuance of request. (rfc7519)
- exp: This is a mandatory field. Request Expiration time. (rfc7519)
- aud: This is a mandatory field. This should be the fully qualified /register endpoint.
- grant_types: Optional, however if passed checks for both; "authorization_code" "client_credentials"
- response_types: This is a mandatory field. Check for "code id_token" or "id_token code"
- token_endpoint_auth_method: This is a mandatory field. Should be set to "private_key_jwt"
- software_id: This is a mandatory field. The value must match the software_id in the SSA
- scope: This is a optional field. If passed the scope must include "openid". Additional scopes may be requested here - these should be appropriate to the role that your registration is requesting (e.g. AISPs should submit "openid accounts")
- software_statement: This is mandatory. The SSA is included in the software_statement attribute. The SSA JWT must not be altered from the original token that you received from /ssa.
A successful registration generates a response similar to the example below:
"client_name": "OpenBanking TPP Software TPP",
"software_id": "OpenBanking TPP Software",
"scope": "openid accounts",
We are working on bringing the new API portfolio of Open Banking 3.1.1 AISP and PISP to life and would be happy to let you use the service on sandbox on request basis. If you like to make use of our brand new Open Banking AISP and PISP APIs, please get in touch with Metro Bank support team via our Contact Us page after getting your sandbox app on-boarded.
When Metro Bank receives your SSA and verifies your signature, the on-boarding app is removed from the developer portal and a sandbox app appears. With access to the sandbox APIs you can test your application with the Metro Bank APIs before moving to the live APIs.
If you are already using our v1 APIs, we would encourage you to try out our new products in the sandbox. The products can be added to your app by contacting the Metro Bank support team via our Contact Us page.