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

PIS (Payment Initiation Service) APIs

Providing a Payment Initiation Service (PIS) means providing payment instruments and initiating payments directly from a customer’s bank account. They must explicitly give consent for the PISP to connect to the bank system and debit the payment account.

PIS documentation
PIS specifications
PIS endpoints and errors

PIS endpoints and errors

Here are our endpoints and errors which are specific to PIS (Payment Initiation Service) APIs.

Below you can read about:

Domain URLs
Context path
Discovery endpoints
Error codes
OAuth2.0 redirection error mapping

Domain URLs

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

Our domains are over MTLS. You should present your Open Banking signed certificate against these domains to validate the SSL handshake and check it is working as expected.

Environment
Domain
Environment Sandbox (Co-operative Bank)
Domain https://sandbox-openbanking-retail.apis.co-operativebanktest.co.uk/
Environment Sandbox (smile)
Domain https://sandbox-openbanking-retail.apis.co-operativebanktest.co.uk/
Environment Production (Co-operative Bank)
Domain https://openbanking-retail.apis.co-operativebank.co.uk/
Environment Production (smile)
Domain https://openbanking-retail.apis.co-operativebank.co.uk/

Back to the top

Context path

Following a call to the Domain URL you can access the context path before the discovery endpoints.

PISP API CONTEXT PATH - /apis/retail/open-banking/v3.1/pisp/

Back to the top

Discovery endpoints

We provide all the PIS API endpoints which are in the OBL specifications:

PISP
Endpoints
PISP Domestic Payments
Endpoints GET /domestic-payment-consents/{ConsentId}
PISP Domestic Payments
Endpoints POST /domestic-payment-consents
PISP Domestic Payments
Endpoints GET /domestic-payment-consents/{ConsentId}/funds-confirmation
PISP Domestic Payments
Endpoints GET /domestic-payments/{DomesticPaymentId}
PISP Domestic Payments
Endpoints POST /domestic-payments
PISP Domestic Schedule Payment
Endpoints POST /domestic-scheduled-payment-consents
PISP Domestic Schedule Payment
Endpoints GET /domestic-scheduled-payment-consents/{ConsentId}
PISP Domestic Schedule Payment
Endpoints POST /domestic-scheduled-payments
PISP Domestic Schedule Payment
Endpoints GET /domestic-scheduled-payments/{DomesticScheduledPaymentId}
PISP Domestic Standing order
Endpoints POST /domestic-standing-order-consents
PISP Domestic Standing order
Endpoints GET /domestic-standing-order-consents/{ConsentId}
PISP Domestic Standing order
Endpoints POST /domestic-standing-orders
PISP Domestic Standing order
Endpoints GET /domestic-standing-orders/{DomesticStandingOrderId}

Back to the top

Error codes

Below are our error codes and descriptions specific to PIS APIs, and what to do to correct them.

Scenario
Error response
TPP action
Scenario Amount - must be between £0.01 and £19,999.99
Error response Status code: 400

Error code: UK.OBIE.Field.Invalid

Description: Invalid Amount in InstructedAmount
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Consent not found
Error response Status code: 400

Error code: UK.OBIE.Resource.NotFound

Description: Consent not found
TPP action TPP needs to verify the consent status then retry after making necessary changes.
Scenario Consent not Authorised
Error response Status code: 400

Error code: UK.OBIE.Resource.InvalidConsentStatus

Description: Consent not Authorised
TPP action TPP needs to verify the consent status then retry after making necessary changes.
Scenario {payment-order-consent} and {payment-order} resource mismatch
Error response Status code: 400

Error code: UK.OBIE.Resource.ConsentMismatch

Description: Payment details don't match
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Payment date is today's date
Error response Status code: 400

Error code: UK.OBIE.Field.InvalidDate

Description: Today's date is not allowed for RequestedExecutionDateTime
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Payment date is beyond 2 years from today's date
Error response Status code: 400

Error code: UK.OBIE.Field.InvalidDate

Description: Date beyond 2 years is not allowed for RequestedExecutionDateTime
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Payment date is in the past
Error response Status code: 400

Error code: UK.OBIE.Field.InvalidDate

Description: Past dates are not allowed for RequestedExecutionDateTime
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.
Scenario Payment date is a Weekend
Error response Status code: 400

Error code: UK.OBIE.Field.InvalidDate

Description: Weekends are not allowed for RequestedExecutionDateTime
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Payment date is a Bank holiday
Error response Status code: 400

Error code: UK.OBIE.Field.InvalidDate

Description: Bank holidays are not allowed for RequestedExecutionDateTime
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario DomesticScheduledPaymentId in Request doesn't match with the consent
Error response Status code: 400

Error code: UK.OBIE.Resource.NotFound

Description: DomesticScheduledPaymentId not found
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Unexpected Error
Error response Status code: 500

Error code: UK.OBIE.UnexpectedError

Description: Temporary System error, unknown temporary error
TPP action It might be intermediate system error, TPP needs to send the request again.
Scenario Date format is not according to the OBIE spec
Error response Status code: 400

