Skip to main content
The Co-operative Bank and smile
Register
Register

Our APIs

Our APIs are designed to help you securely manage your connection with us. To allow you to do this, we provide a common interface through our RESTful API.

APIs overview
General specifications

General specifications

Here are general settings and parameters for all of our APIs.

Below you can read about:

Consent
Authentication
Errors
Endpoints
Endpoint URLs
Tokens
Certificates
Parameters
Sandbox and production environments

Consent

As part of the consent process, you will be redirected to The Co-operative Bank or smile login page, where you can enter the provided PSU credentials. Based on the API request, you will then see the relevant screen after login.

The consent journey can only be tested using our online banking services, not in the mobile app.

Back to the top

Authentication

Customer authentication

Customer authentication is required on our consent page, to get the PSU’s permission to access their resources via the TPP application.

For sandbox journeys for which you need to test customer authentication, we provide credentials for this during onboarding. It will be stubbed data which will mimic the live consent journey.

When connected to a sandbox Open Banking API, you can select account types and generate access tokens to access the sandbox endpoints APIs in your own environment.

Back to the top

OAuth and TPP redirection

When a PSU completes an Open Banking journey with The Co-operative Bank or smile, they will then be redirected to the TPP.

If there is an error during the journey, the customer will be shown an error screen. When they acknowledge the error, they will then be redirected to the TPP.

There isn’t a timeout in the redirection journey. If timeout is needed, you will need to set one within your journey.

Back to the top

Mutual authentication

All APIs are secured with TLS mutual authentication, where certificates are signed by the Open Banking directory.

Back to the top

Two-factor authentication

Step-up is 2FA (two-factor authentication) and is only required in AIS journeys where sensitive data is requested, such as transactions over 90 days, standing order, direct debit or a scheduled payment.

Back to the top

Errors

You can read the specifications for error codes, error types and HTTP status codes.

Error scenarios

Below are our example scenarios, what our response will be and what you need to do.

Scenario
Bank response
TPP action
Scenario TPP attempts to access a resource for which the access has been revoked at the ASPSP. (Sub-scenario: Access token has been revoked; consent is still in Authorised state).
Bank response Http Status: 403 Error Code: UK.OBIE.Reauthenticate Error Type: Reauthenticate
TPP action Take the user through a re-authentication journey using the existing consent.
Scenario 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 by ASPSP).
Bank response Http Status: 400 Error Code: UK.OBIE.Resource.InvalidConsentStatus Error Type: ReConsent
TPP action Create a new consent using a POST operation. Take the PSU through an authentication journey.
Scenario TPP attempts to access a resource using a access token that has expired. The underlying consent has expired.
Bank response Http Status: 400 Error Code: UK.OBIE.Resource.InvalidConsentStatus Error Type: ReConsent
TPP action Create a new consent using a POST operation. Take the PSU through an authentication journey.
Scenario TPP attempts to access a resource related to an account that is closed.
Bank response Http Status: 400 Error Code: UK.OBIE.Resource.NotFound Error Type: AccountPermanentlyUnavailable
TPP action Create a new consent using a POST operation. Take the PSU through an authentication journey.
Scenario TPP attempts to access a resource related to an account that is temporarily barred from access. This includes situations where the account has a fraud marker or access has been barred for other reasons.
Bank response Http Status: 400 Error Code: UK.OBIE.Resource.NotFound Error Type: AccountTemporarilyUnavailable
TPP action TPP to check account status. Multitude of reasons for this scenario - customer should speak to the Bank, to understand if account level issue.

Back to the top

Endpoints

You can read Open Banking Limited's specifications for endpoints.

Back to the top

Endpoint URLs

Below are our endpoint URLs to use for calls and redirects. Be sure to include the URL for the appropriate environment and purpose in each call.

Our redirect endpoints need to be sent as part of the redirection URL in base64 parameters.

