Notice of change - Open Banking Improvements: OBL v4 API - HSBC

Issued: 4th June 2025| TB-1620

What's changing?

CMA9 banks are starting migrations from OBLv3 APIs to OBLv4.

From the 13th June 2025, the first UK bank, HSBC, will start to go live with OBL v4 and deprecating OBL v3. Other CMA9 Financial Institutions are due to release their Open Banking V4 APIs through the 2nd half of 2025. During this period, there will be a difference in API responses depending on whether a given Financial Institution is available through Token.io on the Open Banking v4 OR Open Banking v3.1.11 standard.

Changes associated with OBLv4:

PIS:

• Bank raw responses are changing

• PCC codes are changing

• Improved error messaging

AIS:

• Changes to Balance Types Identifiers

All changes are available on Sandbox for testing.

Does this change affect you?

Payment Initiation Services

You may be impacted if:

• You are initiating payments with banks using the UK Open Banking API standard, and your PIS integration relies on raw bank statuses.

• You depend on specific bank error messages in your processes.

You are not impacted if:

• You do not rely on the raw bank responses.

Account Information Services

You may be impacted if:

• You are making AIS calls to banks using the UK Open Banking API standard, and you validate balance types in your AIS integration.

You are not impacted if:

• You do not validate balance types in your AIS integration.

Changes in detail

Payment Initiation Services

Standardised Payment Statuses

The bankPaymentStatus field will now return ISO 20022 standard payment status codes.

❗ Note: Token.io’s own status codes will remain unchanged.

If you have designed your implementation for raw bank statuses, you must decide how to handle the ISO 20022 version.

• V4 statuses repository and diagram

• List of how Token handles v4 statuses for APIv1

• List of how Token handles v4 statuses for APIv2:

Consistent Error Messaging

Bank error messages will be updated to match the OBL v4 specification for improved clarity and consistency.

Affected Endpoints:

• V1 API

  • providerDetails.status

    • POST/transfers

    • GET /transfers/{transfer_id}

    • GET /transfers

• V2 API

  • bankPaymentStatus

    • GET/v2/payments

    • GET/v2/payments/{paymentId}

• VRP API

  • bankVrpConsentStatus

    • POST/vrp-consents

    • GET/vrp-consents

    • GET/vrp-consents/{id}

    • ../../api/reference/Variable-Recurring-Payments#operation/GetVrpConsentDELETE/vrp-consents/{id}

  • bankVrpStatus

    • GET /vrp-consents/{id}/payments

    • POST /vrps

    • GET /vrps

    • GET /vrps/{id}

Handling of PCC codes

Token.io currently populates the PCC field with a defaulted value when no value is provided. However, with v4, we will no longer do this.

If you would like to include a PCC, you will need to provide one as part of your request. You can find more information on the new PCC in our documentation here for v1 and v2.

Affected Endpoints:

• V1 API

  • POST /token-request

• V2 API

  • POST /v2/payments

❗ Note: If you decide to not send a PCC or send an incorrect PCC, your request will not fail. Token will ignore any incorrect PCC provided, and the field will be empty. Whilst PCC is not mandatory currently or in OBL v4, it is recommended to be included as part of the request as Payment Context Code is a key transaction indicator and can be validated by the receiving bank.

Account Information Services

Changes to Balance Types identifiers

What action do I need to take?

If you are impacted, to ensure a smooth transition we strongly recommend, as soon as possible, that you:

• Speak with your implementation manager, or

• Contact us at support@token.io

When will this change apply to all impacted customers?

Currently, we only have confirmation for the first bank migration (HSBC), which is scheduled for 13th June 2025.

Where can I get further information?

For any questions, concerns, or to discuss your integration, please speak with your implementation manager or contact support@token.io.