Error code: UK.OBIE.Field.InvalidDate

Description: /Data/RequestedExecutionDateTime [2013-09-29 18:46:19] is not a valid date-time. Expected [yyyy-MM-dd'T'HH:mm:ssZ, yyyy-MM-dd'T'HH:mm:ss.[0-9]{1,9}Z,
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Mandatory field is missing according to the OB Spec
Error response Status code: 400

Error code: UK.OBIE.Field.Missing

Description: {Field} required key {Field} not found
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Scheme name is not valid enum for debitor Account
Error response Status code: 400

Error code: UK.OBIE.Unsupported.Scheme

Description: /Data/Initiation/DebtorAccount/SchemeName UK.OBIE.PAN is not a valid enum value
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Scheme name is not valid enum for Creditor Account
Error response Status code: 400

Error code: UK.OBIE.Unsupported.Scheme

Description: /Data/Initiation/DebtorAccount/SchemeName UK.OBIE.PAN is not a valid enum value
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Identification length is not correct
Error response Status code: 400

Error code: UK.OBIE.Unsupported.AccountIdentifier

Description: /Data/DebtorAccount/Identification expected maxLength: 14, actual: 18
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario Invalid field
Error response Status code: 400

Error code: UK.OBIE.Resource.InvalidFormat

Description: /Data/Initiation/InstructedAmount/Amount string [1fd03] does not match pattern ^\\d{1,13}$|^\\d{1,13}\\.\\d{1,5}$
TPP action Review the payload ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario JWS Signature Invalid
Error response Status code: 400

Error code: UK.OBIE.Signature.Invalid

Description: The signature header x-jws-signature was parsed and has a valid JOSE header that complies with the specification. However, the signature itself could not be verified.
TPP action Review the signature header detail ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario JWS Signature Malformed
Error response Status code: 400

Error code: UK.OBIE.Signature.Malformed

Description: The x-jws-signature in the request header was malformed and could not be parsed as a valid JWS.
TPP action Review the signature header detail ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario JWS Signature Missing
Error response Status code: 400

Error code: UK.OBIE.Signature.Missing

Description: The API request expected an x-jws-signature in the header, but it was missing.
TPP action Review the signature header detail ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario JWS Signature Missing Claim
Error response Status code: 400

Error code: UK.OBIE.Signature.MissingClaim

Description: The JOSE header in the x-jws-signature has one or more mandatory claim(s) that are not specified. The name of the missing claim(s) should be specified in the path field of the error response.
TPP action Review the signature header detail ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.
Scenario JWS Signature Invalid Claim
Error response Status code: 400

Error code: UK.OBIE.Signature.InvalidClaim

Description: The JOSE header in the x-jws-signature has one or more claims with an invalid value.
TPP action Review the signature header detail ensuring that the data is in line with the guidance given within API documentation.

Retry after making necessary changes.

Back to the top

OAuth2.0 redirection error mapping

These errors will cover any unhappy path system or user actions that result in the journey being exited without giving consent. In some of these scenario’s we will pass an error message back to the TPP. The error message may be different depending on the scenario and what will prompt which relevant error message needs to be used; and will relate to the scenario.

Error
Error description
Redirection URL
Summary
Error Account not found
Error description User account details supplied do not meet criteria
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Account+not+found&error_description=User+account+details+supplied+do+not+meet+criteria
Summary Unable to identify account supplied by TPP as either not eligible / not valid / closed
Error Authentication declined
Error description User declined authentication
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Authentication+declined&error_description=User+declined+authentication
Summary Customer (PSU) has aborted consent journey before authentication complete at Bank (ASPSP) by selecting 'Cancel and return' or session has timed out and automatically redirected back to TPP
Error Authentication failed
Error description User locked out of Online Banking
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Authentication+failed&error_description=User+locked+out+of+Online+Banking
Summary Customer (PSU) Online credentials are locked so require resetting by bank (ASPSP) support team and are unable to authenticate for consent
Error Authentication failed
Error description User needs to reset credentials
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Authentication+failed&error_description=User+needs+to+reset+credentials
Summary Customer (PSU) Online credentials require reseting by bank (ASPSP) support team and are unable to authenticate for consent
Error Consent declined
Error description User declined consent
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Consent+declined&error_description=User+declined+consent
Summary Customer (PSU) has aborted consent journey after reviewing consent details supplied by selecting 'Cancel and return' or session has timed out and automatically redirected back to TPP
Error No eligible accounts
Error description User has no eligible accounts
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=No+eligible+accounts&error_description=User+has+no+eligible+accounts
Summary Customer (PSU) has no accounts eligible for Open Banking
Error Payment Limit Exceeded
Error description User has exceeded their payment limit
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Payment+Limit+Exceeded&error_description=User+has+exceeded+their+payment+limit
Summary Customer (PSU) has reached their payment limit and is unable to proceed with the payment at this current time
Error Savings Account - Standing Order
Error description Consent declined as only Savings Account available for Standing Order
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Savings+Account+-+Standing+Order&error_description=Consent+declined+as+only+Savings+Account+available+for+Standing+Order
Summary Customer (PSU) only has a Savings Account eligible for Open Banking and unable to provide consent as Standing Orders not permitted with this product type
Error Savings Account - Standing Order
Error description Consent declined - Savings Account NOT permitted for Standing Order
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Savings+Account+-+Standing+Order&error_description=Consent+declined+-+Savings+Account+NOT+permitted+for+Standing+Order
Summary Account supplied by TPP is a Savings Account and unable to provide consent as Standing Orders not permitted with this product type
Error Savings Account with Reference
Error description Consent declined as payment with reference from Savings Account
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Savings+Account+with+Reference&error_description=Consent+declined+as+payment+with+reference+from+Savings+Account
Summary Customer (PSU) unable to make payment from a Savings Account with a payment reference
Error Temporary System Error
Error description Unknown Temporary Error
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=Temporary+System+Error&error_description=Unknown+Temporary+Error+
Summary Bank (ASPSP) has had an internal system error and is unable to provide a response to consent request, please try again later
Error User action caused error
Error description User refreshed the page during authentication
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=User+action+caused+error&error_description=User+refresh+page+during+authentication
Summary Customer (PSU) has aborted consent journey before authentication complete at Bank (ASPSP) by selecting 'Browser Refresh' and has automatically redirected back to TPP
Error User action caused error
Error description User refreshed the page during consent
Redirection URL https://sandbox-bank.co-operativebanktest.co.uk/openbanking/coop/oauthRedirect?error=User+action+caused+error&error_description=User+refresh+page+during+consent
Summary Customer (PSU) has aborted consent journey after reviewing consent details supplied by selecting 'Browser Refresh' and has automatically redirected back to TPP
Error Cancelled payment
Error description User cancelled payment
Redirection URL https://www.example.com?error=Cancelled+payment&error_description=User+cancelled+payment
Summary Customer (PSU) has aborted consent journey before proceeding to authentication at Bank (ASPSP) by selecting 'Cancel and return'.
Error Not mobile registered user
Error description Mobile - user not registered
Redirection URL https://www.example.com?error=Not+mobile+registered+user&error_description=Mobile+-+user+not+registered
Summary The Customer (PSU) has the Bank (ASPSP) app on their device, but their device is not registered for Mobile Banking. Customer has decided to return to the TPP instead of going on to Online Banking to provide consent. Customer (PSU) needs to register their device before starting the journey again or instead continue to Online Banking to provide consent.
Error Temporary system error
Error description App currently unavailable – user exited journey
Redirection URL https://www.example.com?error=Temporary+system+error&error_description=App+currently+unavailable+–+user+exited+journey
Summary The Bank (ASPSP) App is currently unavailable. Customer has decided to return to the TPP instead of going on to Online Banking to provide consent. Customer (PSU) can try again to see if it the App is available or instead continue to Online Banking to provide consent.
Error Obsolete app version
Error description App update required
Redirection URL https://www.example.com?error=Obsolete+app+version&error_description=App+update+required
Summary Customer (PSU) needs to do a mandatory update of their version of the Bank (ASPSP) mobile app and customer has decided to return to the TPP instead of going on to Online Banking to provide consent. Customer (PSU) needs to update their Bank (ASPSP) app before starting the journey again or instead continue to Online Banking to provide consent.
Error User action - exit
Error description User exited journey
Redirection URL https://www.example.com?error=User+action+-+exit&error_description=User+exited+journey
Summary Customer (PSU) has aborted consent journey before authentication complete at Bank (ASPSP) by selecting 'Cancel and return' on page which may indicate they need to reset their mobile app log in credentials.
Error Authentication failed
Error description User unable to authenticate
Redirection URL https://www.example.com?error=Authentication+failed&error_description=User+unable+to+authenticate
Summary Customer (PSU) has failed authentication and is temporarily frozen-out of Mobile Banking. The customer will need to wait until the countdown has expired before they can try authentication again.
Error request_unauthorized
Error description The request could not be authorized. The login request has expired. Please try again.
Redirection URL https://www.example.com?error=request_unauthorized&error_description=The+request+could+not+be+authorized.The+login+request+has+expired.+Please+try+again.
Summary The consent token has expired. Please allow the customer to start the journey again with a new consent token.
Error request_unauthorized
Error description The request could not be authorized. The consent request has expired. Please try again.
Redirection URL https://www.example.com?error=request_unauthorized&error_description=The+request+could+not+be+authorized.+The+consent+request+has+expired.+Please+try+again.
Summary The consent token has expired. Please allow the customer to start the journey again with a new consent token.
Error request_forbidden
Error description The+request+is+not+allowed.+No+CSRF+value+available+in+the+session+cookie
Redirection URL https://www.example.com?error=request_forbidden&error_description=The+request+is+not+allowed.+No+CSRF+value+available+in+the+session+cookie
Summary NA

Back to the top