Environment
OAuth provider endpoint
Consent redirect endpoint
Environment Sandbox (Co-operative Bank)
OAuth provider endpoint https://sandbox-openbanking-retail.apis.co-operativebanktest.co.uk/apis/oauth/v1/oauth2/token
Consent redirect endpoint https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?data={base64EncodedParameter}
Environment Sandbox (smile)
OAuth provider endpoint https://sandbox-openbanking-retail.apis.co-operativebanktest.co.uk/apis/oauth/v1/oauth2/token
Consent redirect endpoint https://sandbox-bank.co-operativebanktest.co.uk/openbanking/smile/oauthRedirect?data={base64EncodedParameter}
Environment Production (Co-operative Bank)
OAuth provider endpoint https://openbanking-retail.apis.co-operativebank.co.uk/apis/oauth/v1/oauth2/token
Consent redirect endpoint https://bank.co-operativebank.co.uk/openbanking/coop/oauthRedirect?data={base64EncodedParameter}
Environment Production (smile)
OAuth provider endpoint https://openbanking-retail.apis.co-operativebank.co.uk/apis/oauth/v1/oauth2/token
Consent redirect endpoint https://bank.co-operativebank.co.uk/openbanking/smile/oauthRedirect?data={base64EncodedParameter}

Back to the top

Tokens

Access tokens allow you to protect resources (including APIs). They will expire after 30 minutes.

Refresh tokens are used to obtain the new access token when the current token becomes invalid or expires. They are valid for 30 days.

As part of the of the token end point call, Client ID should not be populated in the body of the request. Only Client_secret_basic is supported.

Back to the top

Certificates

The authorisation URL journey in browser uses Open Banking signed certificates. Please add your Open Banking sandbox and production root and issuer certificates to the trust store to avoid any untrusted certificate issues in the browser.

Certificate expiry

You must make sure your certificates have a minimum of 90 days until their expiry. Please add your renewed certificates to the trust store to ensure this.

Back to the top

Parameters

Below are the parameters which TPP’s need to send as part of the redirection URL in base64 encoded parameters.

Parameters
Values
Mandatory
Comments
Parameters client_id
Values Client ID shared as part of onboarding
Mandatory Yes
Comments Client ID shared with TPP as part of the onboarding process.
Parameters redirect_uri
Values redirect URI provided as part of the onboarding form
Mandatory Yes
Comments Redirect URI should match to what was provided in the onboarding form.
Please note: When generating your custom set of URL parameters, please do not % encode ‘redirect_uri’ and ‘scope’ parameters (i.e. without any special characters) before encoding your URL string into base64url.
Parameters response_type
Values code
Mandatory Yes
Comments Parameter and value must be present and must be code.
Parameters Scope
Values For CBPII -‘fundsconfirmations+offline’ For AISP -‘accounts+offline' For PISP -‘payments’
Mandatory Yes
Comments Parameter and value must be present, and values must contain either of the one present.
Please note: When generating your custom set of URL parameters, please do not % encode ‘redirect_uri’ and ‘scope’ parameters (i.e. without any special characters) before encoding your URL string into base64url.
Parameters State
Values Unique, randomly generated and non-guessable string
Mandatory Yes
Comments Parameter and value must be present.
Parameters login_hint
Values Brand of bank TPP need to interact with
Mandatory Yes
Comments Parameter and value must be present, and values must be coop or smile.
Parameters Display
Values Consent Id value generated as part of Consent API
Mandatory Yes
Comments UUID must be exactly 36 characters long, including hyphens.
Parameters code_challenge
Values Code challenge value used for PKCE
Mandatory Yes
Comments It should be unique for each Oauth flow.
Parameters code_challenge_method
Values S256
Mandatory Yes
Comments Parameter and value must be present and it matches “S256”.
Parameters stepUp
Values require
Mandatory No
Comments If parameter is present (needed for AISP Step up journey), value must match “require”.
Parameters jrn_typ
Values DP (Domestic Payment) DSP (Domestic Schedule Payment) DSO (Domestic Standing Order)
Mandatory Yes
Comments If scope is payments, then this parameter and value must be present, and it should be either DP, DSP, or DSO.
Parameters ben_name
Values Test Beneficiary
Mandatory Yes
Comments If jrn_typ is DP or DSP then this Parameter and value must be present, as sent in the consent request.
Parameters Amount
Values 1000
Mandatory Yes
Comments If jrn_typ is DP or DSP then this Parameter and value must be present, as sent in the consent request.
Parameters pymt _dt
Values 2023-09-05T10:43:07+00:00
Mandatory Yes
Comments If jrn_typ is DSP then this Parameter and value must be present, as sent in the consent request.

Back to the top

Sandbox and production environments

You can read about how to use our sandbox environment and production environment.

Back to the top