PUBLIC PUBLIC PUBLIC PUBLIC
HSBC Open Banking
TPP Implementation Guide (V3.1.11)
Last Updated: 28-08-2024
PUBLIC PUBLIC PUBLIC PUBLIC
Table of Contents
1. INTRODUCTION......................................................................................................................................................... 8
2. KEY CHANGES AND ANNOUNCEMENTS..................................................................................................................... 9
3. SUMMARY OF HSBC API FUNCTIONALITY PER CHANNEL ........................................................................................ 10
4. USEFUL INFORMATION ........................................................................................................................................... 12
4.1. CUSTOMER UI JOURNEYS ................................................................................................................................................ 12
4.2. TPP REGISTRATION ....................................................................................................................................................... 12
4.2.1. Software Statement .............................................................................................................................................. 12
4.2.2. Onward Provisioning – TPP / Agent name display options ................................................................................... 14
4.2.3. Implemented Endpoints ........................................................................................................................................ 15
4.2.4. Supported token_endpoint_auth_method ............................................................................................................ 16
4.2.5. MTLS when token_endpoint_auth_method is tls_client_auth .............................................................................. 17
4.3. AUTHENTICATION JOURNEY ............................................................................................................................................. 18
4.4. CONSENT EXPIRY DATE ................................................................................................................................................... 18
4.5. AUTHORISATION CODE IN OAUTH AUTHORISATION FRAMEWORK ........................................................................................... 19
4.6. MESSAGE SIGNING - X-JWS-SIGNATURE ............................................................................................................................. 20
4.7. CONSENT OBJECT STATUSES ............................................................................................................................................ 20
4.8. OBWAC / EIDAS CERTIFICATES ...................................................................................................................................... 20
4.8.1. Test Certificate ...................................................................................................................................................... 20
4.8.2. Certificate Requirements ....................................................................................................................................... 21
4.8.3. Certificate Refresh / Replacement ......................................................................................................................... 21
4.9. BUSINESS BANKING ENTITLEMENTS ................................................................................................................................... 21
4.10. UK IP ADDRESS WHITELISTING AND GRATING USER ACCESS FOR HSBCNET USERS ...................................................................... 22
5. ACCOUNTS AND TRANSACTIONS SUMMARY .......................................................................................................... 24
5.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 24
5.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 24
5.1.2. HSBC Business Banking .......................................................................................................................................... 25
5.1.3. HSBC Kinetic .......................................................................................................................................................... 26
5.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 26
5.2. IN-SCOPE PRODUCTS ...................................................................................................................................................... 27
5.2.1. HSBC Personal ....................................................................................................................................................... 27
5.2.2. first direct .............................................................................................................................................................. 27
5.2.3. M&S Bank .............................................................................................................................................................. 28
5.2.4. HSBC Business ....................................................................................................................................................... 28
5.2.5. HSBC Kinetic .......................................................................................................................................................... 28
5.2.6. HSBC Corporate UK (HSBCnet UK) * ...................................................................................................................... 29
5.2.7. HSBC Innovation Banking (HSBCnet UK) ............................................................................................................... 29
6. ACCOUNT REQUESTS API ........................................................................................................................................ 30
6.1. OVERVIEW ................................................................................................................................................................... 30
6.2. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 30
6.2.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 30
6.2.2. HSBC Business ....................................................................................................................................................... 31
6.2.3. HSBC Kinetic .......................................................................................................................................................... 31
6.2.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 31
6.3. KEY INFORMATION ABOUT ACCOUNT IDENTIFICATION........................................................................................................... 32
6.4. CREDIT CARD PRODUCT BEHAVIOUR (REPLACEMENT CARDS) ................................................................................................. 32
6.5. CURRENT ACCOUNT SWITCHING RESPONSES (HSBC RETAIL AND BUSINESS BRANDS) ................................................................. 33
7. BALANCES API ......................................................................................................................................................... 34
7.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 34
7.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 34
3
PUBLIC
7.1.2. HSBC Business ....................................................................................................................................................... 34
7.1.3. HSBC Kinetic .......................................................................................................................................................... 34
7.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 34
7.2. BALANCE TYPE .............................................................................................................................................................. 35
7.2.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 35
7.2.2. HSBC Business ....................................................................................................................................................... 35
7.2.3. HSBC Kinetic .......................................................................................................................................................... 36
7.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 36
8. TRANSACTIONS API ................................................................................................................................................. 37
8.1. OVERVIEW ................................................................................................................................................................... 37
8.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 37
8.1.2. HSBC Business ....................................................................................................................................................... 37
8.1.3. HSBC Kinetic .......................................................................................................................................................... 37
8.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 38
8.2. TRANSACTION HISTORY .................................................................................................................................................. 38
8.3. LIFESPAN OF NEXT LINKS ................................................................................................................................................. 39
8.4. TRUNCATION ................................................................................................................................................................ 39
8.5. TRANSACTION ORDERING ................................................................................................................................................ 41
8.6. PAGINATION ................................................................................................................................................................. 41
8.7. DATE FILTERING ............................................................................................................................................................ 41
8.8. TIME FILTERING ............................................................................................................................................................ 41
8.9. BOOKED AND PENDING TRANSACTIONS ............................................................................................................................. 41
8.10. RESPONSE FIELDS .......................................................................................................................................................... 42
8.10.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 42
8.10.2. HSBC Business ....................................................................................................................................................... 43
8.10.3. HSBC Kinetic .......................................................................................................................................................... 44
8.10.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 45
8.11. MUTABILITY FLAG ......................................................................................................................................................... 45
8.12. RESTRICTED DATA FOR LASTING CONSENTS (ALSO KNOWN AS ARTICLE 10A ACCESS) .................................................................. 46
9. BENEFICIARIES API .................................................................................................................................................. 47
9.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 47
9.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 47
9.1.2. HSBC Business ....................................................................................................................................................... 47
9.1.3. HSBC Kinetic .......................................................................................................................................................... 47
9.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 48
10. DIRECT DEBITS API .................................................................................................................................................. 50
10.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 50
10.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 50
10.1.2. HSBC Business ....................................................................................................................................................... 50
10.1.3. HSBC Kinetic .......................................................................................................................................................... 50
10.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 50
11. STANDING ORDERS API ........................................................................................................................................... 51
11.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 51
11.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 51
11.1.2. HSBC Business ....................................................................................................................................................... 51
11.1.3. HSBC Kinetic .......................................................................................................................................................... 51
11.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet (Not Implemented) .............................................. 52
12. PRODUCTS API ........................................................................................................................................................ 52
12.1. OVERVIEW ................................................................................................................................................................... 52
12.2. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 53
12.2.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 53
12.2.2. HSBC Business ....................................................................................................................................................... 53
4
PUBLIC
12.2.3. HSBC Kinetic .......................................................................................................................................................... 53
12.2.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 53
13. PARTY API ............................................................................................................................................................... 54
13.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 54
13.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 54
13.1.2. HSBC Business ....................................................................................................................................................... 54
13.1.3. HSBC Kinetic .......................................................................................................................................................... 54
13.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 54
13.2. PERMISSIONS ................................................................................................................................................................ 55
13.3. DATA .......................................................................................................................................................................... 55
14. SCHEDULED PAYMENTS API .................................................................................................................................... 56
14.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 56
14.1.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 56
14.1.2. HSBC Business ....................................................................................................................................................... 56
14.1.3. HSBC Kinetic .......................................................................................................................................................... 56
14.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 56
15. OFFERS API ............................................................................................................................................................. 57
15.1. OVERVIEW ................................................................................................................................................................... 57
15.2. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 57
15.2.1. HSBC Personal, M&S Bank ..................................................................................................................................... 57
15.3. OFFERS TYPE ................................................................................................................................................................ 57
15.4. RESPONSE FIELDS........................................................................................................................................................... 58
15.4.1. HSBC Personal, M&S Bank ..................................................................................................................................... 58
16. STATEMENTS API .................................................................................................................................................... 59
16.1. OVERVIEW ................................................................................................................................................................... 59
16.2. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 60
16.2.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 60
16.2.2. HSBC Business ....................................................................................................................................................... 60
16.2.3. HSBC Kinetic .......................................................................................................................................................... 60
16.3. RESPONSE FIELDS........................................................................................................................................................... 61
16.3.1. HSBC Personal, first direct, M&S Bank .................................................................................................................. 61
16.3.2. HSBC Business, Kinetic ........................................................................................................................................... 62
17. PAYMENT INITIATION SUMMARY ........................................................................................................................... 65
17.1. PAYMENT LIMITS ........................................................................................................................................................... 65
17.1.1. HSBC Personal ....................................................................................................................................................... 65
17.1.2. first direct .............................................................................................................................................................. 65
17.1.3. HSBC Business ....................................................................................................................................................... 65
17.1.4. HSBC Kinetic .......................................................................................................................................................... 65
17.1.5. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 65
17.2. HSBC BUSINESS – KEY PIS INFORMATION ......................................................................................................................... 66
17.3. FASTER PAYMENTS ........................................................................................................................................................ 66
17.4. PAYMENTS REFUNDS ...................................................................................................................................................... 66
17.5. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 67
17.5.1. HSBC Personal, first direct ..................................................................................................................................... 67
17.5.2. HSBC Business ....................................................................................................................................................... 68
17.5.3. HSBC Kinetic .......................................................................................................................................................... 69
17.5.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 70
18. DOMESTIC PAYMENTS ............................................................................................................................................ 71
18.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 71
18.1.1. HSBC Personal, first direct ..................................................................................................................................... 71
18.1.2. HSBC Business ....................................................................................................................................................... 71
5
PUBLIC
18.1.3. HSBC Kinetic .......................................................................................................................................................... 71
18.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 72
18.2. REQUEST FIELDS ............................................................................................................................................................ 72
18.2.1. HSBC Personal, first direct ..................................................................................................................................... 72
18.2.2. HSBC Business ....................................................................................................................................................... 72
18.2.3. HSBC Kinetic .......................................................................................................................................................... 73
18.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 74
18.3. FEES FOR CHAPS PAYMENTS .......................................................................................................................................... 75
18.4. CUT-OFF TIME FOR CHAPS PAYMENTS ............................................................................................................................. 75
18.5. PAYMENT STATUS ......................................................................................................................................................... 76
19. DOMESTIC SCHEDULED PAYMENTS ......................................................................................................................... 77
19.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 77
19.1.1. HSBC Personal, first direct ..................................................................................................................................... 77
19.1.2. HSBC Business ....................................................................................................................................................... 77
19.1.3. HSBC Kinetic .......................................................................................................................................................... 77
19.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 78
19.2. REQUEST FIELDS ............................................................................................................................................................ 78
19.2.1. HSBC Personal, first direct ..................................................................................................................................... 78
19.2.2. HSBC Business ....................................................................................................................................................... 78
19.2.3. HSBC Kinetic .......................................................................................................................................................... 79
19.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 79
19.3. PAYMENT STATUS ......................................................................................................................................................... 81
20. DOMESTIC STANDING ORDERS ............................................................................................................................... 82
20.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 82
20.1.1. HSBC Personal, first direct ..................................................................................................................................... 82
20.1.2. HSBC Business ....................................................................................................................................................... 82
20.1.3. HSBC Kinetic .......................................................................................................................................................... 82
20.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 82
20.2. REQUEST FIELDS ............................................................................................................................................................ 83
20.2.1. HSBC Personal, Business, Kinetic ........................................................................................................................... 83
20.2.2. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ............................................................................. 84
20.3. PERMITTED FREQUENCY VALUES ...................................................................................................................................... 85
20.3.1. HSBC Personal, Business and Kinetic ..................................................................................................................... 85
20.4. PAYMENT STATUS ......................................................................................................................................................... 87
21. INTERNATIONAL PAYMENTS ................................................................................................................................... 88
21.1. IMPLEMENTED ENDPOINTS .............................................................................................................................................. 88
21.1.1. HSBC Personal, first direct ..................................................................................................................................... 88
21.1.2. HSBC Business ....................................................................................................................................................... 88
21.1.3. HSBC Kinetic .......................................................................................................................................................... 88
21.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 89
21.2. REQUEST FIELDS ............................................................................................................................................................ 89
21.2.1. HSBC Personal, first direct ..................................................................................................................................... 89
21.2.2. HSBC Business ....................................................................................................................................................... 90
21.2.3. HSBC Kinetic .......................................................................................................................................................... 92
21.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 93
21.3. CREDITORAGENT AND CREDITORACCOUNT ......................................................................................................................... 95
21.3.1. HSBC Personal, first direct ..................................................................................................................................... 95
21.3.2. HSBC Business ....................................................................................................................................................... 96
21.3.3. HSBC Kinetic .......................................................................................................................................................... 96
21.4. CREDITOR/POSTALADDRESS ............................................................................................................................................ 97
21.4.1. HSBC Business, HSBC Kinetic ................................................................................................................................. 98
21.5. CREDITORAGENT/POSTALADDRESS................................................................................................................................... 98
21.5.1. HSBC Personal, first direct ..................................................................................................................................... 98
21.6. PAYMENT COUNTRY – CREDITORAGENT/POSTALADDRESS/COUNTRY ..................................................................................... 98
6
PUBLIC
21.6.1. HSBC Personal, first direct ..................................................................................................................................... 99
21.6.2. HSBC Business, HSBC Kinetic ................................................................................................................................. 99
21.6.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet .............................................................................. 99
21.7. OPTIONAL FIELDS ........................................................................................................................................................... 99
21.7.1. HSBC Personal, first direct ..................................................................................................................................... 99
21.7.2. HSBC Business, HSBC Kinetic ............................................................................................................................... 100
21.7.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 102
21.8. FX RATE VALIDITY ....................................................................................................................................................... 105
21.8.1. HSBC Personal, first direct ................................................................................................................................... 105
21.8.2. HSBC Business, HSBC Kinetic ............................................................................................................................... 105
21.8.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 105
21.9. PAYMENT STATUS ....................................................................................................................................................... 106
21.9.1. HSBC Personal, first direct ................................................................................................................................... 106
21.9.2. HSBC Business, HSBC Kinetic ............................................................................................................................... 106
21.9.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 106
22. INTERNATIONAL SCHEDULED PAYMENTS ............................................................................................................. 108
22.1. IMPLEMENTED ENDPOINTS ............................................................................................................................................ 108
22.1.1. HSBC Personal, first direct ................................................................................................................................... 108
22.1.2. HSBC Business ..................................................................................................................................................... 108
22.1.3. HSBC Kinetic (Not Implemented) ......................................................................................................................... 108
22.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 109
22.2. REQUEST FIELDS .......................................................................................................................................................... 109
22.2.1. HSBC Personal, first direct ................................................................................................................................... 109
22.2.2. HSBC Business ..................................................................................................................................................... 110
22.2.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 111
22.3. PAYMENT STATUS ....................................................................................................................................................... 113
22.3.1. HSBC Personal, first direct ................................................................................................................................... 113
22.3.2. HSBC Business ..................................................................................................................................................... 113
22.3.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 114
23. INTERNATIONAL STANDING ORDERS .................................................................................................................... 115
23.1. IMPLEMENTED ENDPOINTS ............................................................................................................................................ 115
23.1.1. HSBC Personal, first direct ................................................................................................................................... 115
23.1.2. HSBC Business (Not Implemented) ...................................................................................................................... 115
23.1.3. HSBC Kinetic (Not Implemented) ......................................................................................................................... 115
23.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ........................................................................... 116
23.2. REQUEST FIELDS .......................................................................................................................................................... 116
23.2.1. HSBC Personal, first direct ................................................................................................................................... 116
23.2.2. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 118
23.3. PERMITTED FREQUENCY VALUES .................................................................................................................................... 120
23.4. PAYMENT STATUS ....................................................................................................................................................... 120
24. FILE PAYMENTS ..................................................................................................................................................... 121
24.1. IMPLEMENTED ENDPOINTS ............................................................................................................................................ 121
24.1.1. HSBC Personal (Not implemented) ...................................................................................................................... 121
24.1.2. HSBC Business ..................................................................................................................................................... 121
24.1.3. HSBC Kinetic (Not Implemented) ......................................................................................................................... 121
24.1.4. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ........................................................................... 122
24.2. REQUEST FIELDS AND EXAMPLE FILE................................................................................................................................ 122
24.2.1. HSBC Business ..................................................................................................................................................... 122
24.2.2. HSBC Corporate UK and HSBC Innovation Banking – HSBCnet ........................................................................... 127
24.3. PAYMENT STATUS ....................................................................................................................................................... 130
24.3.1. HSBC Business ..................................................................................................................................................... 130
24.3.2. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet UK ....................................................................... 131
25. MAJOR BENEFICIARIES .......................................................................................................................................... 132
7
PUBLIC
25.1. PAYING A MAJOR BENEFICIARY ...................................................................................................................................... 132
25.1.1. HSBC Personal, first direct ................................................................................................................................... 132
25.1.2. HSBC Business ..................................................................................................................................................... 132
25.1.3. HSBC Kinetic ........................................................................................................................................................ 132
26. MULTI-AUTHORISATION ....................................................................................................................................... 133
26.1. IMPLEMENTED ENDPOINTS ............................................................................................................................................ 133
26.1.1. HSBC Business ..................................................................................................................................................... 133
26.1.2. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 133
26.2. TPP AUTHORISATION TYPE ........................................................................................................................................... 134
26.3. HSBC BUSINESS MULTI-AUTHORISATION ........................................................................................................................ 134
26.4. MULTI-AUTHORISATION OBJECT STATUS ......................................................................................................................... 135
26.5. REFUND ACCOUNT DETAILS FOR MULTI-AUTHORISATION PAYMENTS .................................................................................... 135
27. CONFIRMATION OF FUNDS SUMMARY ................................................................................................................. 137
27.1. IMPLEMENTED ENDPOINTS ............................................................................................................................................ 137
27.1.1. HSBC Personal, first direct, M&S Bank ................................................................................................................ 137
27.1.2. HSBC Business ..................................................................................................................................................... 137
27.1.3. HSBC Kinetic ........................................................................................................................................................ 138
27.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet ............................................................................ 138
27.2. REQUEST FIELDS .......................................................................................................................................................... 138
28. VARIABLE RECURRING PAYMENTS - SWEEPING .................................................................................................... 139
28.1. KEY INFORMATION....................................................................................................................................................... 139
28.2. PAYMENT REFUNDS ..................................................................................................................................................... 139
28.3. IMPLEMENTED ENDPOINTS ............................................................................................................................................ 139
28.3.1. HSBC Personal, first direct ................................................................................................................................... 139
28.3.2. HSBC Business ..................................................................................................................................................... 140
28.3.3. HSBC Kinetic ........................................................................................................................................................ 140
28.4. REQUEST FIELDS .......................................................................................................................................................... 141
28.4.1. HSBC Personal, first direct ................................................................................................................................... 141
28.4.2. HSBC Business ..................................................................................................................................................... 142
28.5. PAYMENT LIMITS ......................................................................................................................................................... 143
28.5.1. HSBC Personal, first direct ................................................................................................................................... 143
28.5.2. HSBC Business ..................................................................................................................................................... 143
28.5.3. HSBC Kinetic ........................................................................................................................................................ 143
28.6. FEES FOR CHAPS PAYMENTS ........................................................................................................................................ 143
28.7. CUT-OFF TIME FOR CHAPS PAYMENTS ........................................................................................................................... 143
28.8. PAYMENT STATUS ....................................................................................................................................................... 144
28.9. ADDITIONAL NOTES ..................................................................................................................................................... 145
29. TWO-WAY NOTICE OF REVOCATION ..................................................................................................................... 145
29.1. IMPLEMENTED ENDPOINTS ............................................................................................................................................ 146
29.1.1. HSBC Personal, first direct, M&S Bank ................................................................................................................ 146
29.1.2. HSBC Business ..................................................................................................................................................... 146
29.1.3. HSBC Kinetic ........................................................................................................................................................ 146
29.2. REQUEST FIELDS .......................................................................................................................................................... 146
30. ERROR CODES ....................................................................................................................................................... 148
30.1. COMMON, AUTHORISATION AND TOKEN ERRORS .............................................................................................................. 148
30.2. ACCOUNT INFORMATION SERVICE (AIS) ERRORS ............................................................................................................... 148
30.3. PAYMENT INITIATION SERVICE (PIS) ERRORS .................................................................................................................... 148
30.4. CARD BASED PAYMENT INSTRUMENT ISSUER (CBPII) ERRORS ............................................................................................. 149
30.5. EVENT NOTIFICATION ERRORS ....................................................................................................................................... 149
31. DISCLAIMER .......................................................................................................................................................... 150
8
PUBLIC
1. Introduction
HSBC has made all reasonable efforts to apply the OBIE standard to its UK Open Banking implementation. Therefore, developers
should start with OBIE published documentation.
This Implementation Guide covers items HSBC wishes to provide further detail on. We welcome feedback to make this as useful as
possible. Our implementation guide is designed to assist you, as a TPP with registration, on-boarding and completion of both AIS and
PIS standard journeys.
If you have any suggestions or feedback on our Implementation Guide, then please reach out to our Third Party Provider Engagement
team by clicking
here
or completing our Online Form.
You can access the HSBC Transparency Calendars via the following links:
Banking Area
Page Link
HSBC Personal
https://openbanking.atlassian.net/wiki/spaces/AD/pages/108266712/Implementation+Guide+
HSBC+Personal
HSBC Business
https://openbanking.atlassian.net/wiki/spaces/AD/pages/1059489023/Implementation+Guide+
HSBC+Business
Marks and Spencer
https://openbanking.atlassian.net/wiki/spaces/AD/pages/914326499/Implementation+Guide+
Marks+Spencers
first direct
https://openbanking.atlassian.net/wiki/spaces/AD/pages/915047304/Implementation+Guide+fi
rst+direct
HSBC Kinetic
https://openbanking.atlassian.net/wiki/spaces/AD/pages/1387201093/Implementation+Guide+
HSBC+-+Kinetic
HSBC Corporate UK (HSBCnet UK)
https://openbanking.atlassian.net/wiki/spaces/AD/pages/1171816486/HSBC+-
+Corporate+Banking
HSBC Innovation Banking
(HSBCnet UK)
https://openbanking.atlassian.net/wiki/spaces/AD/pages/2707390465/HSBC+Innovation+Bank
ing
9
PUBLIC
2. Key Changes and Announcements
Key Changes:
➢ Discover the newly added information about payment limits in the Payment Initiation Summary (section 17)
➢ Errata corrections
Announcements:
➢ The decommissioning of the MCIs for HSBC Personal, first direct, M&S Bank, HSBC Business, HSBC Kinetic, and HSBCnet
UK, which was communicated on 31st May 2024, will be implemented on or after 31st August 2024.
10
PUBLIC
3. Summary of HSBC API Functionality Per
Channel
HSBC continues to make improvements and introduce new functionality to its Open Banking API channel. Below summarises the
current per-brand position of live API functionality, and what can be expected to be live-to-market later in 2024.
Product
Feature
Date (browser)
Date
(app-2-app)
Current Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (SIP, FDP, SO)
Live
Live
International Payments
Live
Live
Complex Payments (BACS, CHAPS)
n/a
n/a
Savings Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (Domestic Payments Only)
Live
Live
Credit Cards*
AIS
Live
Live
Confirmation of Funds
Live
Live
Global Money
AIS
Live
Live
PIS (Domestic Payments Only)
Live
Live
Confirmation of Funds
Live
Live
Multi-Currency
Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (International Payments Only)
Live
Live
Current Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (SIP, FDP, SO)
Live
Live
International Payments
Live
Live
Complex Payments (BACS, CHAPS)
n/a
n/a
Savings Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (Domestic Payments Only)
Live
Live
Credit Cards*
AIS
Live
Live
Confirmation of Funds
Live
Live
Business
Current Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (SIP, FDP, SO)
Live
Live
International Payments
Live
Live
Complex Payments (BACS, CHAPS)
Live
Live
Savings Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (Internal Transfers Only)
Live
Live
Deposit Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS
Live
Live
Credit Cards*
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS
n/a
n/a
Multi-Currency
Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (International Payments Only)
Live
Live
Global Wallet
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (International Payments Only)
Live
Live
Credit Cards*
AIS
Live
Live
Confirmation of Funds
Live
Live
11
PUBLIC
* For Credit Card APIs, please note the following:
- The maximum transaction history accessible with SCA is 18 months billed and 1 month unbilled; for statements it is 18 months billed only (Transactions of up
to 72 months will be shared through Credit Cards Statements endpoint in 2024)
cal license will not be covered.
Business
Current Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (SIP, FDP, SO)
Live
Live
International Payments
n/a
n/a
Complex Payments (BACS, CHAPS)
n/a
n/a
Credit Cards*
AIS
Live
Live
Confirmation of Funds
Live
Live
Business
Current Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (Domestic payments)
Live
Live
Complex Payments (BACS, CHAPS)
Live
Live
Multi-Currency
Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (International Payments Only)
Live
Live
Credit Cards
AIS
Live
Live
Confirmation of Funds
Live
Live
Global Wallet
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (International Payments Only)
Live
Live
Business
Current Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (Domestic payments)
Live
Live
Complex Payments (BACS, CHAPS)
Live
Live
Multi-Currency
Accounts
AIS
Live
Live
Confirmation of Funds
Live
Live
PIS (International Payments Only)
Live
Live
Credit Cards
AIS
Live
Live
Confirmation of Funds
Live
Live
Credit Cards**
AIS
tbc
tbc
Confirmation of Funds
tbc
tbc
12
PUBLIC
4. Useful Information
4.1. Customer UI Journeys
For AISP journeys, our solution can determine whether the PSU is about to authorise a new consent or refresh an existing one. As a
result, only the core information is displayed during the AISP refresh flow user journey.
PISP flows are enriched with similar features, to enable us to spot a payment request to a trusted beneficiary, or to apply SCA
exemptions if applicable.
The above is supported by a responsive design which provides a smooth user experience on desktop and a mobile browser.
For further technical information please visit the Open Banking Security Profile
4.2. TPP Registration
For TPP registration HSBC supports 3.2 of Dynamic Client Registration in line with specifications - Dynamic Client Registration v3.2.
Please note in version 3.2 of Dynamic Client Registration content-type should be application/jose.
-known
configuration.
Please note the JWT expiry parameter (exp) in the request body should be set to a maximum of 30 mins.
4.2.1. Software Statement
TPPs need to check the address of HSBC's registration endpoint using our well-known endpoints:
Banking Area
Well-known Endpoint
HSBC Personal
https://api.ob.hsbc.co.uk/.well-known/openid-configuration
HSBC Business
https://api.ob.business.hsbc.co.uk/.well-known/openid-configuration
Marks and Spencer
https://api.ob.mandsbank.com/.well-known/openid-configuration
first direct
https://api.ob.firstdirect.com/.well-known/openid-configuration
HSBC Kinetic
https://api.ob.hsbckinetic.co.uk/.well-known/openid-configuration
HSBC Corporate UK (HSBCnet UK)
https://api.ob.hsbcnet.com/.well-known/openid-configuration
HSBC Innovation Banking
(HSBCnet UK)
https://api.ob.hsbcnet.com/.well-known/openid-configuration
TPPs need to register with their National Competent Authority (NCA) and to obtain the appropriate certificate based on jurisdiction.
13
PUBLIC
Software Statements:
For holders of OBWAC / OBSEAL certificates, TPPs will be issued with a software statement from the OBIE Directory - see here for
more information.
TPPs using eIDAS certificates can generate a self-signed software statement (self-signed SSA) - see here for further information. A
complete list of all fields required for a self-signed SSA is provided below in the tables:
Metadata
Description
Optional or
Mandatory
Source Specification
`software_id`
Unique Identifier for TPP Client
Software
M
[RFC7591]
^[0-9a-zA-Z]{1,22}$
`iss`
SSA Issuer
M
[RFC7519]
^[0-9a-zA-Z]{1,22}$
Identifier for the TPP. This value must be
unique for each TPP registered by the issuer
of the SSA
For SSAs issued by the OB Directory, this
must be the software_id
`iat`
Time SSA issued
M
[RFC7519]
`jti`
JWT ID
M
[RFC7519]
^[0-9A-F]{8}-[0-9A-F]{4}-4[0-9A-F]{3}-
[89AB][0-9A-F]{3}-[0-9A-F]{12}$`
Max-36 length
`software_client_id`
The Client ID Registered at OB used to
access OB resources
M
Base62 GUID (22 chars) Max 36
`software_client_description`
Human-readable detailed description of
the client
O
Max256Text
`software_client_name`
Human-readable Software Name
O
Max40Text
`software_client_uri`
The website or resource root uri
O
Max256Text
`software_version`
The version number of the software
should a TPP choose to register and /
or maintain it
O
decimal
`software_environment`
Requested additional field to avoid
certificate check
O
Max256Text
`software_jwks_endpoint`
Contains all active signing and network
certs for the software
M
Max256Text
`software_jwks_revoked_endpoint`
Contains all revoked signing and
network certs for the software
O
Max256Text
`software_logo_uri`
Link to the TPP logo. Note, ASPSPs are
not obliged to display images hosted
by third parties
O
Max256Text
`software_mode`
ASPSP Requested additional field to
indicate that this software is `Test` or
`Live` the default is `Live`. Impact and
support for `Test` software is up to the
ASPSP.
O
Max40Text
`software_on_behalf_of_org`
A reference to fourth party
organsiation resource on the OB
Directory if the registering TPP is
acting on behalf of another.
O
Max40Text
`software_policy_uri`
A link to the software's policy page
O
Max256Text
`software_redirect_uris`
Registered client callback endpoints as
registered with Open Banking
M
A string array of Max256Text items
Pattern applied
(?:\\[([0-9a-fA-F:]+)\\]|(?:(?:[a-zA-Z0-9%-
._~!$&'()*+,;=]+(?::[a-zA-Z0-9%-
._~!$&'()*+,;=]*)?@)?([\\p{Alnum}\\-
\\.]*)))(?::(\\d*))?(.*)?
`software_roles`
A multi value list of PSD2 roles that
this software is authorized to perform.
M
A string array of Max256Text items
`software_tos_uri`
A link to the software's terms of
service page
O
Max256Text
`organisation_competent_authority_claims`
Authorisations granted to the
organsiation by an NCA
CodeList {`AISP`, `PISP`, `CBPII`, `ASPSP`}
14
PUBLIC
`org_status`
Included to cater for voluntary
withdrawal from OB scenarios
`Active`, `Revoked`, or `Withdrawn`
`org_id`
The Unique TPP or ASPSP ID held by
OpenBanking.
M
HSBC Implementation support Max 18 char
`org_name`
Legal Entity Identifier or other known
organisation name
O
Max140Text
`org_contacts`
JSON array of objects containing a
triplet of name, email, and phone
number
O
Each item Max256Text
`org_jwks_endpoint`
Contains all active signing and network
certs for the organisation
O
Max256Text
`org_jwks_revoked_endpoint`
Contains all revoked signing and
network certs for the organisation
O
Max256Text
`typ`
MUST be set to `JWT`
M
`alg`
MUST be set to `PS256`
M
`kid`
The kid will be kept the same as the
`x5t` parameter. (X.509 Certificate
SHA-1 Thumbprint) of the signing
certificate.
M
Software statements are checked by the ASPSP on TPP registration / request for access.
Digital Signatures:
QSEALs or OBSEALS will also be required by TPPs to enable a digital signature feature. Use of a digital signature to sign payloads is
mandatory.
4.2.2. Onward Provisioning TPP / Agent name display options
Please note that TPPs must ensure that they have registered using the appropriate fields so that the correct information is displayed
to customers.
Options
Display
Display Rule
Client
Name
Org
Name
On
Behalf
Of'
Name
What
Will
display
When <org name> & <Client Name> are
available & both are same & <Software on
behalf name> not available
All (single name and key
point)
Use <Client Name> as TPP name
ABC
Company
Ltd
ABC
Company
Ltd
N/A
ABC
Company
Ltd
When <org name> & <Client Name> are
available & both are different & <Software
on behalf name> not available
All (single name and key
point)
Use <Client Name> as TPP name
ABC Trades
ABC
Company
Ltd
N/A
ABC Trades
When <org name> & <Client Name> are
available & both are same & <Software on
behalf name> is available & is same as well
All (single name and key
point)
Use <Client Name> as TPP name
ABC
Company
Ltd
ABC
Company
Ltd
ABC
Company
Ltd
ABC
Company
Ltd
When <org name> & <Client Name> are
available & both are different & <Software
on behalf name> is available & is same as
the <org name>
Both names to be displayed
*
<Agent> on behalf of <TPP>
Use <SoftwareOnBehalf> as Agent
Use <Client Name> as TPP
ABC Trades
ABC
Company
Ltd
ABC
Company
Ltd
ABC
Company
Ltd on behalf
of ABC
Trades
When <org name> & <Client Name> are
available & both are different & <Software
on behalf name> is available & is same as
the <Client name>
All (single name and key
point)
Use <Client Name> as TPP name
ABC Trades
ABC
Company
Ltd
ABC Trades
ABC Trades
When <org name> & <Client Name> are
available & both are same & <Software on
behalf name> is available & is different
from both
Both names to be displayed*
<Agent> on behalf of <TPP>
Use <SoftwareOnBehalf> as Agent
Use <Client Name> as TPP
ABC
Company
Ltd
ABC
Company
Ltd
OBO Ltd
OBO Ltd on
behalf of
ABC
Company
Ltd
15
PUBLIC
When <org name> & <Client Name> are
available & both are different & <Software
on behalf name> is available & is different
from both
Both names to be displayed
*
<Agent> on behalf of <TPP>
Use <SoftwareOnBehalf> as Agent
Use <Client Name> as TPP
ABC Trades
ABC
Company
Ltd
OBO Ltd
OBO Ltd on
behalf of
ABC Trades
* Both names will always be displayed at the consent set-up step, however, for simplicity, single name may be displayed in some
non-key steps within the journey.
4.2.3. Implemented Endpoints
Endpoints
Mandatory
Implemented
POST /register
Conditional
Y
GET /register/{ClientId}
Optional
Y
PUT /register/{ClientId}
Optional
Y
DELETE /register/{ClientId}
Optional
N
POST /register:
➢ TPPs must include a complete ClientName and OrganisationName during the registration process.
➢ Both names should be:
▪ Semantically and syntactically correct
▪ Adhere to data integrity rules including correct capitalisation, consistent use of abbreviations and spacing
➢ If an agent is acting on behalf of the TPP, the agent name (Trading name of the Agent Company) must be provided within
➢
Banking Area
Well-known Endpoint
HSBC Personal
https://api.ob.hsbc.co.uk
HSBC Business
https://api.ob.business.hsbc.co.uk
Marks and Spencer
https://api.ob.mandsbank.com
first direct
https://api.ob.firstdirect.com
HSBC Kinetic
https://api.ob.hsbckinetic.co.uk
HSBC Corporate UK (HSBCnet UK)
https://api.ob.hsbcnet.com
HSBC Innovation Banking
(HSBCnet UK)
https://api.ob.hsbcnet.com
16
PUBLIC
GET /register:
➢ r
should have Bearer token as access_token retrieved from /token with client_credentials grant_type.
PUT /register:
➢ TPPs may use this endpoint to update existing registration details. Relevant checks will be performed to ensure the updates
are valid/allowed. An error message will be returned in instance of failures.
➢ The request should contain the response received from the GET /register
should have Bearer token as access_token retrieved from /token with client_credentials grant_type.
➢ It is important to note that the entire GET /register payload is expected in PUT /register payload as well. Any value that does
not need an update during registration is still expected to be sent in the request.
➢ Also with respect to scope update, it is expected that all scope for which registration is required is sent. For example, even if
TPP is registered with accounts scope, and expects payments to be updated as part of PUT /register, the value in the
payload expected is accounts payments. This scope in PUT /register will be considered as a complete replace instead of
append to the existing value.
The following fields can be updated via PUT/register:
Fields which can be updated using PUT/register
exp
response_types
grant_types
scope
iat
software_id
id_token_signed_response_alg
software_statement
iss
request_object_signing_alg
jti
token_endpoint_auth_method
redirect_uris
token_endpoint_auth_signing_alg
4.2.4. Supported token_endpoint_auth_method
Method
Supported
private_key_jwt
Y
client_secret_jwt
N
client_secret_basic
N
client_secret_post
N
tls_client_auth
Y
17
PUBLIC
Clarification on Scope parameter
Endpoint
Journey
Scopes
Notes
/register
PIS
"scope": "openid payments"
A Journey needs to be
chosen based on TPP
specialization
AIS
"scope": "openid accounts"
CoF
"scope": "openid fundsconfirmations"
PIS, AIS, CoF
"scope": "openid payments accounts
"fundsconfirmations"
/token with "client_credentials"
grant type
PIS
"scope": "payments"
OpenID should not be
included in client
credentials
AIS
"scope": "accounts"
CoF
"scope": " fundsconfirmations "
/authorize
PIS
"scope":"openid payments"
A Journey needs to be
chosen based on TPP
specialization
AIS
"scope":"openid accounts"
CoF
"scope":"openid fundsconfirmations"
parameter. If you do, this will result in the error code
:
/token endpoint should be:
https://<banking area>/obie/open-banking/v1.1/oauth2/token.
For example: https://api.ob.hsbc.co.uk/obie/open-banking/v1.1/oauth2/token for HSBC Personal.
/authorize endpoint should be:
https://<banking area>
For example: https://api.ob.hsbc.co.uk for HSBC Personal.
4.2.5. MTLS when token_endpoint_auth_method is tls_client_auth
If MTLS tls_client_auth is used the tls_client_auth_subject_dn claim in the registration JWT must contain the full DN (Distinguished
Name) of the transport (QWAC, OBWAC) certificate that the TPP will present to the ASPSP token endpoint to establish mutual TLS
connection. The order of the attributes must also be the same as in the certificate subject value. Please note that this should not
For example, a valid value would be: CN=00158000016i44JAAQ,2.5.4.97=#131050534447422D4643412D373635313132,O=HSBC
UK Bank Plc,C=GB
Expected format of tls_client_auth_subject_dn follows a string representation -- as defined in [RFC4514] -- of the DN. Please refer to
https://tools.ietf.org/html/rfc4512#section-2 for formal definition of DN, RDN and attribute value assertion (AVA).
Currently supported short names for attribute types (descriptor - https://tools.ietf.org/html/rfc4514#section-2)
18
PUBLIC
CN (2.5.4.3)
DNQUALIFIER (2.5.4.46)
C (2.5.4.6)
DNQ (2.5.4.46)
L (2.5.4.7)
SURNAME (2.5.4.4)
S (2.5.4.8)
GIVENNAME (2.5.4.42)
ST (2.5.4.8)
INITIALS (2.5.4.43)
O (2.5.4.10)
GENERATION (2.5.4.44)
OU (2.5.4.11)
EMAIL (1.2.840.113549.1.9.1)
T (2.5.4.12)
EMAILADDRESS (1.2.840.113549.1.9.1)
IP (1.3.6.1.4.1.42.2.11.2.1)
UID (0.9.2342.19200300.100.1.1)
STREET (2.5.4.9)
SERIALNUMBER (2.5.4.5)
DC (0.9.2342.19200300.100.1.25)
Multiple keywords are available for one OID.
Attribute types not present on above list should be encoded as the dotted-
Example: 1.3.6.1.4.1.311.60.2.1.3=PL
Full Example:
CN=[value],serialNumber=[value],OU=[value],O=[value],C=[value],ST=[value],2.5.4.97=[value],2.5.4.15=[value],1.3.6.1.4.1.311.60.2.1.
3=[value]
*[value] represents any value it is a placeholder for real value.
4.3. Authentication Journey
Whenever a timeout occurs on the authentication UI, or the PSU closes a web/mobile browser the consent status will be saved in
The consent status can be checked with dedicated endpoints.
In order to restart the authentication journey for the already created consent, instead of creating a new one, TPPs should call
GET/authorize to start the authentication OAUTH journey again.
4.4. Consent Expiry Date
Consent expiry is an optional field.
If consent expiry date is not populated, the consent will never expire (unless revoked by the TPP).
If consent expiry date is populated, its maximum value must be before 19/01/2038.
19
PUBLIC
4.5. Authorisation Code in OAuth Authorisation Framework
The auth_authorisation code obtained after consent-confirmation completion is only valid for 60 seconds. Within this time-frame, the
TPP must exchange the auth_authorisation code for an access token.
Please note the JWT expiry parameter (exp) in the request body should be set to a maximum of 30 mins.
Please see the summary table for token validities below:
Token
Endpoint
Time To Live
Auth Code
GET /authorize
1 minute
Access Token
POST/token
grant type: client credentials
5 minutes
Access Token
POST/token
grant type: authorization_code
scenario. If you do, this will result in the error code
AIS - 60 minutes - OAuth Code elapsed time
PIS - 5 minutes - OAuth Code elapsed time
Refresh token
POST/token
grant type: refresh_token
AISP equal to Consent Expiry Date
Or
open ended if Consent Expiry Date not specified
Or
If consent expiry date is provided and less than 90 days the
refresh token will only be valid up to the provided date
PISP
N/A there is no refresh token issued
CBPII
equal to Consent Expiry Date
or
open ended if Consent Expiry Date not specified
20
PUBLIC
4.6. Message Signing - x-jws-signature
http://openbanking.org.uk/iss must match full DN of eIDAS certificate. Please use the following command to obtain DN of the
certificate: openssl x509 -in eidas.pem -noout -subject -nameopt RFC2253
OBIE Field
Current HSBC Implementation
TPP b64 Header Claim
Must be omitted
TPP JWS Payload
Must be b64 encoded
HSBC b64 Header Claim
(response to TPPs)
Will be omitted
HSBC b64 Payload
(response to TPPs)
Will be b64 encoded
4.7. Consent Object Statuses
Statuses implemented are in line with the
Read/Write Data API Specification v3.1.11
.
On top of what is articulated in the above link:
➢ PSU inactivity results in timeout and consent is kept in AWAITING AUTHORISATION status.
➢ Web/mobile browser window closure results in keeping the consent in AWAITING AUTHORISATION status.Intentional
actions of the PSU on the HSBC authentication page result in moving the consent to REJECTED status.
➢ At any point in time a PSU can revoke a consent within HSBCs access dashboard. If this occurs, the consent will have a
REVOKED status. If TPPs attempt to access any accounts using the original consent, a 403 FORBIDDEN error will be
returned.
4.8. OBWAC / eIDAS Certificates
4.8.1. Test Certificate
In line with the electronic certificate (OBWAC & eIDAS) regulation, production APIs require a QTSP issued QWAC certificate or an
OBWAC certificate to securely connect.
For the purposes of the testing facility we provide TPPs with the required certificates to develop and test your application against our
Sandbox.
To generate a test certificate, please execute the following commands using OpenSSL:
1. Generate a new RSA private key:
$ openssl genrsa -out server.key 2048
2. Generate the X.509 Certificate Signing Request:
$ openssl req -sha256 -new -key server.key -out server.csr -outform der
21
PUBLIC
4.8.2. Certificate Requirements
Requirements for the TLS and HTTP Signature certificate:
➢ Public key algorithm: RSA-2048 bits.
➢ Signature algorithm: SHA-256 bits.
➢ Valid upon upload.
4.8.3. Certificate Refresh / Replacement
OBWAC / eIDAS Certificate Expiration and Refresh
TPPs can update expiring OBWAC / eIDAS certificates without impacting lasting consents by using their new OBWAC / eIDAS
certificates with their existing registrations, as long as the following conditions are met:
➢ The new certificate should have same full subject DN as the previous certificate.
➢ Access tokens are bound to the certificate, so previous access tokens will not work with new certificate. Thus, before using
the new certificate you need to request a new access token with corresponding new refresh tokens bound to the new
certificates.
➢ There are no steps required for fulfilment on the HSBC side prior to use of the new certificate.
OBWAC / eIDAS Certificate Rotation (prior to expiration)
rs to
refresh consents or experiencing any downtime / breakage in channel connectivity. However, the following conditions must be met:
➢ The new certificate should have same full subject DN as the previous certificate.
➢ All access tokens bound to old certificate must be discarded and new access tokens requested corresponding new refresh
tokens and new certificates.
➢ There are no steps required for fulfilment on the HSBC side prior to use of the new certificate.
4.9. Business Banking Entitlements
Business users have different types of entitlements / permissions (e.g. primary vs. secondary users) that affects their ability to view,
and therefore share information. Entitlements for PIS can trigger multi- -
Business users with a credit card will typically have a control account (parent) with multiple associated card holder accounts (child).
Only users with entitlements to the control account will be able to grant access to this account.
When a control account is presented, the account number is masked only the last 4 characters are visible. When a card holder
account is presented, the credit card number is masked only the last 4 characters are visible. The readPAN permission is not
supported. Permissions are specific to product types, where a product does not support a given permission HSBC Business will not
be able to fulfil that consent and a 4xx error will be returned.
22
PUBLIC
4.10. UK IP Address Whitelisting and grating user access for
HSBCnet users
ent
journeys as the IP address in the API request call may not be in the IP - rror
persists, the IP Whitelist can be updated or removed by the Customer by sending an email by Customer RM or Admin to Local Help
Desk as per the current process.
Before customers can use Open Banking, their HSBCnet UK system administrator must grant them the relevant permission through
the HSBCnet UK browser channel.
This is relevant for HSBC Corporate and HSBC Innovation Banking customers.
23
PUBLIC
Accounts and Transactions
24
PUBLIC
5. Accounts and Transactions Summary
As per OBIE customer research, to ensure consistency of language across AISPs and ASPSs, HSBC is now adhering to the OBIE
https://view.officeapps.live.com/op/view.aspx?src=https%3A%2F%2Fstandards.openbanking.org.uk%2Fwp-
content%2Fuploads%2F2022%2F04%2FCustomer-Experience-Guidelines-Checklist-Version-v3110-
Final.xlsx&wdOrigin=BROWSELINK for further information.
Following the consent creation, if a TPP tries to trigger any of the fulfilment endpoints for a consented account where the account has
now transitioned to an inactive state will result in an error nt could
transition to an Inactive state are Account closed, Customer not registered for Internet banking.
Note: There is a daily system maintenance window (usually takes 15 minutes), during which TPPs may encounter service failure.
HSBC Business, Kinetic, HSBCnet UK, HSBC Personal and first direct maintenance window start time - 19:00 UKT, maintenance
window end time - 03:30 UKT. M&S - 21:30 UKT and 03:00 UKT accordingly. If TPPs encounter this error during the batch window,
they should try again in 30 minutes.
5.1. Implemented Endpoints
5.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Access
consent
/account-access-consents (POST/ GET/ DELETE)
Mandatory
Y
Y
Y
Y
Y
Accounts
GET /accounts
Mandatory
Y
Y
Y
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
Y
Y
Y
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
Y
Y
Y
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
Y
Y
Y
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
Conditional
Y
Y
N
Y
Y
Direct-Debits
GET /accounts/{AccountId}/direct-debits
Conditional
Y
N
N
N
N
Standing-
orders
GET /accounts/{AccountId}/standing-orders
Conditional
Y
N
N
Y
N
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
Y
Y
N
Party
GET /accounts/{AccountId}/party
Conditional
Y
Y
Y
Y
Y
Party
GET /accounts/{AccountId}/parties
Conditional
Y
Y
Y
Y
Y
Scheduled-
payments
GET /accounts/{AccountId}/scheduled-payments
Conditional
Y
Y
N
Y
Y
Offers
GET /accounts/{AccountId}/offers
Mandatory
N
N
Y
N
N
Offers
GET /offers
Conditional
N
N
N
N
N
Statements
GET /accounts/{AccountId}/statements
Conditional
N
N
Y
N
N
Statements
GET /accounts/{AccountId}/statements/{StatementId}
Conditional
N
N
Y
N
N
25
PUBLIC
Statements
GET /accounts/{AccountId}/statements/{StatementId}/transactions
Conditional
N
N
Y
N
N
*As per direct channel availability, this functionality will not be available for customers on a weekly basis between Saturday 22:00 and
Sunday 08:00.
5.1.2. HSBC Business Banking
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Access
consent
/account-access-consents (POST/ GET/ DELETE)
Mandatory
Y
Y
Y
Y
Y
Y
Accounts
GET /accounts
Mandatory
Y
Y
Y
Y
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
Y
Y
Y
Y
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
Y
Y
Y
Y
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
Y
Y
Y
Y
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
Conditional
Y
N
Y
N
N
Y
Beneficiaries
GET /beneficiaries
Optional
N
N
N
N
N
N
Direct-
Debits
GET /accounts/{AccountId}/direct-debits
Conditional
Y
N
Y
N
N
N
Standing-
orders
GET /accounts/{AccountId}/standing-orders
Conditional
Y
N
Y
N
N
N
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
Y
Y
Y
Y
Party
GET /accounts/{AccountId}/party
Conditional
Y
Y
Y
Y
Y
Y
Party
GET /accounts/{AccountId}/parties
Conditional
Y
Y
Y
Y
Y
Y
Scheduled-
payments
GET /accounts/{AccountId}/scheduled-payments
Conditional
Y
Y
Y
N
N
N
Statements
GET /accounts/{AccountId}/statements
Conditional
N
N
N
Y
N
N
Statements
GET /accounts/{AccountId}/statements/{StatementId}
Conditional
N
N
N
Y
N
N
Statements
GET
/accounts/{AccountId}/statements/{StatementId}/transactions
Conditional
N
N
N
Y
N
N
*As per direct channel availability, this functionality will not be available for customers on a weekly basis between Saturday 22:00 and
Sunday 08:00 GMT.
26
PUBLIC
5.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Access consent
/account-access-consents (POST/ GET/ DELETE)
Mandatory
Y
Y
Accounts
GET /accounts
Mandatory
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
Conditional
Y
N
Direct-Debits
GET /accounts/{AccountId}/direct-debits
Conditional
Y
N
Standing-orders
GET /accounts/{AccountId}/standing-orders
Conditional
Y
N
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
Party
GET /accounts/{AccountId}/party
Conditional
N
N
Party
GET /accounts/{AccountId}/parties
Conditional
Y
N
Scheduled-
payments
GET /accounts/{AccountId}/scheduled-payments
Conditional
Y
N
Statements
GET /accounts/{AccountId}/statements
Conditional
N
Y
Statements
GET /accounts/{AccountId}/statements/{StatementId}
Conditional
N
Y
Statements
GET /accounts/{AccountId}/statements/{StatementId}/transactions
Conditional
N
Y
5.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Access consent
/account-access-consents (POST/ GET/ DELETE)
Mandatory
Y
Y
Y
Accounts
GET /accounts
Mandatory
Y
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
Y
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
Y
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
Y
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
Conditional
Y
N
N
Direct-Debits
GET /accounts/{AccountId}/direct-debits
Conditional
Y
N
N
Standing-orders
GET /accounts/{AccountId}/standing-orders
Conditional
N
N
N
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
Y
Party
GET /accounts/{AccountId}/party
Conditional
N
N
N
Party
GET /accounts/{AccountId}/parties
Conditional
Y
Y
Y
27
PUBLIC
Scheduled-payments
GET /accounts/{AccountId}/scheduled-payments
Conditional
Y
N
N
Statements
GET /accounts/{AccountId}/statements
Conditional
N
N
N
Statements
GET /accounts/{AccountId}/statements/{StatementId}
Conditional
N
N
N
Statements
GET /accounts/{AccountId}/statements/{StatementId}/transactions
Conditional
N
N
N
*As per direct channel availability, this functionality will not be available for customers on a weekly basis between Saturday 22:00 and
Sunday 08:00.
5.2. In-scope Products
5.2.1. HSBC Personal
Products
Available for APIs
All current accounts
In Scope
Online Bonus Saver
In Scope
Flexible Saver
In Scope
Premier Savings
In Scope
My Savings / Premier My Savings
In Scope
Credit Cards
In Scope
Future Saver for Children
In Scope
Foreign Currency Accounts
In Scope
Global Money
In Scope
Fixed Rate Saver
Out of scope
ISA
Out of scope
Regular Saver
Out of scope
5.2.2. first direct
Products
Available for APIs
Current Accounts
In scope
Savings Accounts
In scope
28
PUBLIC
Bonus Saving Accounts
In scope
Credit Cards
In scope
Fixed Rate Savings
Out of scope
Cash ISA
Out of scope
Regular Saver
Out of scope
5.2.3. M&S Bank
Products
Available for APIs
Credit Cards
In scope
Savings Accounts
Out of scope
5.2.4. HSBC Business
Products
Available for APIs
Current Accounts
In scope
Savings Accounts
In scope
Deposit Accounts
In scope
Credit Cards
In scope
Foreign Currency Accounts
In scope
Global Wallet*
In scope
.3
for further information on account identification.
5.2.5. HSBC Kinetic
Products
Available for APIs
Current Accounts
In scope
Credit Cards
In scope
29
PUBLIC
Savings Accounts
Out of scope
5.2.6. HSBC Corporate UK (HSBCnet UK) *
Products
Available for APIs
Current Accounts
In scope
Credit Cards
In scope
Foreign Currency Accounts
In scope
Global Wallet
In scope
* TPPs authorised in the UK will only have access to HSBCnet UK accounts domiciled in the UK. TPPs authorised in an EU country
will have access to HSBCnet UK accounts domiciled in all EU countries. TPPs authorised in an EU country and included in FCA CRO /
SRO Regimes will have access to HSBCnet UK accounts domiciled in the UK and all EU countries.
5.2.7. HSBC Innovation Banking (HSBCnet UK)
Products
Available for APIs
Current Accounts
In scope
Credit Cards
In scope
Foreign Currency Accounts
In scope
30
PUBLIC
6. Account Requests API
6.1. Overview
The following values are accepted in OBReadRequest1/Data/Permissions:
➢ ReadAccountsBasic
➢ ReadAccountsDetail
➢ ReadBalances
➢ ReadBeneficiariesBasic
➢ ReadBeneficiariesDetail
➢ ReadDirectDebits
➢ ReadOffers
➢ ReadPAN
➢ ReadParty
➢ ReadProducts
➢ ReadScheduledPaymentsBasic
➢ ReadScheduledPaymentsDetail
➢ ReadStandingOrdersBasic
➢ ReadStandingOrdersDetail
➢ ReadTransactionsBasic
➢ ReadTransactionsCredits
➢ ReadTransactionsDebits
➢ ReadTransactionsDetail
➢ ReadStatementsBasic
➢ ReadStatementsDetail
6.2. Implemented Endpoints
6.2.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Accounts
GET /accounts
Mandatory
Y
Y
Y
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
Y
Y
Y
31
PUBLIC
6.2.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Accounts
GET /accounts
Mandatory
Y
Y
Y
Y
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
Y
Y
Y
Y
For card products get/accounts endpoint returns the control account in SecondaryIdentification field where the user has the required
entitlements.
6.2.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Accounts
GET /accounts
Mandatory
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
6.2.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Accounts
GET /accounts
Mandatory
Y
Y
Y
Accounts
GET /accounts/{AccountId}
Mandatory
Y
Y
Y
32
PUBLIC
6.3. Key Information about Account Identification
Product
Type
Field
Notes
Credit Cards
Data/Account/Account/Id
entification
HSBC Personal, first direct - Masked credit card number
M&S Bank Masked card account number
HSBC Business Masked credit card control account (parent) and credit card holder account (child)
HSBC Kinetic Masked credit card number
HSBCnet UK format: AccountCountryCode+AccountInstitution+AccountType+Un-masked control card
account number. For commercial cards, the Identification will contain the control commercial card
account number, and not the individual commercial card number. As such, the Identification will always
contain the unmasked number, even if the ReadPan attribute has not been specifically provided
Global Wallet
Data/Account/Account/S
chemeName
HSBC Business and HSBCnet - Global Wallet Account/SchemeName will be UK.OBIE.WALLET
Global Wallet
Data/Account/Account/Id
entification
HSBC Business and HSBCnet UK Global Wallet identification is 19 alphanumeric characters
WA denotes a Global Wallet account, followed by 14-digit account number and 3 letter currency code
(e.g. USD, EUR, AUD etc.)
Global Wallet
Date/Account/AccountSu
bType
HSBC Business Global Wallet AccountSubType will be Wallet
HSBCnet UK Global Wallet AccountSubType will be CurrentAccount
6.4. Credit Card Product Behaviour (replacement cards)
HSBC Personal, first direct:
Customers must authorise a new AIS consent on receipt of a new card/ (s) being issued on account of old card/ (s) being stolen, lost or upgraded. The
old card/ (s) details and its related consent will cease to exist.
M&S Bank:
Existing AIS consents relating to old card/ (s) details are retained upon issuance of a new card/ (s). There is no requirement to re-authorize existing
related consents to old card/ (s).
HSBC Business:
Existing AIS consents relating to old card/ (s) details are retained upon issuance of a new card/ (s). There is no requirement to re-authorize existing
related consents to old card/ (s).
33
PUBLIC
HSBC Kinetic:
Existing AIS consents relating to old card/ (s) details are retained upon issuance of a new card/ (s). There is no requirement to re-authorize existing
related consents to old card/ (s).
HSBC Corporate UK and HSBC Innovation Banking - HSBCnet:
Existing AIS consents relating to old card/ (s) details are retained upon issuance of a new card/ (s). There is no requirement to re-authorize existing
related consents to old card/ (s).
6.5. Current Account Switching Responses (HSBC Retail and
Business Brands)
HSBC Personal, first direct, HSBC Business and HSBC Kinetic have implemented current account switching status
functionality.
This enables TPP ability to track when an account is undergoing an account switch. Status responses are summarised
below:
Please note that the requirement for implementation of CASS functionality is n/a for HSBC Corporate UK (HSBCnet UK).
34
PUBLIC
7. Balances API
7.1. Implemented Endpoints
7.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
Y
Y
Y
Note: To retrieve the currency balances that are held for the Global Money Account, TPP will need to be able to process
7.1.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
Y
Y
Y
Y
7.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
7.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Balances
GET /accounts/{AccountId}/balances
Mandatory
Y
Y
Y
35
PUBLIC
7.2. Balance Type
7.2.1. HSBC Personal, first direct, M&S Bank
Balance API Returns- Current Accounts
Field
Definition
Population notes
Balance
Real time ledger balance
only)
Available Balance
Balance +/- total pending authorised
transactions
Credit Line Object
Overdraft amount
-
Balance API Returns Credit Cards
Field
Definition
Population notes
Balance
Real time ledger balance
only)
Available Balance
Total Credit Limit minus Balance
Credit Line Object
Total Credit Limit amount
'Credit Line'
*Minimum payment due, Immediate payment due and Last Statement Balance and related payment dates will be shared through
Credit Cards Statements End point. This endpoint will be made available in 2024.
7.2.2. HSBC Business
Balance API Returns - Business Current, Deposit and Saving Accounts
Balance.Type
CreditLine.Included
CreditLine.Type
Notes
InterimBooked
Object not populated
Object not populated
Real time ledger balance
InterimAvailable
True
Temporary
Available balance including overdraft +/- total
pending authorised transactions
Balance API Returns - Business Credit Cards
Balance.Type
CreditLine.Included
CreditLine.Type
Notes
Expected
Object not populated
Object not populated
Real time balance plus pending transactions
InterimAvailable
True
Credit
Available balance plus agreed credit limit
36
PUBLIC
7.2.3. HSBC Kinetic
Balance API Returns - Business Current, Deposit and Saving Accounts
Balance.Type
CreditLine.Included
CreditLine.Type
Notes
InterimBooked
Object not populated
Object not populated
Real time ledger balance
InterimAvailable
True
Temporary
Available balance including overdraft +/- total
pending authorised transactions
Balance API Returns - Business Credit Cards
Balance.Type
CreditLine.Included
CreditLine.Type
Notes
Expected
Object not populated
Object not populated
Real time balance plus pending transactions
InterimAvailable
True
Credit
Available balance plus agreed credit limit
7.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Balance API Returns - Current Accounts
Field
Definition
Notes
Closing Ledger Balance
Closing time ledger balance
Populates the closing balance [CLBD] as
PreviouslyClosedBooked*
Closing Available Balance
EOD ledger balance
Populates available closing balance [CLAV] as ClosingAvailable*
Current Ledger Balance
Real time ledger balance
Populates the current balance [ITBD] as InterimBooked*
Current available
Real time available balance
Populates the available balance [ITAV] as InterimAvailable*
Opening available balance
Opening available balance
Populates opening available balance [OPAV] as
OpeningAvailable*
Opening Ledger Balance
Opening ledger balance
Populates opening balance [OPBD] as OpeningBooked*
* Only if balance amount is available, otherwise not returned.
Balance API Returns - Credit Cards
Field
Definition
Notes
Current Ledger Balance
Real time ledger balance
Populates the current balance as InterimBooked*
Current available
Real time available balance
Will include the available credit as InterimAvailable*
* Only if balance amount is available, otherwise not returned.
37
PUBLIC
8. Transactions API
8.1. Overview
Both domestic and international transactions will be included in the response.
8.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
Y
Y
Y
Note: To retrieve the currency transactions that are held for the Global Money Account, TPP will need be able to process field
to display transaction in the correct currency.
8.1.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
Y
Y
Y
Y
Note: If transactions are requested for the credit card control account, all the transactions from each of the cardholder accounts, and
the control account, will be returned. If transactions are requested for a single cardholder account, only those related to that account
will be returned.
8.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
38
PUBLIC
8.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Transactions
GET /accounts/{AccountId}/transactions
Mandatory
Y
Y
Y
8.2. Transaction History
The table below outlines the transaction history and pagination limitations for each HSBC brand by product type:
HSBC brand
Product type
Max. number of
transactions
returned per
page
Transaction
status
Period supported
HSBC Personal
PCA, Savings
400 more details can
be found in the section
Pagination
Pending & Booked
6 years
HSBC Personal
HCA
400 more details can
be found in the section
Pagination
Pending & Booked
6 months
HSBC Personal
Credit Cards
300
Unbilled & Billed
1 month of Unbilled & 18 months of Billed
HSBC Personal
Global Money
Account
400
Booked
6 years
first direct
PCA, Savings
400 more details can
be found in the section
Pagination
Pending & Booked
6 years
first direct
Credit Cards
300
Unbilled & Billed
1 month of Unbilled & 18 months of Billed
M&S Bank
Credit Cards
300
Unbilled & Billed
1 month of Unbilled & 18 months of Billed
HSBC Business
BCA , Savings &
Deposit
400
Pending & Booked
7 years
HSBC Business
Foreign Currency
Accounts (FCA)
400
Pending & Booked
6 years
HSBC Business
Credit Cards
300
Unbilled & Billed
1 month of Unbilled & 18 months of Billed
HSBC Business
Global Wallet
400
Booked
7 years
Kinetic
BCA
400
Pending & Booked
7 years from 01 June 2020 (launch date of Kinetic)
Kinetic
Credit Cards
300
Unbilled & Billed
1 month of Unbilled & 18 months of Billed up to a
maximum of 300 transactions.
HSBC Corporate UK
(HSBCnet UK)
Current Accounts
400
Pending & Booked
From the start of the previous year
(Note: In Q2 of each year, data going further back
than the start of the previous year, will become
unavailable. For example: from Q2 2024 only data
from January 2023 onwards will be returned)
HSBC Corporate UK
(HSBCnet UK)
Currency Accounts
400
Pending & Booked
From the start of the previous year
(Note: In Q2 of each year, data going further back
than the start of the previous year, will become
unavailable. For example: from Q2 2024 only data
from January 2023 onwards will be returned)
HSBC Corporate UK
(HSBCnet UK)
Credit Cards
300
Unbilled & Billed
12 months
HSBC Corporate UK
(HSBCnet UK)
Global Wallet
400
Booked
12 months
HSBC Innovation
Banking
(HSBCnet UK)
Current Accounts
400
Pending & Booked
From August 2023
HSBC Innovation
Banking
(HSBCnet UK)
Currency Accounts
400
Pending & Booked
From August 2023
HSBC Innovation
Banking
(HSBCnet UK)
Credit Cards
300
Unbilled & Billed
From August 2023
39
PUBLIC
8.3. Lifespan of Next Links
When the transaction endpoint has been called for a date range greater than 90 days in the past, the 'next' link it returns has a
lifespan of 5 minutes from SCA.
If the 'next' link is used within these5 minutes, the 'next' link returned by that call will have a lifespan extended by 5 minutes, and so
forth. This is to permit traversal or large transaction data sets.
The access token must continue to be refreshed.
Anything other than Accounts, Balances and Transactions are restricted endpoints and so will be disabled once the 60 minutes since
SCA has expired, or when the next access token is received from the refresh token.
8.4. Truncation
The date ranges of the transactions returned by the GET /accounts/{AccountId}/transactions message depend upon two date ranges,
indicating the intent and requested time periods. The behaviour of the API can change depending on how these are populated (or not)
and how they overlap. This is documented in detail below:
When the TPP sends in its POST /account-requests, it can send in
transactionFromDate
and
transactionToDate:
➢ These are the time-limits of the period of transactions that the PSU has consented to the TPP seeing.
➢ These can be for any duration.
➢ If the request doesn't have these fields, HSBC defaults to
transactionFromDate
= 2190 days prior (i.e. 6 years) and
transactionToDate
= today, on a rolling basis, e.g. if the GET /accounts/{AccountId}/transactions is sent a week after the
POST /account-requests, it will have access to the most recent 7 days, but no longer have access to the 7 days at the start
of the 2190-day period from the date the POST /account-requests was sent in.
➢ When the TPP sends in GET /accounts/{AccountId}/transactions, it can send in
fromBookingDateTime
and
toBookingDateTime:
➢ HSBC will accept a future-dated
toBookingDateTime
, but this will have the same net result as setting the date to today (see
later section
Booked and Pending Transactions
) termed 'future truncation'.
➢ If no dates are provided, HSBC will return the most recent transactions working backwards from the intent's
transactionToDate..
Please also refer to Section 8.6 for pagination behaviour in this scenario.
➢ If the dates provided go beyond the maximum number of days for which transactions are available (e.g. 6 years), HSBC will
return the maximum available (6 years in this example).
➢ HSBC will truncate dates that don't crossover with the intent's
transactionFromDate
and
transactionToDate
termed
'crossover truncation'.
➢ To identify that future truncation or crossover truncation has occurred, the TPP may wish to check the 'self' link returned,
40
PUBLIC
Example 1: crossover truncation and future truncation I
|---------------------| ... INTENT period
|---------| ... GET /TRANSACTION period
X ... today
|----| ... accessible period after truncation
Example 2: crossover truncation and future truncation II
|---------| ... INTENT period
|---------------------| ... GET /TRANSACTION period
X ... today
|----| ... accessible period after truncation
Example 3: crossover truncation, but future truncation is irrelevant
|---------| ... INTENT period
|--------------| ... GET /TRANSACTION period
X ... today is irrelevant, so no future truncation occurs
|--| ... accessible period after truncation
Example 4: crossover truncation where there is no crossover
|---| ... INTENT period
|--------------| ... GET /TRANSACTION period
X ... today is irrelevant
<Nothing> ... accessible period after truncation
Example 5: no date period in the intent
|-------------------------| ... INTENT period not sent in, so defaulted to today 2190 days to today
|----------| ... GET /TRANSACTION period
X ... today
|----------| ... accessible period after truncation
41
PUBLIC
8.5. Transaction Ordering
HSBC returns the transactions in reverse date order (i.e., most recent first).
8.6. Pagination
Pending transactions (both domestic and international) are sent in the first response to the TPP followed by booked transactions.
Page size is variable according to circumstances, for example the maximum number of days' data that can be returned in a single
page will vary according to the product type being queried, and the final page of a set will almost always be smaller due to having
fewer remaining transactions.
TPPs should not rely upon any specific logic with regards to pagination nor should they rely upon the size of the returned page to
determine whether there is another, but only use the next link, if returned.
tions (if
returned to obtain
the booked transactions.
For HSBC Personal, first direct bank and PCA, Savings and HCA product types, we will return all transactions (most recent to oldest)
within a 180-day block. Where the TPP request is > 180 days, the next link must be used to retrieve the remaining transactions.
8.7. Date Filtering
HSBC accepts one, both or neither of the
fromBookingDateTime
and
toBookingDateTime
parameters being passed.
8.8. Time Filtering
HSBC does not utilise times in transaction date-times, so the time components of
fromBookingDateTime
and
toBookingDateTime
are
ignored, and data will be returned from the fromBookingDateTime 00:00:00 until the toBookingDateTime 23:59:59 (subject to
pagination).
8.9. Booked and Pending Transactions
GET /accounts/{AccountId}/transactions can return both booked and pending transactions depending on product type.
Pending transactions can have a date of today or later; booked transactions can have a date of today or earlier.
If GET /accounts/{AccountId}/transactions toBookingDateTime is set to today it will include all pending transactions.
Assuming they are both within the requested date range, pending transactions are returned before booked transactions.
When paginating the response, a page may contain both pending and booked transactions.
42
PUBLIC
8.10. Response Fields
8.10.1. HSBC Personal, first direct, M&S Bank
Field
Notes
/Data/Transaction/BankTransactionCode/code
Not returned
/Data/Transaction/ProprietaryBankTransactionCode/code
Populated with the following values for PCA and Savings Account:
))) - Contactless debit card payment
ATM - Cash machine
BP - Bill payment
CHQ - Cheque
CR - Credit
DD - Direct Debit or other BACS debit
DIV - Dividend
DR Debit
OBP - Open Banking Payment
OBT - Open Banking Transfer (me to me)
PYM - Paym
SO - Standing order
TFR - Transfer
VIS Visa
Populated with the following values for Credit Cards:
MAIL_ORDER_OR_TELEPHONE_ORDER_PURCH
ONLINE_PURCHASE
CONTACTLESS_PURCHASE
OTHER_PURCHASE
ATM_CASH_WITHDRAWAL
OTHER_CASH_WITHDRAWAL
PAYMENT
FEES
INTEREST
RETURNS_OR_REFUNDS
OTHER_TRANSACTIONS
Data/Transaction/TransactionId
Unique identifier for the transaction
Note: For credit cards, there are some scenarios of transactions which
will have the same transaction ID. These include:
▪ Transactions which incur a fee (for example ATM
withdrawal, foreign currency transaction); the transaction
and the corresponding fee will have the same transaction ID
▪ Annual fees Annual fee transactions will have the same
transaction ID
▪ Regular subscriptions Each regular (e.g. monthly)
transaction relating to a subscription will have the same
transaction ID
We advise TPPs to use a combination of transaction ID, date, and
amount to deduplicate credit card transactions.
Data/Transaction/TransactionReference
Acquirer Reference Number (for Credit Cards)
43
PUBLIC
8.10.2. HSBC Business
Field
Notes
/Data/Transaction/BankTransactionCode/code
Not returned
/Data/Transaction/ProprietaryBankTransactionCode/code
Populated with the following values for PCA and Savings Account:
))) - Contactless debit card payment
ATM - Cash machine
BP - Bill payment
CHQ - Cheque
CR - Credit
DD - Direct Debit or other BACS debit
DIV - Dividend
DR Debit
OBP - Open Banking Payment
OBT - Open Banking Transfer (me to me)
PYM - Paym
SO - Standing order
TFR - Transfer
VIS Visa
Populated with the following values for Credit Cards:
MAIL_ORDER_OR_TELEPHONE_ORDER_PURCH
ONLINE_PURCHASE
CONTACTLESS_PURCHASE
OTHER_PURCHASE
ATM_CASH_WITHDRAWAL
OTHER_CASH_WITHDRAWAL
PAYMENT
FEES
INTEREST
RETURNS_OR_REFUNDS
OTHER_TRANSACTIONS
Data/Transaction/TransactionId
Unique identifier for the transaction
Note: For credit cards, there are some scenarios of transactions which
will have the same transaction ID. These include:
▪ Transactions which incur a fee (for example ATM
withdrawal, foreign currency transaction); the transaction
and the corresponding fee will have the same transaction ID
▪ Annual fees Annual fee transactions will have the same
transaction ID
▪ Regular subscriptions Each regular (e.g. monthly)
transaction relating to a subscription will have the same
transaction ID
We advise TPPs to use a combination of transaction ID, date, and
amount to deduplicate credit card transactions.
Data/Transaction/TransactionReference
Acquirer Reference Number (for Credit Cards)
44
PUBLIC
8.10.3. HSBC Kinetic
Field
Notes
/Data/Transaction/BankTransactionCode/code
Not returned
/Data/Transaction/ProprietaryBankTransactionCode/code
Populated with the following values for BCA:
Switch
OTHER
Payment
Contactless
Transfer
Maestro
Paying at cashpoint
BILL PAYMENT
Incoming transaction
Other
OUTGOING TRANSACTION
ATM
Standing Order
Visa In-app purchase
DD indemnity claim
Open banking transfer
Visa Mobile Contactless
PAYM
INCOMING TRANSACTION
Dividend
Mastercard
Card transaction
Cirrus or Maestro
Cheque
Bill Payment
Direct Debit
Open banking payment
PBBA Debit
Solo
International Payment
Populated with the following values for Credit Cards:
MAIL_ORDER_OR_TELEPHONE_ORDER_PURCH
ONLINE_PURCHASE
CONTACTLESS_PURCHASE
OTHER_PURCHASE
ATM_CASH_WITHDRAWAL
OTHER_CASH_WITHDRAWAL
PAYMENT
FEES
INTEREST
RETURNS_OR_REFUNDS
OTHER_TRANSACTIONS
Data/Transaction/TransactionId
Unique identifier for the transaction
Note: For credit cards, there are some scenarios of transactions which
will have the same transaction ID. These include:
▪ Transactions which incur a fee (for example ATM
withdrawal, foreign currency transaction); the transaction
and the corresponding fee will have the same transaction ID
▪ Annual fees Annual fee transactions will have the same
transaction ID
▪ Regular subscriptions Each regular (e.g. monthly)
transaction relating to a subscription will have the same
transaction ID
We advise TPPs to use a combination of transaction ID, date, and
amount to deduplicate credit card transactions.
Data/Transaction/TransactionReference
Acquirer Reference Number (for Credit Cards)
45
PUBLIC
Data/Transaction/TransactionInformation
NOTE: The response for this field on International payments will be
populated with the following values:
• Original amount and currency - This is the amount to be
credited to the payee after any applicable Kinetic fees to
be paid by the payee have been deducted in the
currency instructed by the payer.
This value may be the same as the originally instructed amount,
however, it may or may not include fees depending on who the
PSU has elected to pay the fees for the transaction.
• Transaction amount - This is the amount to be paid from the
HSBC Kinetic account in GBP.
• Transaction Information (Creditor Name)
• Transaction Code - For International Payments this field will
payment
• BookingDateTime
• ExchangeRate
• SourceCurrency
• Target Currency
• MidmarketRate
• TransactionInformation (Payment Reference)
• ContractIdentification
8.10.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Field
Notes
/Data/Transaction/BankTransactionCode/code
Not returned
/Data/Transaction/ProprietaryBankTransactionCode/code
Populates value of HSBC global code same as shown on HSBCnet direct
channel
/Data/Transaction/ProprietaryBankTransactionCode/issuer
Data/Transaction/TransactionId
Unique identifier for the transaction. This identifier is only provided once
Note: For credit cards, there are some scenarios of transactions which
will have the same transaction ID. These include:
▪ Transactions which incur a fee (for example ATM
withdrawal, foreign currency transaction); the transaction
and the corresponding fee will have the same transaction ID
▪ Annual fees Annual fee transactions will have the same
transaction ID
▪ Regular subscriptions Each regular (e.g. monthly)
transaction relating to a subscription will have the same
transaction ID
We advise TPPs to use a combination of transaction ID, date, and
amount to deduplicate credit card transactions.
Data/Transaction/TransactionReference
Bank reference of a transaction.
*For Credit cards this is NA
8.11. Mutability Flag
A mutability flag will be returned on applicable transactions as part of the response. Mutable transactions are for noting and could
change as part of some of our backend processing, whilst immutable transactions will not ordinarily be subject to any further
processing.
46
PUBLIC
In most cases the flag will turn from immutable to mutable the next calendar date after the transaction is booked.
8.12. Restricted Data for Lasting Consents (also known as
Article 10A access)
TPPs can access all the data clusters included in the customer consent within 60 minutes of SCA.
For subsequent requests, TPPs can only access Balance and the last 90 days of transaction history without SCA (customer not
present). More specifically:
The following endpoints are available outside of Article 10A access (i.e. without re-SCA).
➢ GET /accounts
➢ GET /accounts/{AccountId}
➢ GET /accounts/{AccountId}/balances
➢ GET /accounts/{AccountId}/transactions
These are examples of the Restricted endpoints which are available within the 60 minutes of SCA
➢ GET /accounts/{AccountId}/direct-debits
➢ GET /accounts/{AccountId}/standing-orders
➢ GET /accounts/{AccountId}/beneficiaries
Following the first 60 minutes after SCA these are only available if the customer re-SCAs and for another 60 minutes.
For requests outside the Article 10A exemption, we return only the data clusters allowed (Balance and Transactions under 90 days)
and return 403 errors for other data clusters, which may be included in the same request (e.g. standing orders).
For the Transactions data cluster, more specifically, the data requested must be for up to 90 days in order to return a successful
response. If a request includes transactions that are older than 90 days, then a 403 will be returned for the entire cluster; partial
responses are not returned. The TPP can then trigger a re-SCA flow if they wish to access data outside the Article 10A exemption.
47
PUBLIC
9. Beneficiaries API
9.1. Implemented Endpoints
9.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
Conditional
Y
Y
N
Y
Y
9.1.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
^
Conditional
Y
N
Y
N
N
Y
Beneficiaries
GET /beneficiaries *
Optional
N
N
N
N
N
N
^ For this endpoint only, beneficiaries will be provided to TPP as follows:
➢
➢ For all other account types,
➢ with pagination
➢
➢ where both domestic and international beneficiaries are available, domestic beneficiaries will be returned first followed by
international beneficiaries with pagination
Customer level = all beneficiaries saved into the common beneficiary store used across accounts
Account level = beneficiaries saved into a specific beneficiary store for that account
For all account types, only forward pagination will be supported with page size of 50
* Support for this endpoint has been demised
9.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
Conditional
Y
N
48
PUBLIC
9.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
The beneficiaries resource is used by an AISP to retrieve the list of beneficiaries for a specific AccountId that the PSU has authorized
to access. The bulk beneficiaries endpoint is not supported for HSBCnet.
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Beneficiaries
GET /accounts/{AccountId}/beneficiaries
Conditional
Y
N
N
Beneficiary list
The table below outlines the beneficiary list and pagination limitations for each HSBC channel by product type:
HSBC channel
Product type
Max. number of
beneficiaries
returned per page
Beneficiary
status
Period supported
HSBCnet UK
Business
Current Accounts
50
Approved
7 years
Beneficiaries ordering
HSBCnet UK returns the beneficiary details in reverse date order (i.e., beneficiary details added in the template that is created most
recent returns first to TPP).
Pagination
HSBCnet UK returns max 50 beneficiaries/page. For cases where the number of beneficiaries received for, a particular debit account
exceeds 50, then pagination is supported, and additional records can be viewed using next and previous navigations.
Payment types supported to retrieve beneficiaries
HSBCnet UK retrieves the beneficiaries from templates which are created for below payment type:
➢ Priority Payment (PP)
➢ Inter Account Transfer (IAT)
➢ ACH Credit
➢ ACH Debit
49
PUBLIC
Response fields
HSBCnet UK returns the below fields to TPP for the received debit account if the debit account has all the necessary entitlements to
receive the specific beneficiary information.
Field
Notes
/Data/Beneficiary/CreditorAccount/Identification
Mandatory field
This field includes the Creditor account number for the approved
beneficiaries.
/Data/Beneficiary/CreditorAccount/Name
Optional field
This field contains the beneficiary's name for the approved beneficiary.
/Data/Beneficiary/CreditorAccount/SchemeName
Mandatory field
This field contains the beneficiary account number type
Possible values:
1. "UK.OBIE.SortCodeAccountNumber"
2. "UK.OBIE.IBAN"
3. "UK.OBIE.BBAN"
Out of scope
4. UK.OBIE.PAN
5. UK.OBIE.Paym
50
PUBLIC
10. Direct Debits API
10.1. Implemented Endpoints
10.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Direct-Debits
GET /accounts/{AccountId}/direct-debits
Conditional
Y
N
N
N
N
10.1.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Direct-Debits
GET /accounts/{AccountId}/direct-
debits
Conditional
Y
N
Y
N
N
N
10.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Direct-Debits
GET /accounts/{AccountId}/direct-
debits
Conditional
Y
N
10.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Direct-Debits
GET /accounts/{AccountId}/direct-debits
Conditional
Y
N
N
51
PUBLIC
11. Standing Orders API
For Personal Banking, domestic and international standing orders will be included in the response. HSBC Business Banking and HSBC
Kinetic do not currently offer international standing order functionality.
11.1. Implemented Endpoints
11.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Standing-orders
GET /accounts/{AccountId}/standing-orders
Conditional
Y
N
N
Y
N
Inactive standing orders are included in the response.
11.1.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Standing-
orders
GET /accounts/{AccountId}/standing-
orders
Conditional
Y
N
Y
N
N
N
Inactive standing orders are included in the response.
11.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Standing-orders
GET /accounts/{AccountId}/standing-
orders
Conditional
Y
N
Applies for domestic payments only
Inactive standing orders are included in the response.
52
PUBLIC
11.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet (Not
Implemented)
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Standing-orders
GET /accounts/{AccountId}/standing-orders
Conditional
N
N
N
12. Products API
12.1. Overview
The following table summarises the possible responses:
Product
ID
Product
Name
Product
Details
Credit
Interest
Overdraft
Interest
Other
Fees &
Charges
Description
X
X
of the response has a value then TPP can refer to
Open Data API for complete product reference
data for the account.
X
X
X
X
X
section is
masked, product name is populated and one or
more of the subset data sections are populated in
the response, then the product information
should be picked up from the response by the
TPP i.e. Open Data should not be referred in such
instances.
X
X
X
value and one or more of the subset data
sections are also populated in the response, then
that means a customer specific element exists on
the account e.g. an account fee in this instance.
In such scenarios the subset data section
populated in the response should be picked by
the TPP, and Open Data API should be referred
for product reference data not present in the
subset section of the response.
X
If the response contains the
populated, then that means the data is not
available to be shared in this instance.
section is
masked, product name and none of the subset
sections are populated, then that means the data
is not available to be shared in this instance.
53
PUBLIC
12.2. Implemented Endpoints
12.2.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
Y
Y
N
12.2.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
Y
Y
Y
Y
12.2.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
12.2.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Products
GET /accounts/{AccountId}/product
Conditional
Y
Y
Y
54
PUBLIC
13. Party API
13.1. Implemented Endpoints
13.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Party
GET /accounts/{AccountId}/party
Conditional
Y
Y
Y
Y
Y
Party
GET /accounts/{AccountId}/parties
Conditional
Y
Y
Y
Y
Y
13.1.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Party
GET /accounts/{AccountId}/party
Conditional
Y
Y
Y
Y
Y
Y
Party
GET /accounts/{AccountId}/parties
Conditional
Y
Y
Y
Y
Y
Y
13.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Party
GET /accounts/{AccountId}/party
Conditional
N
N
Party
GET /accounts/{AccountId}/parties
Conditional
Y
N
13.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Party
GET /accounts/{AccountId}/party
Conditional
N
N
N
Party
GET /accounts/{AccountId}/parties
Conditional
Y
Y
Y
55
PUBLIC
13.2. Permissions
The ReadParty permission is required to access GET /accounts/{AccountId}/party or GET /accounts/{AccountId}/parties. The resource
response payload does not differ depending on the permissions granted.
The ReadPartyPSU permission is required to access GET /party. However, the ReadPartyPSU permission would not be supported,
since the bulk GET
13.3. Data
HSBC Personal, first direct, M&S Bank
The Party API would surface only the below data:
➢ PartyID
➢ PartyType
➢ Name
➢ FullLegalName
For joint accounts data for both accounts holders will be returned via the Parties API.
HSBC Business and Kinetic
The Party API would surface only the below data:
➢ PartyID
➢ FullLegalName
56
PUBLIC
14. Scheduled Payments API
For all brands offering international payment functionality, the response will include domestic and international scheduled payments.
14.1. Implemented Endpoints
14.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Scheduled-
payments
GET /accounts/{AccountId}/scheduled-
payments
Conditional
Y
Y
N
Y
Y
14.1.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Scheduled-
payments
GET
/accounts/{AccountId}/scheduled-
payments
Conditional
Y
Y
Y
N
N
N
14.1.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Scheduled-
payments
GET /accounts/{AccountId}/scheduled-
payments
Conditional
Y
N
Applies for domestic payments only
14.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Mandatory
Business
Current
Accounts
Foreign
Currency
Accounts*
Credit
Cards
Scheduled-
payments
GET /accounts/{AccountId}/scheduled-
payments
Conditional
Y
N
N
57
PUBLIC
15. Offers API
15.1. Overview
ReadOffers permission cluster is implemented as per the OBIE specification.
15.2. Implemented Endpoints
15.2.1. HSBC Personal, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Offers
GET /accounts/{AccountId}/offers
Mandatory
N
N
Y
N
N
Offers
GET /offers
Optional
N
N
N
N
N
15.3. Offers Type
The below table gives detail on the type of offers that will be returned for HSBC Personal Banking:
Offer API Returns- Credit Cards
Field
Definition
Population notes
Offer
Actual offer available on a credit
card
Offer can be of 2 types: Introductory or
Promotional
Introductory offer will not have end date but will
last for 60 days for HSBC UK and 90 days for
M&S Bank from account opening date.
Promotional offer will have end date provided.
*Offer is returned only if is it available for the given credit card.
58
PUBLIC
15.4. Response fields
15.4.1. HSBC Personal, M&S Bank
GET /accounts/{AccountId}/offers
Field
Notes
Data/Offer/AccountId
Returned
Data/Offer/OfferId
Returned
Data/Offer/OfferType
Following types are supported:
Introductory
Introductory offer is for those customers who are with HSBC bank for
less than or equal to 60 days.
Promotional offer is for those customers who are with HSBC bank for
more than 60 days.
Data/Offer/Description
Returned
Data/Offer/StartDateTime
Not returned
Data/Offer/EndDateTime
Returned for Promotional offer only
Data/Offer/Rate
Returned within Data/Offer/Description
Data/Offer/Value
Not returned
Data/Offer/Term
Returned
Data/Offer/URL
For more details and to apply for Balance transfer, please sign in to
Online Banking
Data/Offer/Amount/Amount
Not returned
Data/Offer/Amount/Currency
Not returned
Data/Offer/Fee/Amount
Not returned
Data/Offer/Fee/Currency
Not returned
59
PUBLIC
16. Statements API
16.1. Overview
Statements Endpoint
ReadStatementsBasic and ReadStatementsDetail permission clusters are implemented as per the OBIE specification.
Statement Transactions Endpoint
ReadTransactionsBasic and ReadTransactionsDetail permission clusters are implemented as per the OBIE specification.
Statement Transactions are returned in reverse date order (i.e. most recent first).
Pagination for Statement Transactions Endpoint return as follows:
➢ HSBC Personal, first direct, M&S Bank - maximum of 300 transactions per page for 18 months of billed transactions
➢ HSBC Business - maximum of 100 transactions per page for 18 months of billed transactions*
➢ HSBC Kinetic - maximum of 100 transactions per page for 18 months of billed transactions*
* in
more transactions than can be delivered in a single session, then TPP will have to present a refresh token to retrieve additional
transactions. The endpoint GET /accounts/{AccountId}/statements/{StatementId}/transactions return only transactions billed for a
given statement period.
Maintenance window
There is a monthly statement file maintenance window. This occurs on the 1st Sunday of every month between 05:00 and 07:00 UK
time which usually takes 5-10 minutes. If TPPs encounter this error during this window, they should try again in 30 minutes.
60
PUBLIC
16.2. Implemented Endpoints
16.2.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Mandatory
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Statements
GET /accounts/{AccountId}/statements
Conditional
N
N
Y
N
N
Statements
GET /accounts/{AccountId}/statements/{StatementId}
Conditional
N
N
Y
N
N
Statements
GET
/accounts/{AccountId}/statements/{StatementId}/transactions
Conditional
N
N
Y
N
N
16.2.2. HSBC Business
Resource
Endpoints
Mandatory
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Statements
GET /accounts/{AccountId}/statements
Conditional
N
N
N
Y
N
N
Statements
GET /accounts/{AccountId}/statements/{StatementId}
Conditional
N
N
N
Y
N
N
Statements
GET
/accounts/{AccountId}/statements/{StatementId}/transactions
Conditional
N
N
N
Y
N
N
16.2.3. HSBC Kinetic
Resource
Endpoints
Mandatory
Business
Current
Accounts
Credit
Cards
Statements
GET /accounts/{AccountId}/statements
Conditional
N
Y
Statements
GET /accounts/{AccountId}/statements/{StatementId}
Conditional
N
Y
Statements
GET
/accounts/{AccountId}/statements/{StatementId}/transactions
Conditional
N
Y
61
PUBLIC
16.3. Response fields
16.3.1. HSBC Personal, first direct, M&S Bank
GET /accounts/{AccountId}/statements
Field
Notes
/Data/Statement/AccountId
Returned
/Data/Statement/StatementId
Returned
/Data/Statement/Type
Only RegularPeriodic
/Data/Statement/StartDateTime
Returned
/Data/Statement/EndDateTime
Returned
/Data/Statement/CreationDateTime
Returned
GET /accounts/{AccountId}/statements/{StatementId}
Field
Notes
/Data/Statement/StatementDescription
Not returned
/Data/Statement/StatementBenefit
Not returned
/Data/Statement/StatementInterest/Type
Following types supported:
UK.OBIE.Cash
Transfer plan" the
OBReadStatement2/Data/Statement/StatementInterest/Type will
OBReadStatement2/Data/Statement/StatementInterest/Description
"Money Transfer plan".
/Data/Statement/StatementInterest/Description
For Credit Cards with
Transfer plan" the
OBReadStatement2/Data/Statement/StatementInterest/Type will
OBReadStatement2/Data/Statement/StatementInterest/Description
will contain the plan typ
"Money Transfer plan".
/Data/Statement/StatementInterest/CreditDebitIndicator
Returned
/Data/Statement/StatementInterest/Frequency
Following types supported:
/Data/Statement/StatementInterest/Amount/Amount
Returned
/Data/Statement/StatementInterest/Amount/Currency
Returned
/Data/Statement/StatementFee
Not returned (data delivered via Transactions resource)
62
PUBLIC
/Data/Statement/StatementDateTime/Type
Following types supported:
/Data/Statement/StatementDateTime/DateTime
Returned
/Data/Statement/StatementRate/Type
Not returned
/Data/Statement/StatementValue
Not returned
/Data/Statement/StatementAmount/Type
Following types supported:
UK.OBIE.MinimumPaymentDue
/Data/Statement/StatementAmount/CreditDebitIndicator
Returned
/Data/Statement/StatementAmount/Amount/Amount
Returned
/Data/Statement/StatementAmount/Amount/Currency
Returned
16.3.2. HSBC Business, Kinetic
GET /accounts/{AccountId}/statements
Field
Notes
/Data/Statement/AccountId
Returned
/Data/Statement/StatementId
Returned
/Data/Statement/ StatementReference
Returned
/Data/Statement/Type
Only RegularPeriodic
/Data/Statement/StartDateTime
Returned
/Data/Statement/EndDateTime
Returned
/Data/Statement/CreationDateTime
Returned
GET /accounts/{AccountId}/statements/{StatementId}
Field
Notes
/Data/Statement/StatementDescription
Returned
/Data/Statement/StatementBenefit
Not returned
/Data/Statement/StatementInterest/Type
Following types supported:
63
PUBLIC
/Data/Statement/StatementInterest/Description
Not returned
/Data/Statement/StatementInterest/CreditDebitIndicator
Returned
/Data/Statement/StatementInterest/Frequency
Following types supported:
/Data/Statement/StatementInterest/Amount/Amount
Returned
/Data/Statement/StatementInterest/Amount/Currency
Returned
/Data/Statement/StatementFee
Not returned (data delivered via Transactions resource)
/Data/Statement/StatementDateTime/Type
Following types supported:
UK.OBIE.PurchasePromoEnd (next statement grace period end
date)
/Data/Statement/StatementDateTime/DateTime
Returned
/Data/Statement/StatementRate/Type
Only UK.OBIE.MonthlyPurchase
/Data/Statement/StatementValue
Not returned
/Data/Statement/StatementAmount/Type
Following types supported:
/Data/Statement/StatementAmount/CreditDebitIndicator
Returned
/Data/Statement/StatementAmount/Amount/Amount
Returned
/Data/Statement/StatementAmount/Amount/Currency
Returned
64
PUBLIC
Payment Initiation Summary
65
PUBLIC
17. Payment Initiation Summary
17.1. Payment limits
The below limits are correct as of this document publication date but are subject to change without notice.
17.1.1. HSBC Personal
Single Payment Limit - £25,000
Daily Payment Limit - £1,000 - £50,000 (Default limit £25,000) - Customers can personalise their daily digital payment limit between
these values.
* HSBC Personal has introduced additional limits for cryptocurrency payments. These limits restrict each payment to £2,500 and the
total payments to within a 30-day period to £10,000.
17.1.2. first direct
Single Payment Limit - £49,999
Daily Payment Limit - £49,999
* first direct has introduced additional limits for cryptocurrency payments. These limits restrict each payment to £2,500 and the total
payments to within a 30-day period to £10,000.
17.1.3. HSBC Business
Single Payment Limit - Starts at £10,000 (negotiable so may vary by customer)
Daily Payment Limit - Starts at £10,000 (negotiable so may vary by customer)
17.1.4. HSBC Kinetic
Single Payment Limit - £25,000
Daily Payment Limit - £25,000
17.1.5. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Single Payment Limit - Same as the customer's limit on the direct channel
Daily Payment Limit - Same as the customer's limit on the direct channel
66
PUBLIC
17.2. HSBC Business Key PIS Information
HSBC Business supports multi-authorisation for all payment types. It is therefore essential that any TPP initiating payments through
Business Banking indicates their requirement in the AuthorisationType field. In line with the OBIE spec, this field can contain
-authorisation is supported (AuthorisationType = Any). Failure to
indicate Authorisation Type may result in failed payments if the TPP does not support multi-authorisation.
17.3. Faster Payments
Please note there is a risk that payment requests received between 18:00 - 23:45 which are deemed to require additional fraud checks
have the potential to be rejected/declined, unless the fraud checks can be completed with the customer on the same day.
17.4. Payments Refunds
must be true and the payment initiation must be successful.
However, if the payment initiation fails, or is not complete (as per the below statues) payment refund details will not be shared even
if the readRefundAccount is true.
➢ HSBC Personal, first direct- rejected, initiationFailed
➢ HSBC Business - pending, rejected, initiationPending and initiationFailed
➢ HSBC Kinetic - rejected, initiationFailed
➢ HSBC Corporate UK and HSBC Innovation Banking HSBCnet - pending, rejected, initiationPending and initiationFailed
For international payments (HSBC Personal and HSBC Business only), apart from the debtor accounts scheme and identification, in
order to aid the payment refunds the below details will be shared as part of the payment refund object:
➢ refund/account/secondaryIdentification - IBAN of the debtor account
➢ refund/agent/schemeName - UK.OBIE.BICFI
➢ refund/agent/identification - BIC value
ers with queries over
refunds should contact the Business Internet Banking Helpdesk.
- -
authorisation payments.
67
PUBLIC
17.5. Implemented Endpoints
17.5.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts
Global
Money
Domestic-payments
/domestic-payment-consents (POST/ GET/ DELETE)
Y
Y
N
Y
Domestic-payments
POST /domestic-payments
Y
Y
N
Y
Domestic-payments
GET /domestic-payments/{DomesticPaymentId}
Y
Y
N
Y
Domestic-payments
GET /domestic-payment-consents/{ConsentId}/funds-
confirmation
Y
Y
N
Y
Domestic-scheduled-
payments
/domestic-scheduled-payment-consents (POST/ GET/
DELETE)
Y
Y
N
Y
Domestic-scheduled-
payments
POST /domestic-scheduled-payments
Y
Y
N
Y
Domestic-scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
N
Y
Domestic-standing-
orders
/domestic-standing-order-consents (POST/ GET/
DELETE)
Y
N
N
N
Domestic-standing-
orders
POST /domestic-standing-orders
Y
N
N
N
Domestic-standing-
orders
GET /domestic-standing-
orders/{DomesticStandingOrderId}
Y
N
N
N
International-payments
/international-payment-consents (POST/ GET/ DELETE)
Y
N
Y
N
International-payments
POST /international-payments
Y
N
Y
N
International-payments
GET /international-payments/{InternationalPaymentId}
Y
N
Y
N
International-payments
GET /international-payment-
consents/{ConsentId}/funds-confirmation
Y
N
Y
N
International-scheduled-
payments
/international-scheduled-payment-consents (POST/
GET/ DELETE)
Y
N
Y
N
International-scheduled-
payments
POST /international-scheduled-payments
Y
N
Y
N
International-scheduled-
payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
Y
N
International-scheduled-
payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
N
N
N
International-standing-
orders
/international-standing-order-consents
(POST/GET/DELETE)
Y
N
Y
N
International-standing-
orders
POST /international-standing-orders
Y
N
Y
N
International-standing-
orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
Y
N
Y
N
file-payments-consent
POST /file-payment-consents
N
N
N
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
N
N
N
N
file-payments-consent
GET /file-payment-consents/{ConsentId}
N
N
N
N
file-payments
POST /file-payments
N
N
N
N
file-payments
GET /file-payments/{FilePaymentId}
N
N
N
N
file-payments
GET /file-payments/{FilePaymentId}/payment-details ^
N
N
N
N
file-payments
GET /file-payments/{FilePaymentId}/report-file
N
N
N
N
Payments are allowed only to existing beneficiaries from Savings product in line with direct channels. New beneficiaries for savings
accounts can only be set up via staff channel (Phone or Branch).
68
PUBLIC
17.5.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts**
Domestic-payments
/domestic-payment-consents (POST/ GET/ DELETE)
Y
Y
Y
N
Domestic-payments
POST /domestic-payments
Y
Y
Y
N
Domestic-payments
GET /domestic-payments/{DomesticPaymentId}
Y
Y
Y
N
Domestic-payments
GET /domestic-payment-consents/{ConsentId}/funds-
confirmation
Y
Y
Y
N
Domestic-scheduled-
payments
/domestic-scheduled-payment-consents (POST/ GET/
DELETE)
Y
Y
Y
N
Domestic-scheduled-
payments
POST /domestic-scheduled-payments
Y
Y
Y
N
Domestic-scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
Y
N
Domestic-standing-
orders
/domestic-standing-order-consents (POST/ GET/
DELETE)
Y
N
Y
N
Domestic-standing-
orders
POST /domestic-standing-orders
Y
N
Y
N
Domestic-standing-
orders
GET /domestic-standing-
orders/{DomesticStandingOrderId}
Y
N
Y
N
International-
payments
/international-payment-consents (POST/ GET/ DELETE)
Y
N
N
Y
International-
payments
POST /international-payments
Y
N
N
Y
International-
payments
GET /international-payments/{InternationalPaymentId}
Y
N
N
Y
International-
payments
GET /international-payment-
consents/{ConsentId}/funds-confirmation
Y
N
N
Y
International-
scheduled-payments
/international-scheduled-payment-consents (POST/
GET/ DELETE)
Y
N
N
Y
International-
scheduled-payments
POST /international-scheduled-payments
Y
N
N
Y
International-
scheduled-payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
N
Y
International-
scheduled-payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
N
N
N
International-standing-
orders
/international-standing-order-consents
(POST/GET/DELETE)
N
N
N
N
International-standing-
orders
POST /international-standing-orders
N
N
N
N
International-standing-
orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
N
N
N
N
file-payments-consent
POST /file-payment-consents
Y
N
Y
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
Y
N
Y
N
file-payments-consent
GET /file-payment-consents/{ConsentId}
Y
N
Y
N
file-payments
POST /file-payments
Y
N
Y
N
file-payments
GET /file-payments/{FilePaymentId}
Y
N
Y
N
file-payments
GET /file-payments/{FilePaymentId}/payment-details ^
Y
N
Y
N
file-payments
GET /file-payments/{FilePaymentId}/report-file
N
N
N
N
**As per direct channel availability, this functionality will not be available for customers on a weekly basis between Saturday 22:00
and Sunday 08:00 GMT.
Please note Savings Account payments are only able to be conducted in the form of internal transfers.
69
PUBLIC
^ Only available when localinstrument is UK.OBIE.FPS
17.5.3. HSBC Kinetic
Resource
Endpoints
Business Current
Accounts
Domestic-payments
/domestic-payment-consents (POST/ GET/ DELETE)
Y
Domestic-payments
POST /domestic-payments
Y
Domestic-payments
GET /domestic-payments/{DomesticPaymentId}
Y
Domestic-payments
GET /domestic-payment-consents/{ConsentId}/funds-
confirmation
Y
Domestic-scheduled-payments
/domestic-scheduled-payment-consents (POST/ GET/ DELETE)
Y
Domestic-scheduled-payments
POST /domestic-scheduled-payments
Y
Domestic-scheduled-payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Domestic-standing-orders
/domestic-standing-order-consents (POST/ GET/ DELETE)
Y
Domestic-standing-orders
POST /domestic-standing-orders
Y
Domestic-standing-orders
GET /domestic-standing-orders/{DomesticStandingOrderId}
Y
International-payments
/international-payment-consents (POST/ GET/ DELETE)
N
International-payments
POST /international-payments
N
International-payments
GET /international-payments/{InternationalPaymentId}
N
International-payments
GET /international-payment-consents/{ConsentId}/funds-
confirmation
N
International-scheduled-
payments
/international-scheduled-payment-consents (POST/ GET/
DELETE)
N
International-scheduled-
payments
POST /international-scheduled-payments
N
International-scheduled-
payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
N
International-scheduled-
payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
International-standing-orders
/international-standing-order-consents (POST/GET/DELETE)
N
International-standing-orders
POST /international-standing-orders
N
International-standing-orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
N
file-payments-consent
POST /file-payment-consents
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
N
file-payments-consent
GET /file-payment-consents/{ConsentId}
N
file-payments
POST /file-payments
N
file-payments
GET /file-payments/{FilePaymentId}
N
file-payments
GET /file-payments/{FilePaymentId}/payment-details ^
N
file-payments
GET /file-payments/{FilePaymentId}/report-file
N
70
PUBLIC
17.5.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-payments
/domestic-payment-consents (POST/ GET/ DELETE)
Y
Y
N
Domestic-payments
POST /domestic-payments
Y
Y
N
Domestic-payments
GET /domestic-payments/{DomesticPaymentId}
Y
Y
N
Domestic-payments
GET /domestic-payment-consents/{ConsentId}/funds-
confirmation
Y
Y
N
Domestic-scheduled-
payments
/domestic-scheduled-payment-consents (POST/ GET/
DELETE)
Y
Y
N
Domestic-scheduled-
payments
POST /domestic-scheduled-payments
Y
Y
N
Domestic-scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
N
Domestic-standing-orders
/domestic-standing-order-consents (POST/ GET/ DELETE)
Y
Y
N
Domestic-standing-orders
POST /domestic-standing-orders
Y
Y
N
Domestic-standing-orders
GET /domestic-standing-orders/{DomesticStandingOrderId}
Y
Y
N
International-payments
/international-payment-consents (POST/ GET/ DELETE)
Y
N
Y
International-payments
POST /international-payments
Y
N
Y
International-payments
GET /international-payments/{InternationalPaymentId}
Y
N
Y
International-payments
GET /international-payment-consents/{ConsentId}/funds-
confirmation
Y
N
Y
International-scheduled-
payments
/international-scheduled-payment-consents (POST/ GET/
DELETE)
Y
N
Y
International-scheduled-
payments
POST /international-scheduled-payments
Y
N
Y
International-scheduled-
payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
Y
International-scheduled-
payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
N
N
International-standing-
orders
/international-standing-order-consents (POST/GET/DELETE)
Y
N
Y
International-standing-
orders
POST /international-standing-orders
Y
N
Y
International-standing-
orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
Y
N
Y
file-payments-consent
POST /file-payment-consents
Y
N
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
Y
N
N
file-payments-consent
GET /file-payment-consents/{ConsentId}
Y
N
N
file-payments
POST /file-payments
Y
N
N
file-payments
GET /file-payments/{FilePaymentId}
Y
N
N
file-payments
GET /file-payments/{FilePaymentId}/payment-details ^
N
N
N
file-payments
GET /file-payments/{FilePaymentId}/report-file
N
N
N
Please note that domestic endpoints are to be used for domestic payments in Local currency only.
71
PUBLIC
18. Domestic Payments
18.1. Implemented Endpoints
18.1.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts
Global
Money
Domestic-payments
/domestic-payment-consents (POST/ GET/
DELETE)
Y
Y
N
Y
Domestic-payments
POST /domestic-payments
Y
Y
N
Y
Domestic-payments
GET /domestic-
payments/{DomesticPaymentId}
Y
Y
N
Y
Domestic-payments
GET /domestic-payment-
consents/{ConsentId}/funds-confirmation
Y
Y
N
Y
18.1.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-payments
/domestic-payment-consents (POST/ GET/
DELETE)
Y
Y
Y
N
Domestic-payments
POST /domestic-payments
Y
Y
Y
N
Domestic-payments
GET /domestic-
payments/{DomesticPaymentId}
Y
Y
Y
N
Domestic-payments
GET /domestic-payment-
consents/{ConsentId}/funds-confirmation
Y
Y
Y
N
18.1.3. HSBC Kinetic
Resource
Endpoints
Business
Current
Accounts
Domestic-payments
/domestic-payment-consents (POST/ GET/
DELETE)
Y
Domestic-payments
POST /domestic-payments
Y
Domestic-payments
GET /domestic-
payments/{DomesticPaymentId}
Y
Domestic-payments
GET /domestic-payment-
consents/{ConsentId}/funds-confirmation
Y
72
PUBLIC
18.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-payments
/domestic-payment-consents (POST/ GET/
DELETE)
Y
Y
N
Domestic-payments
POST /domestic-payments
Y
Y
N
Domestic-payments
GET /domestic-payments/{DomesticPaymentId}
Y
Y
N
Domestic-payments
GET /domestic-payment-
consents/{ConsentId}/funds-confirmation
Y
Y
N
18.2. Request Fields
For POST /domestic-payment-consents and POST /domestic-payments:
18.2.1. HSBC Personal, first direct
Field
Notes
Error Code if invalid
AuthorisationType
Any or Single
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
InstructedAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Invalid
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
RemittanceInformation/Reference
Must be provided
Max length 18 characters and can contain only the
following A to Z, a to z, 0 to 9, &, -, ., /
If paying a credit card major beneficiary, then this
reference needs to include at least 4 numerical digits.
Payments to major beneficiaries where the reference has
less than four digits can only be made through the App to
App redirection journey. If these payments are submitted
through the browser journey they will be rejected as we
will be unable to process them. Also please note that for
payments to charities, unless there is a specific reference
please use the last four digits of the account number to
populate the reference field.
400 - UK.OBIE.Field.Invalid
18.2.2. HSBC Business
Field
Notes
Error Code if invalid
AuthorisationType
Any or Single
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Unexpected
CreditorAccount/Name
This field must be no more than 18 characters and can
contain A to Z, a to z, 0 to 9 and the special characters
& - . / (spaces are also allowed).
Payment requests that do not meet these conditions
will be rejected.
400 - UK.OBIE.Field.Invalid
73
PUBLIC
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Unexpected
InstructedAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Unexpected
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
LocalInstrument
If Local instrument = UK.OBIE.CHAPS, then consider
CHAPS
Or,
If Local instrument = UK.OBIE.FPS, then consider FPS
Or,
If Local instrument = No value, then select FPS
400 - UK.OBIE.Field.Invalid
Reference
When LocalInstrument = UK.OBIE.FPS Reference is
mandatory and must be no more than 18 characters
and can contain A to Z, a to z, 0 to 9 and the special
characters & - . / (spaces are also allowed).
If paying a credit card major beneficiary, then this
reference needs to include at least 4 numerical digits.
When LocalInstrument = UK.OBIE.CHAPS Reference
is mandatory and maximum 18 characters (as per
above). It will be concatenated with
RemittanceInformation/Unstructured and included in
the message to beneficiary in the payment instruction.
The total of the number of characters in these 2 fields
must not exceed 139
400 - UK.OBIE.Field.Invalid
Unstructured
When LocalInstrument = UK.OBIE.FPS, Unstructured
is optional. The character limit is 138 characters.
When localInstrument=uk.obie.CHAPS. Unstructured
will be concatenated with
RemittanceInformation/Reference and included in the
message to beneficiary in the payment instruction.
The total of the number of characters in these 2 fields
must not exceed 139.
400 - UK.OBIE.Field.Invalid
18.2.3. HSBC Kinetic
Field
Notes
Error Code if invalid
AuthorisationType
Any or Single
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 -
UK.OBIE.Field.Unexpected
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 -
UK.OBIE.Field.Unexpected
InstructedAmount/Currency
Must be GBP
400 -
UK.OBIE.Field.Unexpected
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
RemittanceInformation/Reference
Must be provided
Max length 18 characters and can contain only the
following A to Z, a to z, 0 to 9, &, -, ., / (spaces are also
allowed).
If paying a credit card major beneficiary, then this
reference needs to include at least 4 numerical digits.
74
PUBLIC
18.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Field
Notes
Error Code if
invalid
LocalInstrument (O)
May be optionally provided as per any of the below supported
enumeration values in case sensitive format only:
Note: UK.OBIE.BalanceTransfer, UK.OBIE.MoneyTransfer,
UK.OBIE.Paym & UK.OBIE.Link is not supported currently.
DebtorAccount/SchemeName (O)
May be optionally provided as per any of the below supported
enumeration values only:
UK.OBIE.SortCodeAccountNumber
DebtorAccount/Identification (O)
May be optionally provided as a valid IBAN, BBAN,
SortCodeAccountNumber having character length less than or
equal to 35
CreditorAccount/Name (M)
Must be provided
CreditorAccount/SchemeName (M)
Must be provided as per any of the below supported
enumeration values only:
If you wish to pay Faster Payment (ACH Credits)/ BACS Direct
Credits (ACH Credits)/ Faster Payment (Priority Payment) from
must be UK.OBIE.SortCodeAccountNumber
CreditorAccount/Identification (M)
Must be provided in SWIFT character set having character
length less than or equal to 34,
(1) Debtor and Creditor account locations should be the same
and should be only the UK.
(2) If the CreditorAccount/SchemeName is mentioned as UK.
OBIE.SortCodeAccountNumber, then this
CreditorAccount/Identification must be of numeric and of
length 14 (comprising first 6 digits as Sort Code, and last 8
digits as Account number)
CreditorPostalAddress/AddressLine
(O)
(1) If creditorPostalAddress is provided, it must be in SWIFT
character set having character length less than or equal to 35
in atmost 3 array fields of AddressLine [0-2].
-
field must not be filled.
(3) If you wish to pay Faster Payment (ACH Credits)/ BACS
then CreditorPostalAddress/AddressLine must not be provided
InstructedAmount (M)
Amount: Must not be more than 19 characters including
maximum 3 decimal places. Also, it must not be less than 0.01
Currency: Must be equal to debit account currency. For UK
domestic, the currency should only be GBP.
RemittanceInformation/Reference
(O)
May be optionally provided. Must be no more than 30
characters
RemittanceInformation/Unstructured
(O)
May be optionally provided. Must be no more than 30
characters
ReadRefundAccount (O)
May be optionally provided (Possible values Yes/No).
Must not be provided
Authorisation.AuthorisationType
Risk.DeliveryAddres.PostCode
Authorisation.CompletionDateTime
Risk.DeliveryAddres.StreetName
channelPaymentId
Risk.DeliveryAddres.TownName
Creditor.PostalAddress.AddressLine[3 and onwards] (Priority
Payment)
Risk.MerchantCategoryCode
CreditorAccount.SecondaryIdentification
Risk.MerchantCustomerIdentification
75
PUBLIC
DebtorAccount.SecondaryIdentification
Risk.PaymentContextCode
exchangeRateInformation.exchangeRate
SCASupportData.AppliedAuthenticationApproach
Risk.DeliveryAddres.AddressLine[0 -2]
SCASupportData.ReferencePaymentOrderId
Risk.DeliveryAddres.BuldingNumber
SCASupportData.RequestedSCAExemptionType
Risk.DeliveryAddres.Country
SupplementaryData
Risk.DeliveryAddres.CountrySubDivision[0-2]
18.3. Fees for CHAPS Payments
The PSU can select a different account for bearing the charges for the CHAPS transaction.
The charge will be a dynamic amount for each CHAPS transaction request.
18.4. Cut-Off Time for CHAPS Payments
HSBC Personal, first direct:
Cut-off time for CHAPS payment is 8:00 AM to 3:30 PM UK time. Any request for a CHAPS payment outside these values will be held
and processed the next working day.
HSBC Business:
Cut-off time for CHAPS payment is 8:00 AM to 5:10 PM UK time. Any request for a CHAPS payment outside these values will be
rejected. These cut-off times are aligned to the offering on the direct channels.
76
PUBLIC
18.5. Payment Status
For Single Immediate Domestic payments, a request for a payment status HSBC returns one of the following payment statuses:
Endpoint: POST /domestic-payments
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
All preceding checks such as technical
validation and customer profile were successful
therefore the payment initiation has been
accepted for execution. Debit and credit have
not been posted. This will be further updated
-pay decision. The
terminal status can be accessed via the
Get/DomesticPayment/Domestic PaymentId
endpoint.
200
Interim
HSBC Business
HSBCnet UK
When the payment needs further authorisation
from a second user (multi-auth) or is pending
review.
200
Final
All brands
Payment request is rejected (no Debit and no
Credit posted to the account).
Endpoint: GET /domestic-payments/{DomesticPaymentId}
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
All preceding checks such as technical
validation and customer profile were successful
therefore the payment initiation has been
accepted for execution. Debit and credit have
not been posted. This will be further updated
-pay decision.
200
Interim
HSBC Business
HSBCnet UK
When the payment needs further authorisation
from a second user (multi-auth) or is pending
review.
200
Final
All brands
Payment request has been processed
successfully (i.e. Debit and Credit have been
posted successfully). Current balance reflects
position after the Debit / Credit has taken place.
200
Final
All brands
Payment request is rejected (no Debit and no
Credit posted to the account).
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
authorising party. See section -
TPPs can request & receive payment status updates for up to 10 days after the payment has been posted. A final payment status can
In rare scenarios a timeout may occur, which prevents a final status being returned. If TPPs do not receive final status for a SIP by the
end of the next working day, please contact our service desk who can help manual retrieve the final status. This has to be done within
10 days of the payment.
In a scenario where a TPP terminates the connection before they have received a response from the POST endpoint, the payment may
still have been submitted for processing. I this scenario, the TPP should resubmit the payment with the same idempotency key (x-
idempotency-key) so that they can check the payment status. This will not result in a duplicate payment if using the same
idempotency key.
77
PUBLIC
19. Domestic Scheduled Payments
19.1. Implemented Endpoints
19.1.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts
Global
Money
Domestic-
scheduled-payments
/domestic-scheduled-payment-consents
(POST/ GET/ DELETE)
Y
Y
N
Y
Domestic-
scheduled-payments
POST /domestic-scheduled-payments
Y
Y
N
Y
Domestic-
scheduled-payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
N
Y
19.1.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-
scheduled-
payments
/domestic-scheduled-payment-consents
(POST/ GET/ DELETE)
Y
Y
Y
N
Domestic-
scheduled-
payments
POST /domestic-scheduled-payments
Y
Y
Y
N
Domestic-
scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
Y
N
19.1.3. HSBC Kinetic
Resource
Endpoints
Business
Current
Accounts
Domestic-scheduled-
payments
/domestic-scheduled-payment-consents
(POST/ GET/ DELETE)
Y
Domestic-scheduled-
payments
POST /domestic-scheduled-payments
Y
Domestic-scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
78
PUBLIC
19.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-scheduled-
payments
/domestic-scheduled-payment-consents (POST/
GET/ DELETE)
Y
Y
N
Domestic-scheduled-
payments
POST /domestic-scheduled-payments
Y
Y
N
Domestic-scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
N
Working capital debit accounts are NOT supported via Domestic-scheduled-payment-consents endpoint
19.2. Request Fields
For POST /domestic-scheduled-payment-consents and POST /domestic-scheduled-payments:
19.2.1. HSBC Personal, first direct
Field
Notes
Error Code if invalid
AuthorisationType
Single
400 - UK.OBIE.Field.Invalid
RequestedExecutionDateTime
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
InstructedAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Invalid
InstructedAmount/Amount
Must be provided.
400 - UK.OBIE.Field.Invalid
RemittanceInformation/Reference
Must be provided
Max length 18 characters and can contain only the following A
to Z, a to z, 0 to 9, &, -, ., /
If paying a credit card major beneficiary, then this reference
needs to include at least 4 numerical digits.
400 - UK.OBIE.Field.Invalid
19.2.2. HSBC Business
Field
Notes
Error Code if invalid
AuthorisationType
Any or Single
400 - UK.OBIE.Field.Invalid
RequestedExecutionDateTime
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/Name
This field must be no more than 18 characters, can contain A to
Z, a to z, 0 to 9 and the special characters & - . / (spaces are
also allowed).
Payment requests that do not meet these conditions will be
rejected.
N/A
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
InstructedAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Invalid
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
79
PUBLIC
RemittanceInformation/Reference
Reference is mandatory and
must be no more than 18 characters, can contain A to Z, a to z,
0 to 9, and the special characters & - . / (spaces are also
allowed).
If paying a credit card major beneficiary, then this reference
needs to include at least 4 numerical digits.
400 - UK.OBIE.Field.Invalid
CreditorPostalAddress/Country
If this field is received and is NOT GB the payment will be
rejected
400 - UK.OBIE.Field.Invalid
19.2.3. HSBC Kinetic
Field
Notes
Error Code if invalid
AuthorisationType
Any or Single
400 - UK.OBIE.Field.Invalid
RequestedExecutionDateTime
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
InstructedAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Invalid
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
RemittanceInformation/Reference
Must be provided
Max length 18 characters and can contain only the following A
to Z, a to z, 0 to 9, &, -, ., /
If paying a credit card major beneficiary, then this reference
needs to include at least 4 numerical digits.
400 - UK.OBIE.Field.Invalid
19.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Field
Notes
Error Code if
invalid
LocalInstrument (O)
May be optionally provided as per any of the below supported
enumeration values in case sensitive format only:
payments)
Note: UK.OBIE.BalanceTransfer, UK.OBIE.MoneyTransfer,
UK.OBIE.Paym, UK.OBIE.Link is not supported currently.
RequestedExecutionDateTime (M)
Must be within next 45 calendar days
DebtorAccount/SchemeName (O)
May be optionally provided as per any of the below supported
enumeration values only:
DebtorAccount/Identification (O)
May be optionally provided as a valid IBAN, BBAN,
SortCodeAccountNumber having character length less than or
equal to 35
CreditorAccount/Name (M)
Must be provided
CreditorAccount/SchemeName (M)
Must be provided as per any of the below supported
enumeration values only:
If you wish to pay BACS Direct Credits (ACH Credits) from a
must be UK.OBIE.SortCodeAccountNumber
80
PUBLIC
CreditorAccount/Identification (M)
Must be provided in SWIFT character set having character
length less than or equal to 34,
(1) Debtor and Creditor account locations should be the same
and should be only the UK.
(2) If the CreditorAccount/SchemeName is mentioned as
UK.OBIE.SortCodeAccountNumber, then this
CreditorAccount/Identification must be of numeric and of
length 14 (comprising first 6 digits as Sort Code, and last 8
digits as Account number)
CreditorPostalAddress/AddressLine
(O)
(1) If creditorPostalAddress is provided, it must be in SWIFT
character set having character length less than or equal to 35
in atmost 3 array fields of AddressLine [0-2].
-
field must not be filled.
(3) If you wish to pay BACS Direct Credits (ACH Credits) from
CreditorPostalAddress/AddressLine must not be provided
InstructedAmount (M)
Amount: Must not be more than 19 characters including
maximum 3 decimal places. Also, it must not be less than 0.01
Currency: Must be equal to debit account currency
RemittanceInformation/Reference
(O)
May be optionally provided. Must be no more than 30
characters
RemittanceInformation/Unstructured
(O)
May be optionally provided. Must be no more than 30
characters
ReadRefundAccount (O)
May be optionally provided (Possible values Yes/No).
Must not be provided
Authorisation.AuthorisationType
Risk.DeliveryAddres.PostCode
Authorisation.CompletionDateTime
Risk.DeliveryAddres.StreetName
channelPaymentId
Risk.DeliveryAddres.TownName
Creditor.PostalAddress.AddressLine[3 and onwards] (Priority
Payment)
Risk.MerchantCategoryCode
CreditorAccount.SecondaryIdentification
Risk.MerchantCustomerIdentification
DebtorAccount.SecondaryIdentification
Risk.PaymentContextCode
Risk.DeliveryAddres.AddressLine[0 -2]
SCASupportData.AppliedAuthenticationApproach
Risk.DeliveryAddres.BuldingNumber
SCASupportData.ReferencePaymentOrderId
Risk.DeliveryAddres.Country
SCASupportData.RequestedSCAExemptionType
Risk.DeliveryAddres.CountrySubDivision[0-2]
SupplementaryData
81
PUBLIC
19.3. Payment Status
For domestic scheduled payments, a request for a payment status will return one of the following statuses:
Endpoint: POST /domestic-scheduled-payments
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
The scheduled payment / standing order instruction
has been successfully received but not yet set up.
For HSBC Business, this may also mean that the
instruction needs further authorisation from a
second user (muti-auth).
200
Final
All brands
Instruction has failed
200
Final
HSBCnet UK
The instruction has been cancelled by the customer
using their online banking channel (only applies to
Scheduled Payments when the future dated
payment is cancelled by the user)
200
Final
HSBCnet UK
The instruction has been setup successfully or has
been successfully processed on the due date.
Endpoint: GET /domestic-scheduled-payments/{DomesticScheduledPaymentId}
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
The scheduled payment / standing order instruction
has been successfully received but not yet set up.
For HSBC Business, this may also mean that the
instruction needs further authorisation from a
second user (muti-auth)
200
Final
All brands
The scheduled payment or standing order has been
set up successfully
200
Final
All brands
Instruction has failed
200
Final
All brands
The instruction has been cancelled by the customer
using their online banking channel (only applies to
Scheduled Payments)
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
-
82
PUBLIC
20. Domestic Standing Orders
20.1. Implemented Endpoints
20.1.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts
Global
Money
Domestic-standing-
orders
/domestic-standing-order-consents (POST/
GET/ DELETE)
Y
N
N
N
Domestic-standing-
orders
POST /domestic-standing-orders
Y
N
N
N
Domestic-standing-
orders
GET /domestic-standing-
orders/{DomesticStandingOrderId}
Y
N
N
N
20.1.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-standing-
orders
/domestic-standing-order-consents (POST/
GET/ DELETE)
Y
N
Y
N
Domestic-standing-
orders
POST /domestic-standing-orders
Y
N
Y
N
Domestic-standing-
orders
GET /domestic-standing-
orders/{DomesticStandingOrderId}
Y
N
Y
N
20.1.3. HSBC Kinetic
Resource
Endpoints
Business
Current
Accounts
Domestic-standing-
orders
/domestic-standing-order-consents (POST/
GET/ DELETE)
Y
Domestic-standing-
orders
POST /domestic-standing-orders
Y
Domestic-standing-
orders
GET /domestic-standing-
orders/{DomesticStandingOrderId}
Y
20.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-standing-
orders
/domestic-standing-order-consents (POST/ GET/
DELETE)
Y
Y
N
Domestic-standing-
orders
POST /domestic-standing-orders
Y
Y
N
Domestic-standing-
orders
GET /domestic-standing-
orders/{DomesticStandingOrderId}
Y
Y
N
83
PUBLIC
Working capital debit accounts are NOT supported via Domestic-standing-order-consents endpoint.
20.2. Request Fields
20.2.1. HSBC Personal, Business, Kinetic
For POST /domestic-standing-order-consents and POST /domestic-standing-orders:
Field
Notes
Error Code if invalid
Frequency
See separate Permitted Frequency Values section
400 - UK.OBIE.Field.Invalid
NumberOfPayments
Mutually exclusive with presence of FinalPaymentDateTime;
one and only one must be present
If both FinalPaymentDateTime and NumberOfPayments are
not present in request then the payment will be considered as
to be on-
400 - UK.OBIE.Field.Invalid
FirstPaymentDateTime
Must be < FinalPaymentDateTime, if that field is present
Must be < RecurringPaymentDateTime
It is the TPP's responsibility to align the FirstPaymentDateTime
to the Frequency; for example if it is desired to have the first
monthly payment on 20th June, the TPP must set Frequency
= IntrvlMnthDay:01:20 (Monthly - 20th) and
FirstPaymentDateTime = 2019-06-20
Example 1 (correctly aligned):
Frequency = IntrvlMnthDay:01:10 (Monthly - 10th)
FirstPaymentDateTime = 2019-06-10
=> FirstPaymentDateTime = 2019-06-10
If they are misaligned, the system will move the
FirstPaymentDateTime to be the first date after the input
FirstPaymentDateTime that aligns with the Frequency day.
Example 2 (misaligned):
Frequency = IntrvlMnthDay:01:10 (Monthly - 10th)
FirstPaymentDateTime = 2019-06-20
=> FirstPaymentDateTime = 2019-07-10
Example 3 (misaligned):
Frequency = IntrvlMnthDay:01:20 (Monthly - 20th)
FirstPaymentDateTime = 2019-06-10
=> FirstPaymentDateTime = 2019-06-20
Note: the time element has removed from above DateTime
examples, for simplicity.
If FirstPaymentDateTime folds on weekend or UK Bank
holiday, it will automatically be moved to the next working
day after the instruction is received.
400 - UK.OBIE.Field.Invalid
RecurringPaymentAmount
Optional
If Present ReurringPaymentAmount = FinalPaymentAmount =
FirstPaymentAmount
400 - UK.OBIE.Field.Invalid
FinalPaymentAmount
Optional
If Present FinalPaymentAmount = ReurringPaymentAmount =
FirstPaymentAmount
400 - UK.OBIE.Field.Invalid
FirstPaymentAmount
Mandatory
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
FirstPaymentAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Invalid
RecurringPaymentAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Invalid
FinalPaymentAmount/Currency
Must be GBP
400 - UK.OBIE.Field.Invalid
84
PUBLIC
FinalPaymentDateTime
Mutually exclusive with presence of NumberOfPayments; one
and only one must be present
Must be > tomorrow
Must be > FirstPaymentDateTime
If both FinalPaymentDateTime and NumberOfPayments are
not present in request then the payment will be considered as
to be on-
400 - UK.OBIE.Field.Invalid
RecurringPaymentDateTime
Must be > FirstPaymentDateTime
400 - UK.OBIE.Field.Invalid
Reference
Must be provided
Max length 18 characters and can contain only letters,
numbers, spaces and the symbols ?!:;()&.,'
If paying a credit card major beneficiary, then this reference
needs to include at least 4 numerical digits.
400 - UK.OBIE.Field.Invalid
20.2.2. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
For POST /domestic-standing-order-consents and POST /domestic-standing-orders:
Field
Notes
Error Code if invalid
Initiation/Frequency (M)
Must be provided as per any of the below supported
enumeration values only:
Mon>
week, week starts from Mon>
y: IntrvlMnthDay:01:<day of the month>
month>
-01
FirstPaymentAmount (M)
Amount: Must not be more than 19 characters including
maximum 3 decimal places. Also, it must not be less than 0.01
Currency: Must be equal to debit account currency
FinalPaymentAmount (O)
Amount: Must not be more than 19 characters including
maximum 3 decimal places. Also, it must not be less than 0.01
Currency: Must be equal to debit account currency
Initiation/NumberOfPayments (O)
The max range value for numberOfPayments is dependent on
the payment type.
-Account Transfer : 2-99
-999
DebtorAccount/SchemeName (O)
May be optionally provided as per any of the below supported
enumeration values only:
DebtorAccount/Identification (O)
May be optionally provided as a valid IBAN, BBAN,
SortCodeAccountNumber having character length less than or
equal to 35
CreditorAccount/Name (M)
Must be provided
CreditorAccount/SchemeName (M)
Must be provided as per any of the below supported
enumeration values only:
If you wish to pay BACS Direct Credits (ACH Credits)/Standing
CreditorAccount/SchemeName must be
UK.OBIE.SortCodeAccountNumber
85
PUBLIC
CreditorAccount/Identification (M)
Must be provided in SWIFT character set having character
length less than or equal to 34,
(1) Debtor and Creditor account locations should be the same,
and should be only the UK.
(2) If the CreditorAccount/SchemeName is mentioned as
UK.OBIE.SortCodeAccountNumber, then this
CreditorAccount/Identification must be of numeric and of
length 14 (comprising first 6 digits as Sort Code, and last 8
digits as Account number).
CreditorPostalAddress/AddressLine
(O)
(1) May be optionally provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array
fields of AddressLine [0-2] for PP payments
-
field must not be filled.
Reference (O)
May be optionally provided
ReadRefundAccount (O)
May be optionally provided (Possible values Yes/No).
For Standing orders, only the acceptance of the flag is
supported. Actual Refund for standing order has not been
supported.
Must not be provided
Authorisation.AuthorisationType
Risk.DeliveryAddres.PostCode
Authorisation.CompletionDateTime
Risk.DeliveryAddres.StreetName
channelPaymentId
Risk.DeliveryAddres.TownName
Creditor.PostalAddress.AddressLine[3 and onwards] (Priority
Payment)
Risk.MerchantCategoryCode
CreditorAccount.SecondaryIdentification
Risk.MerchantCustomerIdentification
DebtorAccount.SecondaryIdentification
Risk.PaymentContextCode
Risk.DeliveryAddres.AddressLine[0 -2]
SCASupportData.AppliedAuthenticationApproach
Risk.DeliveryAddres.BuldingNumber
SCASupportData.ReferencePaymentOrderId
Risk.DeliveryAddres.Country
SCASupportData.RequestedSCAExemptionType
Risk.DeliveryAddres.CountrySubDivision[0-2]
SupplementaryData
20.3. Permitted Frequency Values
20.3.1. HSBC Personal, Business and Kinetic
IntrvlWkDay:01:01 Every Monday
IntrvlWkDay:02:01 Every 2 Weeks -
Mon.
IntrvlMnthDay:12:01 Yearly
IntrvlWkDay:01:02 Every Tuesday
IntrvlWkDay:02:02 Every 2 Weeks -
Tue.
IntrvlMnthDay:01:-01 Last day of
month
IntrvlWkDay:01:03 Every Wednesday
IntrvlWkDay:02:03 Every 2 Weeks -
Wed.
IntrvlWkDay:01:04 Every Thursday
IntrvlWkDay:02:04 Every 2 Weeks -
Thu.
IntrvlWkDay:01:05 Every Friday
IntrvlWkDay:02:05 Every 2 Weeks -
Fri.
86
PUBLIC
IntrvlMnthDay:01:01 Monthly - 1st
IntrvlMnthDay:03:01 1 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:11 11 Feb,May,Aug,Nov
IntrvlMnthDay:03:21 21 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:02 Monthly - 2nd
IntrvlMnthDay:03:01 1 Feb,May,Aug,Nov
IntrvlMnthDay:03:12 11 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:22 22 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:03 Monthly - 3rd
IntrvlMnthDay:03:01 1 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:12 12 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:22 22 Feb,May,Aug,Nov
IntrvlMnthDay:01:04 Monthly - 4th
IntrvlMnthDay:03:02 2 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:12 12 Feb,May,Aug,Nov
IntrvlMnthDay:03:22 22 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:05 Monthly - 5th
IntrvlMnthDay:03:02 2 Feb,May,Aug,Nov
IntrvlMnthDay:03:12 12 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:23 23 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:06 Monthly - 6th
IntrvlMnthDay:03:03 2 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:13 13 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:23 23 Feb,May,Aug,Nov
IntrvlMnthDay:01:07 Monthly - 7th
IntrvlMnthDay:03:03 3 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:13 13 Feb,May,Aug,Nov
IntrvlMnthDay:03:23 23 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:08 Monthly - 8th
IntrvlMnthDay:03:03 3 Feb,May,Aug,Nov
IntrvlMnthDay:03:13 13 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:24 24 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:09 Monthly - 9th
IntrvlMnthDay:03:03 3 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:14 14 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:24 24 Feb,May,Aug,Nov
IntrvlMnthDay:01:10 Monthly - 10th
IntrvlMnthDay:03:04 4 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:14 14 Feb,May,Aug,Nov
IntrvlMnthDay:03:24 24 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:11 Monthly - 11th
IntrvlMnthDay:03:04 4 Feb,May,Aug,Nov
IntrvlMnthDay:03:14 14 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:25 25 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:12 Monthly - 12th
IntrvlMnthDay:03:04 4 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:15 15 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:25 25 Feb,May,Aug,Nov
IntrvlMnthDay:01:13 Monthly - 13th
IntrvlMnthDay:03:05 5 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:15 15 Feb,May,Aug,Nov
IntrvlMnthDay:03:25 25 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:14 Monthly - 14th
IntrvlMnthDay:03:05 5 Feb,May,Aug,Nov
IntrvlMnthDay:03:15 15 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:26 26 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:15 Monthly - 15th
IntrvlMnthDay:03:05 5 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:16 16 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:26 26 Feb,May,Aug,Nov
IntrvlMnthDay:01:16 Monthly - 16th
IntrvlMnthDay:03:06 6 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:16 16 Feb,May,Aug,Nov
IntrvlMnthDay:03:26 26 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:17 Monthly - 17th
IntrvlMnthDay:03:06 6 Feb,May,Aug,Nov
IntrvlMnthDay:03:16 16 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:27 27 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:18 Monthly - 18th
IntrvlMnthDay:03:06 6 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:17 17 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:27 27 Feb,May,Aug,Nov
IntrvlMnthDay:01:19 Monthly - 19th
IntrvlMnthDay:03:07 7 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:17 17 Feb,May,Aug,Nov
IntrvlMnthDay:03:27 27 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:20 Monthly - 20th
IntrvlMnthDay:03:07 7 Feb,May,Aug,Nov
IntrvlMnthDay:03:17 17 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:28 28 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:21 Monthly - 21st
IntrvlMnthDay:03:07 7 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:18 18 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:28 28 Feb,May,Aug,Nov
IntrvlMnthDay:01:22 Monthly - 22nd
IntrvlMnthDay:03:08 8 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:18 18 Feb,May,Aug,Nov
IntrvlMnthDay:03:28 28 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:23 Monthly - 23rd
IntrvlMnthDay:03:08 8 Feb,May,Aug,Nov
IntrvlMnthDay:03:18 18 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:29 29 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:24 Monthly - 24th
IntrvlMnthDay:03:08 8 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:19 19 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:29 29 Feb,May,Aug,Nov
IntrvlMnthDay:01:25 Monthly - 25th
IntrvlMnthDay:03:09 9 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:19 19 Feb,May,Aug,Nov
IntrvlMnthDay:03:29 29 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:26 Monthly - 26th
IntrvlMnthDay:03:09 9 Feb,May,Aug,Nov
IntrvlMnthDay:03:19 19 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:30 30 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:27 Monthly - 27th
IntrvlMnthDay:03:09 9 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:20 20 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:30 30 Feb,May,Aug,Nov
IntrvlMnthDay:01:28 Monthly - 28th
IntrvlMnthDay:03:10 10 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:20 20 Feb,May,Aug,Nov
IntrvlMnthDay:03:30 30 Mar,Jun,Sep,Dec
IntrvlMnthDay:01:29 Monthly - 29th
IntrvlMnthDay:03:10 10 Feb,May,Aug,Nov
IntrvlMnthDay:03:20 20 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:31 31 Jan,Apr,Jul,Oct
IntrvlMnthDay:01:30 Monthly - 30th
IntrvlMnthDay:03:10 10 Mar,Jun,Sep,Dec
IntrvlMnthDay:03:21 21 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:31 31 Feb,May,Aug,Nov
IntrvlMnthDay:01:31 Monthly - 31st
IntrvlMnthDay:03:11 11 Jan,Apr,Jul,Oct
IntrvlMnthDay:03:21 21 Feb,May,Aug,Nov
IntrvlMnthDay:03:31 31 Mar,Jun,Sep,Dec
87
PUBLIC
20.4. Payment Status
For domestic standing order payments, a request for a payment status will return one of the following statuses:
Endpoint: POST /domestic-standing-orders
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
The scheduled payment / standing order instruction
has been successfully received but not yet set up.
For HSBC Business, this may also mean that the
instruction needs further authorisation from a
second user (muti-auth)
200
Final
All brands except
HSBCnet UK
Instruction has failed
Endpoint: GET /domestic-standing-orders/{DomesticStandingOrderId}
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
The scheduled payment / standing order instruction
has been successfully received but not yet set up.
For HSBC Business, this may also mean that the
instruction needs further authorisation from a
second user (muti-auth)
200
Final
All brands except
HSBCnet UK
The scheduled payment or standing order has been
set up successfully
200
Final
All brands except
HSBCnet UK
Instruction has failed
200
Final
All brands except
HSBCnet UK
The instruction has been cancelled by the customer
using their online banking channel (only applies to
Scheduled Payments)
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
-
88
PUBLIC
21. International Payments
21.1. Implemented Endpoints
21.1.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts*
Global
Money
International-
payments
/international-payment-consents (POST/
GET/ DELETE)
Y
N
Y
N
International-
payments
POST /international-payments
Y
N
Y
N
International-
payments
GET /international-
payments/{InternationalPaymentId}
Y
N
Y
N
International-
payments
GET /international-payment-
consents/{ConsentId}/funds-confirmation
Y
N
Y
N
* As per direct channel availability, this functionality will not be available for customers on a weekly basis between Saturday 22:00
and Sunday 08:00 GMT.
During the maintenance window:
➢ If Debtor account not selected at TPP scenario, HCA accounts will not be available in the HSBC PIS Consent journey
account selection page.
➢ If Debtor account is selected at TPP then that will result in an error
21.1.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Global
Wallet
International-
payments
/international-payment-consents (POST/ GET/
DELETE)
Y
N
N
Y
Y
International-
payments
POST /international-payments
Y
N
N
Y
Y
International-
payments
GET /international-
payments/{InternationalPaymentId}
Y
N
N
Y
Y
International-
payments
GET /international-payment-
consents/{ConsentId}/funds-confirmation
Y
N
N
Y
Y
21.1.3. HSBC Kinetic
Resource
Endpoints
Business
Current
Accounts
International-payments
/international-payment-consents (POST/ GET/ DELETE)
Y
International-payments
GET /international-payment-consents/{ConsentId}
Y
International-payments
POST /international-payments
Y
International-payments
GET /international-payments/{InternationalPaymentId}
Y
89
PUBLIC
International-payments
GET /international-payment-consents/{ConsentId}/funds-confirmation
Y
21.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
International-
payments
/international-payment-consents (POST/ GET/
DELETE)
Y
N
Y
International-
payments
POST /international-payments
Y
N
Y
International-
payments
GET /international-
payments/{InternationalPaymentId}
Y
N
Y
International-
payments
GET /international-payment-
consents/{ConsentId}/funds-confirmation
Y
N
Y
21.2. Request Fields
21.2.1. HSBC Personal, first direct
For POST /international-payment-consents and POST /international-payments:
Field
Notes
Error Code if invalid
AuthorisationType
Single
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
If populated then must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber or UK.OBIE.IBAN
or UK.HSBC.LocalAccountNumber (Refer section on
CreditorAccount object below)
For a Me To Me (M2M) transfer from a
Account (HCA) or vice versa the value should be
UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/Identification
If CreditorAccount/SchemeName =
UK.OBIE.SortCodeAccountNumber then identification =
SortCodeAccountNumber format (i.e. 14 digits)
If CreditorAccount/SchemeName = UK.OBIE.IBAN then
identification = IBAN format
If CreditorAccount/SchemeName =
UK.HSBC.LocalAccountNumber then identification = Local
Account Number format of that particular country
400 - UK.OBIE.Field.Invalid
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
InstructedAmount/Currency
This can be the debtor account currency
Or
If instructed amount currency is non equal to debtor account
currency then it has to match currency of transfer
400 - UK.OBIE.Field.Invalid
CurrencyOfTransfer
See above rule related to InstructedAmount/Currency
400 - UK.OBIE.Field.Invalid
DestinationCountryCode
This field must not be populated by TPPs. The International
payment routing logic is driven by
CreditorAgent/PostalAddress/Country
400 - UK.OBIE.Field.Invalid
90
PUBLIC
ChargeBearer
Must be one of
BorneByCreditor, BorneByDebtor, Shared
400 - UK.OBIE.Field.Invalid
CreditorAgent/SchemeName
Please refer to section CreditorAgent and CreditorAccount
400 - UK.OBIE.Field.Invalid
CreditorAgent/Identification
Please refer to section CreditorAgent and CreditorAccount
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress
Please refer to section Creditor/PostalAddress
400 - UK.OBIE.Field.Invalid
CreditorAgent/PostalAddress
Please refer to section CreditorAgent/PostalAddress
400 - UK.OBIE.Field.Invalid
CreditorAccount/Name
Max 35 characters
400 - UK.OBIE.Field.Invalid
ExtendedPurpose
Refer to section Optional Fields
400 - UK.OBIE.Field.Invalid
SupplementaryData
Refer to section Optional Fields
400 - UK.OBIE.Field.Invalid
21.2.2. HSBC Business
For POST /international-payment-consents and POST /international-payments:
Field
Notes
Error Code if invalid
LocalInstrument
Valid Values are any of : "UK.OBIE.SEPACreditTransfer",
"UK.OBIE.SEPAInstantCreditTransfer",
"UK.OBIE.SWIFT"
NB
HSBC systems to define the most appropriate payment route.
For Global Wallet payments Local Instrument must not be
SEPA. If supplied the payment will be rejected.
400 - UK.OBIE.Field.Invalid
InstructionPriority
TPP can send Normal or Urgent. However, HSBC Business will
process all requests with the same priority.
400 - UK.OBIE.Field.Invalid
Purpose
For payments to all countries where Purpose of Payment is
required, or when CurrencyOfTransfer is CNY, TPP must not
provide this field. (see Optional Fields section)
See Optional Fields section for details of how this and other
optional fields are restricted.
For all other payments current implementation applies.
400 - UK.OBIE.Field.Invalid
ExtendedPurpose
If Purpose and ExtendedPurpose fields are both received the
payment will be rejected.
when CurrencyOfTransfer is CNY, TPP must provide allowed
value as defined in country/currency specific tables (maximum
of 35 characters) (see Optional Fields section)
Also see Optional Fields for details of how this and other
optional fields are restricted.
For all other payments current implementation applies with the
exception that maximum of 35 characters will now apply.
Allowed characters: a-z, A-Z, 0-9 / - ? : ( ) . , ' +
400 - UK.OBIE.Field.Invalid
DestinationCountryCode
Only HSBC supported countries will be allowed and the
sanctioned country check will be applied. This field must be
provided and must match the BIC and/or IBAN - otherwise
rejected
400 - UK.OBIE.Field.Invalid
InstructedAmount
Amount:
Should not be more than 15 digits
Must not be more than GBP 250k
Currency for a payment from a non Global Wallet Account::
If the Instructed Currency and Currency of Transfer are
different, the Instructed currency must be the same as the debit
account currency. If not the payment cannot be fulfilled.
Global Wallet Payment Currency of Transfer and Instructed
Amount Currency must be the same. If not the payment cannot
be fulfilled.
400 -
UK.OBIE.Field.Unexpected
91
PUBLIC
Global Wallet Transfer Currency of Transfer and Instructed
Amount Currency must be the same, or Instructed Amount
Currency must match currency of debtor account. If not the
payment cannot be fulfilled.
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber or for a Global
Wallet UK.OBIE.Wallet
400 - UK.OBIE.Field.Invalid
DebtorAccount Identification
Global Wallet identification is 19 alphanumeric characters
WA denotes a Global Wallet account, followed by 14-digit
account number and 3 letter currency code (e.g. USD, EUR,
AUD etc)
CreditorAgent SchemeName
SchemeName
Can only be "UK.OBIE.BICFI" or
BIC value must not belong to GB
See table in section CreditorAgent and CreditorAccount for
details
400 - UK.OBIE.Field.Invalid
CreditorAccount SchemeName
Valid values would be:
"UK.OBIE.IBAN",
"UK.OBIE.SortCodeAccountNumber"
or
Global Wallet
account)
400 - UK.OBIE.Field.Invalid
CreditorAccount/Name
Max 35 characters
400 - UK.OBIE.Field.Invalid
CreditorAgent.PostalAddress
For all payments:
This object must NOT be part of the payload that is sent to
HSBC by a TPP. The payment will be rejected if details are
received in this object.
400 - UK.OBIE.Field.Invalid
ChargeBearer
For Swift this field, if supplied, must be one of the following
- BornebyDebtor
- BornebyCreditor
- Shared
For SEPA and Global Wallet payments this field, if supplied, can
400 - UK.OBIE.Field.Invalid
CreditorPostalAddress
Each field in the address array is required
Each field is max 35 characters
* For Global Wallet payments to the United States or Canada or
payments in Canadian Dollars (CAD), the TPP must provide the
CreditorPostalAddress fields.
400 - UK.OBIE.Field.Invalid
DeliveryAddress.Country
Only HSBC supported countries will be allowed. Sanctioned
country check will be applied if this field is received in the
request. Request will be rejected if country is not supported
400 - UK.OBIE.Field.Invalid
If the creditor account is recognized as belonging to the customer initiating the payment, the payment will be presented to user as an
d to the
user:
➢ CreditorAccount.SchemeName
➢ CreditorAccount.Identification
➢ CreditorAccount.Name
➢ CurrencyOfTransfer
➢ InstructedAmount.Amount
➢ InstructedAmount.Currency
92
PUBLIC
For International Transfers, if the debit account is a Business Current Account the credit account must be a Foreign Currency
Account. If this not the case the customer will be shown the relevant error message in the HSBC UI.
21.2.3. HSBC Kinetic
Field
Notes
Error Code if invalid
LocalInstrument (O)
Valid Values are any of :
"UK.OBIE.SEPACreditTransfer",
"UK.OBIE.SEPAInstantCreditTransfer",
"UK.OBIE.SWIFT"
400 - UK.OBIE.Field.Invalid
InstructionPriority
TPP can send Normal or Urgent. However, HSBC will process all
requests with the same priority.
400 - UK.OBIE.Field.Invalid
Purpose
For payments to all countries where Purpose of Payment is required, or
when CurrencyOfTransfer is CNY, TPP must not provide this field. (see
Optional Fields section)
See Optional Fields section for details of how this and other optional
fields are restricted.
For all other payments current implementation applies.
400 - UK.OBIE.Field.Invalid
ExtendedPurpose
If Purpose and ExtendedPurpose fields are both received the payment
will be rejected.
CurrencyOfTransfer is CNY, TPP must provide allowed value as defined
in country/currency specific tables (maximum of 35 characters) (see
Optional Fields section)
Also see Optional Fields for details of how this and other optional fields
are restricted.
For all other payments current implementation applies with the
exception that maximum of 35 characters will now apply.
Allowed characters: a-z, A-Z, 0-9 / - ? : ( ) . , ' +
400 - UK.OBIE.Field.Invalid
DestinationCountryCode
For International Payments DestinationCountryCode must be provided
by TPP. If this is not provided the payment request will be rejected.
Only HSBC supported countries will be allowed and the sanctioned
country check will be applied. This field must be provided and must
match the BIC and/or IBAN - otherwise rejected
400 - UK.OBIE.Field.Invalid
InstructedAmount
Amount:
HSBC Kinetic accounts have a total Daily and Transaction
Limit of GBP 25 000. This covers both domestic and international
payments.
HSBC Kinetic accounts should have a maximum of 2 decimal places
Currency:
If the Instructed Currency and Currency of Transfer are different, the
Instructed currency must be the same as the debit account currency.
If not the payment cannot be fulfilled.
400 - UK.OBIE.Field.Unexpected
DebtorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAgent SchemeName
SchemeName
Can only be "UK.OBIE.BICFI" or
BIC value must not belong to GB
See table in section CreditorAgent and CreditorAccount for details
400 - UK.OBIE.Field.Invalid
93
PUBLIC
CreditorAccount SchemeName
Valid values would be:
"UK.OBIE.IBAN",
"UK.OBIE.SortCodeAccountNumber"
400 - UK.OBIE.Field.Invalid
CreditorAccount/Name
Max 35 characters
400 - UK.OBIE.Field.Invalid
CreditorAgent. PostalAddress
For Swift and SEPA payments:
This object must NOT be part of the payload that is sent to HSBC by a
TPP. The payment will be rejected if details are received in this object.
400 - UK.OBIE.Field.Invalid
ChargeBearer
For Swift this field, if supplied, must be one of the following
- BornebyDebtor
- BornebyCreditor
- Shared
400 - UK.OBIE.Field.Invalid
CreditorPostalAddress
Each field in the address array is required
Each field is max 35 characters
400 - UK.OBIE.Field.Invalid
DeliveryAddress.Country
Only HSBC supported countries will be allowed. Sanctioned country
check will be applied if this field is received in the request. Request
will be rejected if country is not supported
400 - UK.OBIE.Field.Invalid
21.2.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
For POST /international-payment-consents and POST /international-payments:
Field
Notes
Error Code if
invalid
LocalInstrument (O)
May be optionally provided as per any of the below supported
enumeration values in case sensitive format only:
-UK payments)
Note: UK.OBIE.BalanceTransfer, UK.OBIE.MoneyTransfer,
UK.OBIE.Paym, UK.OBIE.Link is not supported currently.
UK.OBIE.BACS, UK.OBIE.CHAPS, UK.OBIE.FPS, is not supported
via International endpoint payment initiation
InstructionPriority (O)
May be
DebtorAccount/SchemeName (O)
May be optionally provided as per any of the below supported
enumeration values only:
UK.OBIE.SortCodeAccountNumber
DebtorAccount/Identification (O)
May be optionally provided as a valid IBAN, BBAN,
SortCodeAccountNumber having character length less than or
equal to 35
ChargeBearer (O)
May be optionally provided as per any of the below supported
enumeration values only:
BornebyCreditor
(1) If Debit Account Country is any passported country except UK
any passported country except UK, then this ChargeBearer may
(2) If Debit Account Country is DE, and Beneficiary Bank Location
this ChargeBearer may be optionally provided as
(3) If Debit Account Country is any passported country except UK
CreditorAccount/Name (M)
Must be provided
94
PUBLIC
Creditor/Name (O)
May be optionally provided as a value same as
CreditorAccount/Name only
CreditorAccount/SchemeName (M)
Must be provided as per any of the below supported
enumeration values only:
CreditorAccount/Identification (M)
Must be provided in SWIFT character set having character length
less than or equal to 34,
(1) Debtor and Creditor account locations should not be the
same, and should be amongst the UK and EU countries. If the
debit and credit location both are UK, then currency must not be
GBP.
(2) If the CreditorAccount/SchemeName is mentioned as
UK.OBIE.SortCodeAccountNumber, then this
CreditorAccount/Identification must be of numeric and of length
14 (comprising first 6 digits as Sort Code, and last 8 digits as
Account number)
account, then CreditorAccount/Identification must be a valid
Czech Republic IBAN or BBAN
then this CreditorAccount/Identification must be a valid Poland
IBAN or BBAN
CreditorPostalAddress/AddressLine
(1) May be optionally provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array fields
of AddressLine [0-
atmost 4 array fields of AddressLine[0-3] for SEPA payments.
then this field must be provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array fields
of AddressLine [0-2]
-
nsfer
as CAD, then this field must be provided in SWIFT character set
having character length less than or equal to 35 in atmost 3 array
fields of AddressLine [0-2]
Note:- -
Credit account country as n
CurrencyOfTransfer as not CAD, then this field must not be filled.
CreditorAgent/Identification (O)
May be optionally provided as a valid SWIFT-BIC code (length 8
or 11) or valid Local clearing code specific to the Beneficiary
Bank Location (length max 35)
CreditorAgent/Name (O)
Must not be provided
CurrencyOfTransfer (M)
Must be provided.
DestinationCountryCode (O)
Only HSBCnet UK supported countries will be allowed. Kindly
refer section 19.6.3. If creditorAccount.schemeName is
UK.OBIE.IBAN, then this field DestinationCountryCode must
match with the first 2 characters of Beneficiary account IBAN. In
addition if creditorAccount.schemeName is
UK.OBIE.SortCodeAccountNumber, then this field
DestinationCountryCode must be GB.
ExchangeRateInformation/ContractIdentification (O)
May be optionally provided as a valid pre-agreed Exchange
Contract number with character length less than or equal to 256
ExchangeRateInformation/ExchangeRate (O)
Must not be provided
ExchangeRateInformation/RateType (O)
ExchangeRateInformation/UnitCurrency (O)
May be optionally provided as value same Debit Account
Currency
ExtendedPurpose (O)
Only HSBCnet UK supported ExtendedPurpose codes will be
allowed. Kindly refer section Optional Fields
InstructedAmount (M)
Amount: Must not be more than 19 characters including
maximum 3 decimal places. Also, it must not be less than 0.01
Currency: Must be equal to debit account currency
Purpose (O)
Only HSBCnet UK supported Purpose codes will be allowed.
Kindly refer section Optional Fields
RemittanceInformation/Reference (O)
May be optionally provided. Must be no more than 30 characters
RemittanceInformation/Unstructured (O)
May be optionally provided. Must be no more than 30 characters
95
PUBLIC
ReadRefundAccount (O)
May be optionally provided (Possible values Yes/No).
Must not be provided
Authorisation.AuthorisationType
Risk.DeliveryAddres.Country
Authorisation.CompletionDateTime
Risk.DeliveryAddres.CountrySubDivision[0-2]
ChannelPaymentId
Risk.DeliveryAddres.PostCode
Creditor.PostalAddress.AddressLine[3 and onwards] (Priority
Payment)
Risk.DeliveryAddres.StreetName
Creditor.PostalAddress.AddressLine[4 and onwards] (Priority
Payment & SEPA Credit Transfer, SEPA Instant Credit Transfer)
Risk.DeliveryAddres.TownName
CreditorAccount.SecondaryIdentification
Risk.MerchantCategoryCode
CreditorAgent.Name
Risk.MerchantCustomerIdentification
CreditorAgent.PostalAddress entire Object (any field inside)
Risk.PaymentContextCode
DebtorAccount.SecondaryIdentification
SCASupportData.AppliedAuthenticationApproach
ExchangeRateInformation.exchangeRate
SCASupportData.ReferencePaymentOrderId
Risk.DeliveryAddres.AddressLine[0 -2]
SCASupportData.RequestedSCAExemptionType
Risk.DeliveryAddres.BuldingNumber
SupplementaryData
21.3. CreditorAgent and CreditorAccount
21.3.1. HSBC Personal, first direct
The TPP should provide the CreditorAgent and CreditorAccount scheme names for the different payment countries as per the table
below:
CreditorAgent/
SchemeName
CreditorAgent/
CreditorAccount/
Credito
rAccou
nt/
Countries -
/CreditorAgent
/PostalAddress
/Country
Countries
NA
NA
UK.OBIE.IBAN
IBAN
Number
Must be provided
EEA / SEPA countries
UK.OBIE.BICFI
BIC Value
11 characters
UK.OBIE.IBAN
IBAN
Number
Must be provided
Albania, Andorra, Azerbaijan, Bahrain,
Bosnia and Herzegovina, Faroe
Islands, Georgia, Greenland, Israel,
Jordan, Kazakhstan, Kuwait, Lebanon,
Macedonia, Mauritania, Moldova,
Montenegro, Pakistan, "Palestinian
Territory, Occupied", Qatar, Saudi
Arabia, Tunisia, Turkey, United Arab
Emirates
UK.HSBC.LCC
LCC Value
e.g. United States
FED Code, India
IFSC Code
UK.HSBC.LocalAccount
Number
Local
Account
Number
Must be provided
Australia, Canada, India, South Africa,
United States
96
PUBLIC
UK.OBIE.BICFI
BIC Value
11 characters
UK.HSBC.LocalAccount
Number
Local
Account
Number
Must be provided
All others
21.3.2. HSBC Business
The format of the Business Identifier Code (BIC) is 11 characters:
➢ 4-letter bank code
➢ 2-letter country code
➢ 2-letter or number location code
➢ 3-letter or number branch code (optional)
The TPP should provide the CreditorAgent and CreditorAccount scheme names for the different payment countries as per the table
below:
Local Instrument Value
CreditorAgent.
SchemeName
CreditorAgent.
Identification
CreditorAgent.
PostalAddress
Countries
UK.OBIE.SEPACreditTransfer
UK.OBIE.SEPAInstantCreditTransfer
NA
NA
Must NOT be
provided
EEA / SEPA countries
UK.OBIE.SWIFT
UK.OBIE.BICFI
BIC Value can be
either 8 or 11
characters
Must NOT be
provided
All countries for SWIFT payment route.
(For payments from a Global Wallet
account SWIFT can go as per above, but
only when the currency of transfer is-
AUD, CAD, CNY, CHF, EUR, HKD, SGD,
USD, GBP, NZD, AED, CZK, DKK, NOK,
PLN, SAR, SEK, ZAR and THB)
UK.OBIE.SWIFT
UK.OBIE.LCC
Routing code
value can be
either 6 or 9 digits
Must NOT be
provided
Australia - 6 digits
Canada - 9 digits
Lesotho - 6 digits
South Africa - 6 digits
Swaziland - 6 digits
USA - 9 digits
Blank/Null
UK.OBIE.LCC
BIC value can be
either 8 or 11
characters.
Routing code
value can be
either 6 or 9
digits.
Must NOT be
provided
For Pay Local from a Global Wallet
account, currencies include: - AUD,
CAD, CNY, CHF, EUR, HKD, JPY, SGD
and USD. Currency of transfer must
match the destination country. All will
use BIC except the following:
Australia BSB ID 6 digits
Canada Bank Code 9 digits
Hong Kong HK clearing bank no. 6
digits
USA ACH routing no. 9 digits
21.3.3. HSBC Kinetic
The format of the Business Identifier Code (BIC) is 11 characters:
➢ 4-letter bank code
➢ 2-letter country code
➢ 2-letter or number location code
➢ 3-letter or number branch code (optional)
97
PUBLIC
The TPP should provide the CreditorAgent and CreditorAccount scheme names for the different payment countries as per the table
below:
Local Instrument Value
CreditorAgent.
SchemeName
CreditorAgent.
Identification
CreditorAgent.
PostalAddress
Countries
UK.OBIE.SEPACreditTransfer
UK.OBIE.SEPAInstantCreditTransfer
NA
NA
Must NOT be
provided
EEA / SEPA countries
UK.OBIE.SWIFT
UK.OBIE.BICFI
BIC Value can be
either 8 or 11
characters
Must NOT be
provided
All countries for SWIFT payment route.
(For payments from a Global Wallet
account SWIFT can go as per above, but
only when the currency of transfer is-
AUD, CAD, CNY, CHF, EUR, HKD, SGD,
USD, GBP, NZD, AED, CZK, DKK, NOK,
PLN, SAR, SEK, ZAR and THB)
UK.OBIE.SWIFT
UK.OBIE.LCC
Routing code
value can be
either 6 or 9 digits
Must NOT be
provided
Australia - 6 digits
Canada - 9 digits
Lesotho - 6 digits
South Africa - 6 digits
Swaziland - 6 digits
USA - 9 digits
21.4. Creditor/PostalAddress
The TPP should provide the AddressLine array or the individual fields in the PostalAddress object, but not both. If the TPP is providing
the address information in the array, then it should consist of the following data elements:
Field
Notes
Error Code if invalid
Creditor/PostalAddress/Country
Must be provided (if the TPP is using the AddressLine array)
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 0
Must be provided (if the TPP is using the AddressLine array)
Department, Sub-Department, Building Number, Street Name
must be provided as comma-separated values
Max length 35 characters
If any of the values are not available then they should be left
blank or spaced out but it is important to maintain the
sequence and comma delimiter.
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 1
Non-Mandatory but if provided should consist of:
Street Name
Max length 35 characters
If the Street Name is not available then this array element
should be left blank or spaced
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 2
Must be provided (if the TPP is using the AddressLine array)
TownName
Max length 25 characters
If the TownName is not available then this array element
should be left blank or spaced
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 3
Non-Mandatory but if provided should consist of:
Postal Code
Max length 8 characters
If the Postal Code is not available then this array element
should be left blank or spaced
400 - UK.OBIE.Field.Invalid
98
PUBLIC
21.4.1. HSBC Business, HSBC Kinetic
HSBC will not support postal addresses in sanctioned countries.
If the TPP is providing the address information in the array, then it should consist of the following data elements:
Field
Notes
Error Code if invalid
Creditor/PostalAddress/Country
Must be provided (if the TPP is using the AddressLine array)
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 0
Must be provided (if the TPP is using the AddressLine array)
Department, Sub-Department, Building Number, Street Name
must be provided as comma-separated values. Max length 35
characters
If any of the values are not available then they should be left
blank or spaced out but it is important to maintain the
sequence and comma delimiter
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 1
Non-Mandatory but if provided should consist of:
Street Name. Max length 35 characters
If the Street Name is not available then this array element
should be left blank or spaced
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 2
Non-Mandatory but if provided should consist of:
TownName. Max length 25 characters
If the TownName is not available then this array element
should be left blank or spaced
400 - UK.OBIE.Field.Invalid
Creditor/PostalAddress/AddressLine
Array Element 3
Non-Mandatory but if provided should consist of:
Postal Code. Max length 8 characters
If the Postal Code is not available then this array element
should be left blank or spaced
400 - UK.OBIE.Field.Invalid
21.5. CreditorAgent/PostalAddress
21.5.1. HSBC Personal, first direct
The TPP must not provide any of the CreditorAgent Postal address fields apart from Country in the request. If TPP provides any of the
non- - nally
from the Bank Search service using the BIC/IBAN/LocalAccountNumber from the request.
Field
Notes
Error Code if
invalid
CreditorAgent/PostalAddress/Country
Must be provided. See following list under section Payment
Country CreditorAgent/PostalAddress/Country for available
values
400 - UK.OBIE.Field.Invalid
21.6. Payment Country CreditorAgent/PostalAddress/Country
HSBC will support payments to most countries where BIC and IBAN/BBAN are supported. From time to time HSBC, at its own
discretion, may suspend support for payment to certain countries in line with sanctions and other policies. If a TPP submits a
payment to a non-supported country the payment request will be rejected.
99
PUBLIC
21.6.1. HSBC Personal, first direct
Full list of countries supported for International Payments for HSBC Personal and first direct can be found in
this document
.
21.6.2. HSBC Business, HSBC Kinetic
The check for non-supported countries will be carried out on the following fields:
➢ Risk/DeliveryAddress/Country
➢ Data/Initiation/DestinationCountryCode
➢ Creditor/PostalAddress/Country
➢ CreditorAgent/PostalAddress/Country (For Swift Payments Only)
The payment will also be rejected if the DestinationCountryCode does not match the country derived from the BIC/IBAN combination
provided in the payload. This will result in 400 UK.OBIE.Field.Invalid.
21.6.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Full list of countries supported for International Payments for HSBCnet UK can be found in
this document
.
21.7. Optional fields
21.7.1. HSBC Personal, first direct
ExtendedPurpose
The a,
Malaysia, Mauritius, Pakistan, Qatar, South Africa, Thailand, UAE. The value must be from the below list:
ExtendedPurpose Description
Buying Goods
Medical Expenses
Charity
Mortgage Payment
Consultancy Services
Office Expenses
Credit Card payment
Other Expenses
Deposit
Payment - Export of goods
Donations
Personal Investment
Family Maintenance
Purchase of property
Gift Remittance
Payment to employee
Goods
Rent
100
PUBLIC
Holiday
Savings
Insurance Premium
School/Tuition Fees
Investment
Securities Investment
Invoice Payment
Services
Living fees
Transfer to own account
Loan repayment
Travel Expenses
Loan to family
Utility Payments
Management Services
Supplementary Data
be
rejected.
21.7.2. HSBC Business, HSBC Kinetic
Creditor Name
For International Payments if Creditor.Name is provided, it must be an exact match to CreditorAccount.Name. If this is not the case
the payment request will be rejected.
Exchange Rate Information
The ExchangeRateInformation object should not be included in the payment request. If it is the payment request will be rejected.
Supplementary Data
be
rejected.
SCA Support Data
The TPP should not include anything in the SCASupportData object. If anything is included in that object, the payment will be
rejected.
101
PUBLIC
Purpose of Payment:
For some countries, a set of allowed Purpose of Payment values must be supplied (using the Initiation/ExtendedPurpose field). The
set of allowed values will be specific to each country.
For certain other specified countries, a generic set of values must be supplied, and a free format option will also be available (up to
35 characters, with blank entry not allowed, using the Initiation/ExtendedPurpose field). For other countries, these generic values may
also be used, but with blank entry also allowed.
For payments to all destinations, where the currency of transfer is Chinese Yen (CNY), a Purpose of Payment from the allowed values
for payments to China must be supplied, using the Initiation/ExtendedPurpose field.
Here
can be found the attachment with a list of countries with their Purpose of Payment values and information on whether the
Purpose of Payment (PoP) is mandatory for this country.
The TPP can provide Initiation/Purpose OR Initiation/ExtendedPurpose. If both fields are received the payment will be rejected.
HSBC will map the contents of the following optional fields to our back-end systems:
➢ Initiation/Purpose OR Initiation/ExtendedPurpose
➢ RemittanceInformation/Unstructured Optional field
➢ RemittanceInformation/Reference Optional field
Any combination of these 3 fields may be used, with the following restrictions:
➢ Initiation/Purpose may only contain the 4 character ISO code for the Purpose of Payment as in the following table
➢ The total number of characters for RemittanceInformation/Reference must not exceed 34. The total number of characters
across RemittanceInformation/Unstructured and RemittanceInformation/Reference combined, must not exceed 103.
Allowed characters: a-z, A-Z, 0-9 / - ? : ( ) . , ' +
ISO codes which may be used in Initiation/Purpose field:
Description
Code
Description
Code
Description
Code
SalaryPayment
SALA
Rent
RENT
GasBill
GASB
TreasuryPayment
TREA
Royalties
ROYA
TelephoneBill
PHON
AdvancePayment
ADVA
PurchaseSaleOfServices
SCVE
OtherTelecomRelatedBill
OTLC
AgriculturalTransfer
AGRT
Securities
SECU
WaterBill
WTER
AlimonyPayment
ALMY
SocialSecurityBenefit
SSBE
Study
STDY
ChildBenefit
BECH
Subscription
SUBS
PricePayment
PRCP
UnemploymentDisabilityBenefit
BENE
TaxPayment
TAXS
Installment
INSM
BonusPayment.
BONU
ValueAddedTaxPayment
VATX
RecurringInstallmentPayment
RINP
CashManagementTransfer
CASH
ConsumerThirdPartyConsolidatedPayment
COMT
OpeningFee
OFEE
CapitalBuilding
CBFF
DebitCollectionPayment
DBTC
CancellationFee
CFEE
CharityPayment
CHAR
SupplierPayment
SUPP
GovernmentInsurance
GOVI
CollectionPayment
COLL
Hedging
HEDG
InsurancePremiumCar
INPC
CommodityTransfer
CMDT
MultipleServiceTypes
MSVC
LaborInsurance
LBRI
CommercialPayment
COMC
NotOtherwiseSpecified
NOWS
LifeInsurance
LIFI
Commission
COMM
CardPayment
CARD
PropertyInsurance
PPTI
Costs
COST
CreditCardBill
CDBL
HealthInsurance
HLTI
Copyright
CPYR
Ferry
FERB
CarLoanPrincipalRepayment
CLPR
Dividend
DIVI
Air
AIRB
HousingLoanRepayment
HLRP
ForeignExchange
FREX
Bus
BUSB
CompanySocialLoanPaymentToBank
CSLP
PurchaseSaleOfGoods
GDDS
Railway
RLWY
EstateTax
ESTX
GovernmentPayment
GOVT
ConvalescentCareFacility
CVCF
HousingTax
HSTX
InstalmentHirePurchaseAgreement
IHRP
DentalServices
DNTS
IncomeTax
INTX
IntraCompanyPayment
INTC
AnesthesiaServices
ANTS
NetIncomeTax
NITX
InsurancePremium
INSU
HomeHealthCare
HLTC
BusinessExpenses
BEXP
Interest
INTE
HospitalCare
HSPC
TrustFund
TRFD
102
PUBLIC
LicenseFee
LICF
IntermediateCareFacility
ICRF
NetworkCharge
NWCH
Loan
LOAN
LongTermCareFacility
LTCF
NetworkCommunication
NWCM
LoanRepayment
LOAR
MedicalServices
MDCS
ReceiptPayment
RCPT
Netting
NETT
VisionCare
VIEW
PaymentTerms
PTSP
Payroll
PAYR
DurableMedicaleEquipment
DMEQ
Other
OTHR
PensionPayment
PENS
CableTVBill
CBTV
WithHolding
WHLD
Refund
REFU
ElectricityBill
ELEC
21.7.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
-SEPA - -SEPA - Credit
code values must be from the below list:
Description
Code
Description
Code
Description
Code
BonusPayment||Transaction is the
payment of a bonus.
BONU
GovernmentPayment||Transaction
is a payment to or from a
government department.
GOVT
SalaryPayment||Transaction is the
payment of salaries.
SALA
CashManagementTransfer||Transaction
is a general cash management
instruction.
CASH
Hedging||Transaction is related to
the payment of a hedging
operation.
HEDG
Securities||Transaction is the
payment of securities.
SECU
CapitalBuilding||Transaction is related
to capital building fringe fortune, ie
capital building in general.
CBFF
Irrevocable Credit Card
Payment||Transaction is
reimbursement of credit card
payment.
ICCP
SocialSecurityBenefit||Transaction is
a social security benefit, ie payment
made by a government to support
individuals.
SSBE
Card Bulk Clearing|| A Service that is
settling money for a bulk of card
transactions, while referring to a
specific transaction file or other
information like terminal ID, card
acceptor ID or other transaction
details.
CBLK
Irrevocable Debit Card
Payment||Transaction is
reimbursement of debit card
payment.
IDCP
SupplierPayment||Transaction is
related to a payment to a supplier.
SUPP
Credit Card Payment||Transaction is
related to a payment of credit card.
CCRD
IntraCompanyPayment||Transaction
is an intra-company payment, ie, a
payment between two companies
belonging to the same group.
INTC
TaxPayment||Transaction is the
payment of taxes.
TAXS
TradeSettlementPayment||Transaction
is related to settlement of a trade, eg a
foreign exchange deal or a securities
transaction.
CORT
Interest||Transaction is the
payment of interest.
INTE
Trade||Transaction is related to the
payment of a trade finance
transaction.
TRAD
Debit Card Payment||Transaction is
related to a payment of debit card.
DCRD
Loan||Transaction is related to the
transfer of a loan to a borrower.
LOAN
TreasuryPayment||Transaction is
related to treasury operations. E.g.
financial contract settlement.
TREA
Dividend||Transaction is the payment
of dividends.
DIVI
OtherPayment||Other payment
purpose.
OTHR
ValueAddedTaxPayment||Transaction
is the payment of value added tax.
VATX
Epayment||Transaction is related to
ePayment via Online-Banking
EPAY
PensionPayment||Transaction is the
payment of pension.
PENS
WithHolding||Transaction is the
payment of withholding tax.
WHLD
Fee Collection||A Service that is
settling card transaction related fees
between two parties.
FCOL
then
103
PUBLIC
Description
Code
Description
Code
Description
Code
Account Management
ACCT
Dental Services
DNTS
Network Communication
NWCM
Advance Payment
ADVA
Education
EDUC
Opening Fee
OFEE
Agricultural Transfer
AGRT
Electricity Bill
ELEC
Other
OTHR
Air
AIRB
Energies
ENRG
Other Telecom Related Bill
OTLC
Allowance
ALLW
Estate Tax
ESTX
Preauthorised Debit
PADD
Alimony Payment
ALMY
Payment of Fees & Charges
FCPM
Payroll
PAYR
Annuity
ANNI
Ferry
FERB
Pension Payment
PENS
Anesthesia Services
ANTS
Foreign Exchange
FREX
Telephone Bill
PHON
Account Receivable Entry
AREN
Foreign Worker Levy
FWLV
Point Of Purchase Entry
POPE
Baby Bonus Scheme
BBSC
Gas Bill
GASB
Property Insurance
PPTI
Child Benefit
BECH
Purchase Sale Of Goods
GDDS
Price Payment
PRCP
Unemployment Disability Benefit
BENE
Purchase Sale Of Goods And
Services
GDSV
Precious Metal
PRME
Business Expenses
BEXP
Government Insurance
GOVI
Payment Terms
PTSP
Back Office Conversion Entry
BOCE
Government Payment
GOVT
Property Tax
PTXP
Bonus Payment
BONU
Purchase Sale Of Goods And
Service With Cash Back
GSCB
Re-presented Check Entry
RCKE
Bus
BUSB
Goods & Services Tax
GSTX
Receipt Payment
RCPT
Cash Management Transfer
CASH
Hedging
HEDG
Road Tax
RDTX
Capital Building
CBFF
Housing Loan Repayment
HLRP
Rebate
REBT
Cable TV Bill
CBTV
Home Health Care
HLTC
Refund
REFU
Credit Card Payment
CCRD
Health Insurance
HLTI
Rent
RENT
Credit Card Bill
CDBL
Hospital Care
HSPC
Recurring Installment Payment
RINP
Credit Payment with Cashback
CDCB
Housing Tax
HSTX
Railway
RLWY
Cash Disbursement
CDCD
Irrevocable Credit Card Payment
ICCP
Royalties
ROYA
Original Credit
CDOC
Intermediate Care Facility
ICRF
Salary Payment
SALA
Quasi cash
CDQC
Irrevocable Debit Card Payment
IDCP
Savings
SAVG
Cancellation Fee
CFEE
Instalment Hire Purchase
Agreement
IHRP
Purchase Sale of Services
SCVE
Charity Payment
CHAR
Insurance Premium Car
INPC
Securities
SECU
Car Loan Principal Repayment
CLPR
Insurance Premium
INSU
Social Security Benefits
SSBE
Commodity Transfer
CMDT
Intra Company Payment
INTC
Study
STDY
Collection Payment
COLL
Interest
INTE
Subscription
SUBS
Commercial Payment
COMC
Investment & Securities
INVS
Supplier Payment
SUPP
Commission
COMM
Invoice Payment
IVPT
Tax Payment
TAXS
Consumer Third Party
Consolidate Payment
COMT
Labour Insurance
LBRI
Telco Bill
TBIL
Costs
COST
License Fee
LICF
Town Council Service Charges
TCSC
Carpark Charges
CPKC
Life Insurance
LIFI
Telephone-Initiated Transaction
TELI
Copyright
CPYR
Liquidity Management
LIMA
Trade Services
TRAD
Cash Disbursement
CSDB
Loan
LOAN
Treasury Payment
TREA
Company Social Loan Payment
To Member Bank
CSLP
Loan Repayment
LOAR
Trust Fund
TRFD
Convalescent Care facility
CVCF
Long Term Care Facility
LTCF
Transport
TRPT
Debit Collection Payment
DBTC
Medical Services
MDCS
Utilities Bill
UBIL
Debit Card Payment
DCRD
Multiple Service Type
MSVC
Value Added Tax Payment
VATX
Deposit
DEPT
Netting
NETT
Vision Care
VIEW
Derivatives
DERI
Net Income Tax
NITX
Internet-Initiated Transaction
WEBI
Dividend
DIVD
Not Otherwise Specified
NOWS
With Holding
WHLD
Durable Medical Equipment
DMEQ
Network Charge
NWCH
Water Bill
WTER
104
PUBLIC
then
the
Code
Description
/BUSINESS/CAPITAL TRF
Capital account transactions, (capital transfers and acquisition/disposal of non-productive or non-
financial assets), capital injection, capital reduction, capital payment, direct investments, securities
investments, other investments, shareholder's loan/repayment, other capital payments as approved
by relevant regulatory authorities, fund transfers for foreign direct investment ('FDI') by enterprises
and RMB Qualified Foreign Institutional Investor ('RQFII') projects by enterprises, bonds, fund transfer
between enterprises, individual investments, etc.
/BUSINESS/CHARITY DONATION
Donation to charities (non-profit making organizations)
/BUSINESS/CURRENT ACC TXN
Income and current transfers, remittance of profits, bonus, dividend payment, tax payment and
scholarships, etc
/BUSINESS/GOODS TRADE
Cross-border settlement conducted for trade in goods, including individual retail consumptions,
general merchandise, goods for processing, goods required for repairing, goods procured in ports by
carriers, transactions to be settled by letter of credit, bills for collection, payment of import equipment
and advanced payment, etc.
/BUSINESS/SERVICE TRADE
Cross-border settlement conducted for trade in services, including individual bill payments, services
or fees relating to transportation; travel; communications; construction services; installation projects
and their subcontract services; insurance; financial services; computer and information services;
royalties and license fees; sports and entertainment; water, electricity and gas bills to be paid by
corporations or financial institutions; rent; audit fees; hotel accommodation fees; legal fees;
advertising and promotion fees; copyright and design fees; research and development fees; company
registration fees; medical expenses; government services not mentioned above and other commercial
services, etc.
If you wish to make a
then
Description
Code
Description
Code
Description
Code
Food and Live Animals
0
Postal and courier services
12140
Information services
16520
Beverages and tobacco
1000
Charter of aircraft (with crews)
12210
Royalties for usage of intellectual
property
16610
Crude Materials, inedible, except
fuels
2000
Charter of ships and vessels
(with crews)
12220
License fees to reproduce and
distribute intellectual property
16620
Minerals, Fuel and Lubricants
3000
Charter of other modes of
transport (with crews)
12230
Merchanting trade in Malaysia
16711
Animal and vegetable Oils, Fats
and waxes
4000
Rentals/operating leasing of
aircraft (without crews)
12310
Merchanting trade Abroad
16712
Chemicals and related products,
not classified elsewhere
5000
Rentals/ operating leasing of
ships and vessels (without
crews)
12320
Research and development
16730
Manufactured Goods
6000
Rentals/ operating leasing of
other transport equipment
(without crews)
12330
Architectural, engineering, and
other technical services
16740
Machinery, non-customised
packaged software and transport
equipment
7000
Fees for salvage operations
12400
Agricultural, mining, and on-site
processing
16750
Power lines, pipelines, and
undersea communication cables
7100
Repair and Maintenance of
Aircraft, Ships and Other
Transport Equipment
12500
Advertising, market research and
public opinion polling services
16760
Miscellaneous manufactured
articles
8000
Goods and services purchase by
travellers
13110
Legal services
16771
Commodities and miscellaneous
transactions, not classified
elsewhere
9000
Goods and services purchase
through official travel
13210
Accounting services
16772
Goods (Broad Classification)
9001
Goods and services purchase by
short term workers
13220
Management consulting services
16773
Refunds relating to goods
transactions
9100
Pilgrimage /religious related
13300
Rentals / operating leasing of
dwellings, other buildings and
machinery
16780
Non-monetary gold
9700
Medical-related
13400
Trade-related services
16791
Goods for
processing/manufacturing
services
10010
Education - related
13500
Waste treatment services
16792
105
PUBLIC
Freight by air
11110
Taxes on products and
productions
14410
Audio-visual and artistic related
services
16810
Freight by sea
11120
Subsidies on products and
productions
14420
Health services
16820
Freight by other modes of
transportation
11130
TeleCommunication services
16100
Education services
16830
Passenger fare by air
11210
Construction and installation
services in Malaysia
16210
Heritage and recreational
services
16840
Passenger fare by sea
11220
Construction and installation
services abroad
16220
Other personal services
16850
Passenger fare by other modes
of transportation
11230
Auxiliary insurance services
16332
Refunds relating to services
transactions
16910
Airport services
12110
Explicitly-charged financial
services
16410
Fines and penalties (Government
sector)
21132
Port services
12120
Computer services
16510
Fines and penalties
21242
Other terminal facilities
12130
21.8. FX Rate Validity
21.8.1. HSBC Personal, first direct
The FX rate quoted for international payments on the HSBC and first direct Open Banking consent journey is valid for 40 seconds
from the point when the FX rate is displayed to the customer. From the 40 second window, the customer has 30 seconds to confirm
the FX Rate/charges on the HSBC User Interface, 5 seconds for the redirection message and subsequently the TPP has 5 seconds to
post the payment instruction to HSBC. Any payment instruction received after this window will be rejected by HSBC.
FX rate function is only applicable to immediate international payments and not applicable to international scheduled payments or
international standing orders.
the endpoint for two reasons:
➢ The confirmation of funds is already done on the HSBC Open Banking consent journey.
➢ The confirmation of funds endpoint will use the time from the 5 second window, leaving the TPP a very tight window to
post the payment instruction.
21.8.2. HSBC Business, HSBC Kinetic
The FX rate quoted for international payments on the Open Banking consent journey is valid for 30 seconds from the point when the
FX rate is displayed to the customer. From the 30 second window, the customer has 20 seconds to confirm the FX Rate/charges on
the HSBC User Interface.
A 10 seconds buffer is reserved to book the rate in the instance that the rate is accepted in the last seconds of the allowed 20
seconds duration. Upon a PSU accepting the rate, it will be booked and the destination currency will be bought.
TPP is then expected to post the payment instruction within the next 30 seconds. Failure to do so adversely impact the customer, as
the rate has already been booked by HSBC. Please contact OpenBankingSupport@hsbc.com if the payment instruction fails on the
POST.
21.8.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
The FX rate quoted for international payments on the Open Banking consent journey is valid for 30 seconds from the point when the
FX rate is displayed to the customer. From the 30 second window, the customer has 20 seconds to confirm the FX Rate/charges on
the HSBCnet UK User Interface.
106
PUBLIC
A 10 seconds buffer is reserved to book the rate in the instance that the rate is accepted in the last seconds of the allowed 20
seconds duration. Upon a PSU accepting the rate, it will be booked and the destination currency will be bought.
TPP is then expected to post the payment instruction within the next 30 seconds. Failure to do so adversely impacts the customer, as
the rate has already been booked by HSBCnet UK. Please contact OpenBankingS[email protected]m if the payment instruction fails on
the POST.
21.9. Payment Status
21.9.1. HSBC Personal, first direct
A request for a payment status will return one of the following statuses:
➢ AcceptedSettlementInProcess
➢ AcceptedSettlementCompleted
➢ Rejected
21.9.2. HSBC Business, HSBC Kinetic
A request for a payment status will return one of the following statuses:
➢ AcceptedSettlementInProcess - payment initiation has been accepted for execution. Debit and credit have not been posted
➢ Pending - when further authorisation is required (in HSBC Business direct channel)
➢ Rejected - payment request is rejected, no debit or credit posted
➢ AcceptedCreditSettlementCompleted - payment request has been processed, i.e. debit and credit have been posted
successfully (SWIFT Payments Only)
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
-
21.9.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
For Single Immediate International payments, a request for a payment status HSBC returns one of the following payment statuses:
Endpoint: POST /international-payments
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
HSBCnet UK
All preceding checks such as technical validation
and customer profile were successful therefore the
payment initiation has been accepted for execution.
Debit and credit have not been posted. This will be
Co -pay
decision. The terminal status can be accessed via
107
PUBLIC
the Get/DomesticPayment/Domestic PaymentId
endpoint.
200
Final
HSBCnet UK
Payment request is rejected (no Debit and no Credit
posted to the account).
200
Interim
HSBCnet UK
Payment request is pending for authorization. The
appropriate reviewer or authoriser must approve
this payment before we can process it.
Endpoint: GET /international-payments/{InternationalPaymentId}
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
HSBCnet UK
All preceding checks such as technical validation
and customer profile were successful therefore the
payment initiation has been accepted for execution.
Debit and credit have not been posted. This will be
Co -pay
decision.
200
Final
HSBCnet UK
Payment request has been processed successfully
(i.e. Debit and Credit have been posted
successfully). Current balance reflects position
after the Debit / Credit has taken place.
200
Final
HSBCnet UK
Payment request is rejected (no Debit and no Credit
posted to the account).
200
Interim
HSBCnet UK
Payment request is pending for authorization. The
appropriate reviewer or authoriser must approve
this payment before we can process it.
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
-
108
PUBLIC
22. International Scheduled Payments
22.1. Implemented Endpoints
22.1.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts
Global
Money
International-
scheduled-payments
/international-scheduled-payment-consents
(POST/ GET/ DELETE)
Y
N
Y
N
International-
scheduled-payments
POST /international-scheduled-payments
Y
N
Y
N
International-
scheduled-payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
Y
N
International-
scheduled-payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
N
N
N
22.1.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
International-
scheduled-payments
/international-scheduled-payment-consents
(POST/ GET/ DELETE)
Y
N
N
Y
International-
scheduled-payments
POST /international-scheduled-payments
Y
N
N
Y
International-
scheduled-payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
N
Y
International-
scheduled-payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
N
N
N
22.1.3. HSBC Kinetic (Not Implemented)
Resource
Endpoints
Business
Current
Accounts
International-
scheduled-payments
/international-scheduled-payment-consents
(POST/ GET/ DELETE)
N
International-
scheduled-payments
POST /international-scheduled-payments
N
International-
scheduled-payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
N
International-
scheduled-payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
109
PUBLIC
22.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
International-
scheduled-payments
/international-scheduled-payment-consents
(POST/ GET/ DELETE)
Y
N
Y
International-
scheduled-payments
POST /international-scheduled-payments
Y
N
Y
International-
scheduled-payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
Y
International-
scheduled-payments
GET /international-scheduled-payment-
consents/{ConsentId}/funds-confirmation
N
N
N
22.2. Request Fields
For POST /international-scheduled-payment-consents and POST /international-scheduled-payments:
22.2.1. HSBC Personal, first direct
Field
Notes
Error Code if invalid
AuthorisationType
Single
400 - UK.OBIE.Field.Invalid
RequestExecutionDateTime
Must be Today +1 and no longer than today +365
Execution date must also be a valid working day
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
If populated then must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber or UK.OBIE.IBAN or
UK.HSBC.LocalAccountNumber (Refer section on CreditorAccount
object below)
(HCA)
or vice versa the value should be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/Identification
If CreditorAccount/SchemeName =
UK.OBIE.SortCodeAccountNumber then identification =
SortCodeAccountNumber format (i.e. 14 digits)
If CreditorAccount/SchemeName = UK.OBIE.IBAN then identification
= IBAN format
If CreditorAccount/SchemeName = UK.HSBC.LocalAccountNumber
then identification = Local Account Number format of that particular
country
400 - UK.OBIE.Field.Invalid
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
InstructedAmount/Currency
This can be the debtor account currency
Or
If instructed amount currency is non equal to debtor account currency
then it has to match currency of transfer
400 - UK.OBIE.Field.Invalid
CurrencyOfTransfer
See above rule related to InstructedAmount/Currency
400 - UK.OBIE.Field.Invalid
DestinationCountryCode
This field must not be populated by TPPs. The International payment
routing logic is driven by CreditorAgent/PostalAddress/Country
400 - UK.OBIE.Field.Invalid
ChargeBearer
Must be one of:
BorneByCreditor, BorneByDebtor, Shared
400 - UK.OBIE.Field.Invalid
CreditorAgent/SchemeName
Please refer to section CreditorAgent and CreditorAccount
400 - UK.OBIE.Field.Invalid
CreditorAgent/Identification
Please refer to section CreditorAgent and CreditorAccount
400 - UK.OBIE.Field.Invalid
CreditorAgent/PostalAddress
Please refer to section CreditorAgent/PostalAddress
400 - UK.OBIE.Field.Invalid
CreditorAccount/Name
Max 35 characters
400 - UK.OBIE.Field.Invalid
110
PUBLIC
ExtendedPurpose
Refer to section Optional Fields
400 - UK.OBIE.Field.Invalid
SupplementaryData.PurposeOfPayment
Refer to section Optional Fields
400 - UK.OBIE.Field.Invalid
22.2.2. HSBC Business
Field
Notes
Error Code if invalid
LocalInstrument
Valid Values can only be:
"UK.OBIE.SWIFT"
400 - UK.OBIE.Field.Invalid
InstructionPriority
TPP can send Normal or Urgent. However, HSBC Business will process
all requests with the same priority.
400 - UK.OBIE.Field.Invalid
Purpose
For payments to all countries where Purpose of Payment is required, or
when CurrencyOfTransfer is CNY, TPP must not provide this field. (see
Optional Fields section)
See Optional Fields section for details of how this and other optional fields
are restricted.
For all other payments current implementation applies.
400 - UK.OBIE.Field.Invalid
ExtendedPurpose
If Purpose and ExtendedPurpose fields are both received the payment will
be rejected.
required countries or when
CurrencyOfTransfer is CNY, TPP must provide allowed value as defined in
country/currency specific tables (maximum of 35 characters) (see Optional
Fields section)
Also see Optional Fields section for details of how this and other optional
fields are restricted.
For all other payments current implementation applies with the exception
that maximum of 35 characters will now apply.
Allowed characters: a-z, A-Z, 0-9 / - ? : ( ) . , ' +
DestinationCountryCode
Only HSBC supported countries will be allowed and sanction country
check will be applied. This field must be provided and match the BIC
and/or IBAN - otherwise rejected
400 - UK.OBIE.Field.Invalid
InstructedAmount
Amount:
Should not be more than 15 digits
Must not be more than GBP100k
Currency:
Instructed currency, Currency of Transfer and debit account currency
must all be the same.
Users will only be shown accounts of the same currency if the debit
account is not provided by the TPP.
400 - UK.OBIE.Field.Unexpected
CreditorAgent SchemeName
SchemeName
See table in International Payments for details
BIC value must not belong to GB
400 - UK.OBIE.Field.Invalid
CreditorAccount SchemeName
Valid values would be:
"UK.OBIE.IBAN",
400 - UK.OBIE.Field.Invalid
RequestedExecutionDateTime
Must be Today +1 and no longer than today +45 days
Execution date must also be a valid working day for UK
Execution date must not be a UK bank holiday
400 - UK.OBIE.Field.Invalid
Currency of Transfer
Currency: GBP only
400 - UK.OBIE.Field.Invalid
CreditorAgent.PostalAddress
This object must not be part of the payload that is sent to HSBC by a TPP.
The payment will be rejected if details are received in this object
400 - UK.OBIE.Field.Invalid
ChargeBearer
If supplied, this field must be one of the following:
- BornebyDebtor
- BornebyCreditor
- Shared
400 - UK.OBIE.Field.Invalid
CreditorPostalAddress
Each field in the address array is required
400 - UK.OBIE.Field.Invalid
RequestedExecutionDateTime:
Future dated payments value date must be on a working date. UK Bank
holidays and weekends value dates are not permitted.
InstructedAmount.Currency
And
CurrencyOfTransfer:
Only Same Currency payments (GBP to GBP) are allowed for International
Scheduled Payment.
400 - UK.OBIE.Field.Invalid
111
PUBLIC
DeliveryAddress.Country
Only HSBC supported countries will be allowed. Sanctioned country
check will be applied if this field is received in the request. Request will
be rejected if country is not supported
400 - UK.OBIE.Field.Invalid
22.2.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Field
Notes
Error Code if
invalid
LocalInstrument (O)
May be optionally provided as per any of the below supported
enumeration values in case sensitive format only:
· UK.OBIE.SWIFT (for non-UK payments)
· UK.OBIE.Target2 (for all PSD2 payments)
· UK.OBIE.Euro1 (for all PSD2 payments)
Note:- UK.OBIE.BalanceTransfer, UK.OBIE.MoneyTransfer,
UK.OBIE.Paym, UK.OBIE.Link is not supported currently.
UK.OBIE.BACS, UK.OBIE.CHAPS, UK.OBIE.FPS, is not supported
via International-scheduled endpoint payment initiation
InstructionPriority (O)
RequestedExecutionDateTime (M)
Must be provided in ISO date format and should be within next 45
calendar days
DebtorAccount/SchemeName (O)
May be optionally provided as per any of the below supported
enumeration values only:
· UK.OBIE.IBAN
· UK.OBIE.BBAN
· UK.OBIE.SortCodeAccountNumber
DebtorAccount/Identification (O)
May be optionally provided as a valid IBAN, BBAN,
SortCodeAccountNumber having character length less than or
equal to 35
ChargeBearer (O)
May be optionally provided as per any of the below supported
enumeration values only:
· BornebyDebtor
· BornebyCreditor
· Shared
(1) If Debit Account Country is any passported country except UK
Beneficiary Bank Location is
any passported country except UK, then this ChargeBearer may
(2) If Debit Account Country is DE, and Beneficiary Bank Location
this
(3) If Debit Account Country is any passported country except UK
y provided as
CreditorAccount/Name (M)
Must be provided
Creditor/Name (O)
May be optionally provided as a value same as
CreditorAccount/Name only
CreditorAccount/SchemeName (M)
Must be provided as per any of the below supported enumeration
values only:
· UK.OBIE.IBAN
· UK.OBIE.BBAN
· UK.OBIE.SortCodeAccountNumber (for UK payments)
112
PUBLIC
CreditorAccount/Identification (M)
Must be provided in SWIFT character set having character length
less than or equal to 34,
(1) Debtor and Creditor account locations should not be the same,
and should be amongst the UK and EU countries. If the debit and
credit location both are UK, then currency must not be GBP.
(2) If the CreditorAccount/SchemeName is mentioned as
UK.OBIE.SortCodeAccountNumber, then this
CreditorAccount/Identification must be of numeric and of length
14 (comprising first 6 digits as Sort Code, and last 8 digits as
Account number)
account, then CreditorAccount/Identification must be a valid
Czech Republic IBAN or BBAN
then this CreditorAccount/Identification must be a valid Poland
IBAN or BBAN
CreditorPostalAddress/AddressLine
(1) May be optionally provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array fields of
AddressLine [0-
array fields of AddressLine[0-3] for SEPA payments.
then this field must be provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array fields of
AddressLine [0-2]
-
then this field must be provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array fields of
AddressLine [0-2]
Note:- -
CurrencyOfTransfer as not CAD, then this field must not be filled.
CreditorAgent/Identification (O)
May be optionally provided as a valid SWIFT-BIC code (length 8 or
11) or valid Local clearing code specific to the Beneficiary Bank
Location (length max 35)
CreditorAgent/Name (O)
Must not be provided
CurrencyOfTransfer (M)
Must be provided.
DestinationCountryCode (O)
Only HSBCnet UK supported countries will be allowed. Kindly
refer section 19.6.3. If creditorAccount.schemeName is
UK.OBIE.IBAN, then this field DestinationCountryCode must
match with the first 2 characters of Beneficiary account IBAN. In
addition if creditorAccount.schemeName is
UK.OBIE.SortCodeAccountNumber, then this field
DestinationCountryCode must be GB.
ExchangeRateInformation/ContractIdentification (O)
May be optionally provided as a valid pre-agreed Exchange
Contract number with character length less than or equal to 256
ExchangeRateInformation/ExchangeRate (O)
Must not be provided
ExchangeRateInformation/RateType (O)
ExchangeRateInformation/UnitCurrency (O)
May be optionally provided as value same Debit Account
Currency
ExtendedPurpose (O)
Only HSBCnet UK supported ExtendedPurpose codes will be
allowed. Kindly refer section Optional Fields
InstructedAmount (M)
Amount :- Must not be more than 19 characters including
maximum 3 decimal places. Also, it must not be less than 0.01
Currency :- Must be equal to debit account currency
Purpose (O)
Only HSBCnet UK supported Purpose codes will be allowed.
Kindly refer section Optional Fields
RemittanceInformation/Reference (O)
May be optionally provided. Must be no more than 30 characters
RemittanceInformation/Unstructured(O)
May be optionally provided. Must be no more than 30 characters
ReadRefundAccount (O)
May be optionally provided (Possible values Yes/No).
113
PUBLIC
Must not be provided
Authorisation.AuthorisationType
Risk.DeliveryAddres.Country
Authorisation.CompletionDateTime
Risk.DeliveryAddres.CountrySubDivision[0-2]
ChannelPaymentId
Risk.DeliveryAddres.PostCode
Creditor.PostalAddress.AddressLine[3 and onwards] (Priority
Payment)
Risk.DeliveryAddres.StreetName
Creditor.PostalAddress.AddressLine[4 and onwards] (Priority
Payment & SEPA Credit Transfer, SEPA Instant Credit Transfer)
Risk.DeliveryAddres.TownName
CreditorAccount.SecondaryIdentification
Risk.MerchantCategoryCode
CreditorAgent.Name
Risk.MerchantCustomerIdentification
CreditorAgent.PostalAddress entire Object (any field inside)
Risk.PaymentContextCode
DebtorAccount.SecondaryIdentification
SCASupportData.AppliedAuthenticationApproach
ExchangeRateInformation.exchangeRate
SCASupportData.ReferencePaymentOrderId
Risk.DeliveryAddres.AddressLine[0 -2]
SCASupportData.RequestedSCAExemptionType
Risk.DeliveryAddres.BuldingNumber
SupplementaryData
22.3. Payment Status
For international scheduled payments, a request for a payment status will return one of the following statuses:
22.3.1. HSBC Personal, first direct
➢ InitiationCompletedInitiationFailed
22.3.2. HSBC Business
➢ InitiationCompleted
➢ InitiationPending (when multi-authorisation is required in HSBCs direct channel)
➢ InitiationFailed
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
authorising party. See section -
114
PUBLIC
22.3.3. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Endpoint: POST /international-scheduled-payments
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Final
HSBCnet UK
The instruction has been setup successfully or has
been successfully processed on the due date
200
Interim
HSBCnet UK
The scheduled payment / standing order instruction
has been successfully received but not yet set up
200
Final
HSBCnet UK
Instruction has failed
200
Final
HSBCnet UK
The instruction has been cancelled by the customer
using their online banking channel (only applies to
Scheduled Payments when the future dated
payment is cancelled by the user)
Endpoint: GET/international-scheduled-payments/{InternationalScheduledPaymentId}
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Final
HSBCnet UK
The instruction has been setup successfully or has
been successfully processed on the due date
200
Interim
HSBCnet UK
The scheduled payment / standing order instruction
has been successfully received but not yet set up
200
Final
HSBCnet UK
Instruction has failed
200
Final
HSBCnet UK
The instruction has been cancelled by the customer
using their online banking channel (only applies to
Scheduled Payments when the future dated
payment is cancelled by the user)
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
-
115
PUBLIC
23. International Standing Orders
23.1. Implemented Endpoints
23.1.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts
Global
Money
International-
standing-orders
/international-standing-order-consents
(POST/GET/DELETE)
Y
N
Y
N
International-
standing-orders
POST /international-standing-orders
Y
N
Y
N
International-
standing-orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
Y
N
Y
N
23.1.2. HSBC Business (Not Implemented)
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
International-
standing-orders
/international-standing-order-consents
(POST/GET/DELETE)
N
N
N
N
International-
standing-orders
POST /international-standing-orders
N
N
N
N
International-
standing-orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
N
N
N
N
23.1.3. HSBC Kinetic (Not Implemented)
Resource
Endpoints
Business
Current
Accounts
International-
standing-orders
/international-standing-order-consents
(POST/GET/DELETE)
N
International-
standing-orders
POST /international-standing-orders
N
International-
standing-orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
N
116
PUBLIC
23.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
International-
standing-orders
/international-standing-order-consents
(POST/GET/DELETE)
Y
N
Y
International-
standing-orders
POST /international-standing-orders
Y
N
Y
International-
standing-orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
Y
N
Y
Global Wallet/Working capital debit accounts are NOT permitted via International-standing-order-consents endpoint
23.2. Request Fields
For POST /international-standing-order-consents and POST /international-standing-orders:
23.2.1. HSBC Personal, first direct
Field
Notes
Error Code if invalid
Frequency
See separate Permitted Frequency Values section
400 - UK.OBIE.Field.Invalid
NumberOfPayments
Mutually exclusive with presence of FinalPaymentDateTime; one and
only one must be present
Must be > 0 and
If both FinalPaymentDateTime and NumberOfPayments are not
present in request then the payment will be considered as to be on-
400 - UK.OBIE.Field.Invalid
FirstPaymentDateTime
Execution date must also be a valid working day
Must be < FinalPaymentDateTime, if that field is present
Must be < RecurringPaymentDateTime
It is the TPP's responsibility to align the FirstPaymentDateTime to the
Frequency; for example if it is desired to have the first monthly
payment on 20th June, the TPP must set Frequency =
IntrvlMnthDay:01:20 (Monthly - 20th) and FirstPaymentDateTime =
2019-06-20
Example 1 (correctly aligned):
Frequency = IntrvlMnthDay:01:10 (Monthly - 10th)
FirstPaymentDateTime = 2019-06-10
=> FirstPaymentDateTime = 2019-06-10
If they are misaligned, the system will move the
FirstPaymentDateTime to be the first date after the input
FirstPaymentDateTime that aligns with the Frequency day.
Example 2 (misaligned):
Frequency = IntrvlMnthDay:01:10 (Monthly - 10th)
FirstPaymentDateTime = 2019-06-20
=> FirstPaymentDateTime = 2019-07-10
Example 3 (misaligned):
Frequency = IntrvlMnthDay:01:20 (Monthly - 20th)
FirstPaymentDateTime = 2019-06-10
=> FirstPaymentDateTime = 2019-06-20
Note: the time element has removed from above DateTime examples,
for simplicity.
400 - UK.OBIE.Field.Invalid
RecurringPaymentAmount
Optional
If Present ReurringPaymentAmount = FinalPaymentAmount =
FirstPaymentAmount
400 - UK.OBIE.Field.Invalid
FinalPaymentAmount
Optional
If Present FinalPaymentAmount = ReurringPaymentAmount =
FirstPaymentAmount
400 - UK.OBIE.Field.Invalid
FirstPaymentAmount
Mandatory
400 - UK.OBIE.Field.Invalid
117
PUBLIC
FinalPaymentDateTime
Mutually exclusive with presence of NumberOfPayments; one and
only one must be present
Must be > tomorrow
Must be > FirstPaymentDateTime
If both FinalPaymentDateTime and NumberOfPayments are not
present in request then the payment will be considered as to be on-
400 - UK.OBIE.Field.Invalid
RecurringPaymentDateTime
365 days ahead
Must be > FirstPaymentDateTime
400 - UK.OBIE.Field.Invalid
AuthorisationType
Any or Single
400 - UK.OBIE.Field.Invalid
DebtorAccount/SchemeName
If populated then must be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/SchemeName
Must be UK.OBIE.SortCodeAccountNumber or UK.OBIE.IBAN or
UK.HSBC.LocalAccountNumber (Refer section on CreditorAccount
object below)
(HCA)
or vice versa the value should be UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Field.Invalid
CreditorAccount/Identification
If CreditorAccount/SchemeName =
UK.OBIE.SortCodeAccountNumber then identification =
SortCodeAccountNumber format (i.e. 14 digits)
If CreditorAccount/SchemeName = UK.OBIE.IBAN then identification
= IBAN format
If CreditorAccount/SchemeName = UK.HSBC.LocalAccountNumber
then identification = Local Account Number format of that particular
country
400 - UK.OBIE.Field.Invalid
InstructedAmount/Amount
Must be provided
400 - UK.OBIE.Field.Invalid
InstructedAmount/Currency
This can be the debtor account currency
Or
If instructed amount currency is non equal to debtor account currency
then it has to match currency of transfer
400 - UK.OBIE.Field.Invalid
CurrencyOfTransfer
See above rule related to InstructedAmount/Currency
400 - UK.OBIE.Field.Invalid
DestinationCountryCode
This field must not be populated by TPPs. The International payment
routing logic is driven by CreditorAgent/PostalAddress/Country
400 - UK.OBIE.Field.Invalid
ChargeBearer
Must be one of
BorneByCreditor, BorneByDebtor, Shared
400 - UK.OBIE.Field.Invalid
CreditorAgent/SchemeName
Please refer to International Payments
400 - UK.OBIE.Field.Invalid
CreditorAgent/Identification
Please refer to International Payments
400 - UK.OBIE.Field.Invalid
CreditorAgent/PostalAddress
Please refer to International Payments
400 - UK.OBIE.Field.Invalid
CreditorAccount/Name
Max 35 characters
400 - UK.OBIE.Field.Invalid
ExtendedPurpose
Please refer to International Payments
400 - UK.OBIE.Field.Invalid
SupplementaryData.PurposeOfPayment
Please refer to International Payments
400 - UK.OBIE.Field.Invalid
118
PUBLIC
23.2.2. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Field
Notes
Error Code if
invalid
Initiation/Frequency (M)
Must be provided as per any of the below supported
enumeration values only:
Mon>
week starts from Mon>
y: IntrvlMnthDay:01:<day of the month>
month>
-01
Initiation/NumberOfPayments (O)
-Account
format between 2 and 99.
DebtorAccount/SchemeName (O)
May be optionally provided as per any of the below supported
enumeration values only:
DebtorAccount/Identification (O)
May be optionally provided as a valid IBAN, BBAN,
SortCodeAccountNumber having character length less than or
equal to 35
ChargeBearer (O)
May be optionally provided as per any of the below supported
enumeration values only:
(1) If Debit Account Country is any passported country except UK
s
any passported country except UK, then this ChargeBearer may
(2) If Debit Account Country is DE, and Beneficiary Bank Location
this ChargeBearer may be optionally provided as
(3) If Debit Account Country is any passported country except UK
.
CreditorAccount/Name (M)
Must be provided
Creditor/Name (O)
May be optionally provided as a value same as
CreditorAccount/Name only
CreditorAccount/SchemeName (M)
Must be provided as per any of the below supported
enumeration values only:
CreditorAccount/Identification (M)
Must be provided in SWIFT character set having character length
less than or equal to 34,
(1) Debtor and Creditor account locations should not be the
same, and should be amongst the UK and EU countries. If the
debit and credit location both are UK, then currency must not be
GBP.
(2) If the CreditorAccount/SchemeName is mentioned as
UK.OBIE.SortCodeAccountNumber, then this
CreditorAccount/Identification must be of numeric and of length
14 (comprising first 6 digits as Sort Code, and last 8 digits as
Account number)
account, then CreditorAccount/Identification must be a valid
Czech Republic IBAN or BBAN
then this CreditorAccount/Identification must be a valid Poland
IBAN or BBAN
119
PUBLIC
CreditorPostalAddress/AddressLine
(1) May be optionally provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array fields
of AddressLine [0-
then this field must be provided in SWIFT character set having
character length less than or equal to 35 in atmost 3 array fields
of AddressLine [0-2]
-
as CAD, then this field must be provided in SWIFT character set
having character length less than or equal to 35 in atmost 3 array
fields of AddressLine [0-2]
Note:- -
CurrencyOfTransfer as not CAD, then this field must not be filled.
CreditorAgent/Identification (O)
May be optionally provided as a valid SWIFT-BIC code (length 8
or 11) or valid Local clearing code specific to the Beneficiary
Bank Location (length max 35)
CreditorAgent/Name (O)
Must not be provided
DestinationCountryCode (O)
Only HSBCnet UK supported countries will be allowed. Kindly
refer section 19.6.3. If creditorAccount.schemeName is
UK.OBIE.IBAN, then this field DestinationCountryCode must
match with the first 2 characters of Beneficiary account IBAN. In
addition if creditorAccount.schemeName is
UK.OBIE.SortCodeAccountNumber, then this field
DestinationCountryCode must be GB.
ExchangeRateInformation/ContractIdentification (O)
May be optionally provided as a valid pre-agreed Exchange
Contract number with character length less than or equal to 256
ExchangeRateInformation/ExchangeRate (O)
Must not be provided
ExchangeRateInformation/RateType (O)
ExchangeRateInformation/UnitCurrency (O)
May be optionally provided as value same Debit Account
Currency
ExtendedPurpose (O)
Only HSBCnet UK supported ExtendedPurpose codes will be
allowed.
InstructedAmount (M)
Amount: Must not be more than 19 characters including
maximum 3 decimal places. Also, it must not be less than 0.01
Currency: Must be equal to debit account currency
Purpose (O)
Only HSBCnet UK supported Purpose codes will be allowed.
Reference (O)
May be optionally provided
ReadRefundAccount (O)
May be optionally provided (Possible values Yes/No).
For Standing orders, only the acceptance of the flag is supported.
Actual Refund for standing order has not been supported.
Must not be provided
Authorisation.AuthorisationType
Risk.DeliveryAddres.Country
Authorisation.CompletionDateTime
Risk.DeliveryAddres.CountrySubDivision[0-2]
ChannelPaymentId
Risk.DeliveryAddres.PostCode
Creditor.PostalAddress.AddressLine[3 and onwards] (Priority
Payment)
Risk.DeliveryAddres.StreetName
CreditorAccount.SecondaryIdentification
Risk.DeliveryAddres.TownName
CreditorAgent.Name
Risk.MerchantCategoryCode
CreditorAgent.PostalAddress entire Object (any field inside)
Risk.MerchantCustomerIdentification
DebtorAccount.SecondaryIdentification
Risk.PaymentContextCode
ExchangeRateInformation.exchangeRate
SCASupportData.AppliedAuthenticationApproach
Purpose
SCASupportData.ReferencePaymentOrderId
Risk.DeliveryAddres.AddressLine[0 -2]
SCASupportData.RequestedSCAExemptionType
Risk.DeliveryAddres.BuldingNumber
SupplementaryData
120
PUBLIC
23.3. Permitted Frequency Values
The permitted frequencies that are allowed by the online channels are as follows:
➢ Weekly
➢ Monthly
➢ 4 weekly
➢ Quarterly
➢ Annually
➢ Last working day of the month
The corresponding frequency patterns as per the OBIE schema are as below:
Field - Frequency
Description
IntrvlWkDay:01:XX
Same day every week (Weekly) where XX is 01-05
representing Monday to Friday
IntrvlMnthDay:01:XX
Same day on every month (Monthly) where XX is 01-31
representing date of the month
IntrvlWkDay:04:XX
Same day on every 4 weeks where XX is 01-05 representing
Monday to Friday
IntrvlMnthDay:03:XX
Same day every 3 months where XX is 01-31 representing
date of the month
IntrvlMnthDay:12:XX
Same day every year where XX is 01-31 representing date of
the month
IntrvlMnthDay:01:31
IntrvlMnthDay:01:30
IntrvlMnthDay:01:29
IntrvlMnthDay:01:28
Monthly and Adhere to Month End
23.4. Payment Status
For international standing order payments, a request for a payment status will return one of the following statuses:
➢ InitiationCompleted (all brands except HSBCnet UK)
➢ InitiationFailed (all brands except HSBCnet UK)
➢ InitiationPending (only HSBCnet UK)
121
PUBLIC
24. File Payments
24.1. Implemented Endpoints
24.1.1. HSBC Personal (Not implemented)
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Foreign
Currency
Accounts
Global
Money
file-payments-consent
POST /file-payment-consents
N
N
N
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
N
N
N
N
file-payments-consent
GET /file-payment-consents/{ConsentId}
N
N
N
N
file-payments
POST /file-payments
N
N
N
N
file-payments
GET /file-payments/{FilePaymentId}
N
N
N
N
file-payments
GET /file-payments/{FilePaymentId}/payment-
details ^
N
N
N
N
file-payments
GET /file-payments/{FilePaymentId}/report-
file
N
N
N
N
24.1.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
file-payments-consent
POST /file-payment-consents
Y
N
Y
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
Y
N
Y
N
file-payments-consent
GET /file-payment-consents/{ConsentId}
Y
N
Y
N
file-payments
POST /file-payments
Y
N
Y
N
file-payments
GET /file-payments/{FilePaymentId}
Y
N
Y
N
file-payments
GET /file-payments/{FilePaymentId}/payment-
details ^
Y
N
Y
N
file-payments
GET /file-payments/{FilePaymentId}/report-
file
N
N
N
N
24.1.3. HSBC Kinetic (Not Implemented)
Resource
Endpoints
Business
Current
Accounts
file-payments-consent
POST /file-payment-consents
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
N
122
PUBLIC
file-payments-consent
GET /file-payment-consents/{ConsentId}
N
file-payments
POST /file-payments
N
file-payments
GET /file-payments/{FilePaymentId}
N
file-payments
GET /file-payments/{FilePaymentId}/payment-
details ^
N
file-payments
GET /file-payments/{FilePaymentId}/report-file
N
24.1.4. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
file-payments-consent
POST /file-payment-consents
Y
N
N
file-payments-consent
POST /file-payment-consents/{ConsentId}/file
Y
N
N
file-payments-consent
GET /file-payment-consents/{ConsentId}
Y
N
N
file-payments
POST /file-payments
Y
N
N
file-payments
GET /file-payments/{FilePaymentId}
Y
N
N
file-payments
GET /file-payments/{FilePaymentId}/payment-
details ^
N
N
N
file-payments
GET /file-payments/{FilePaymentId}/report-file
N
N
N
24.2. Request Fields and Example File
24.2.1. HSBC Business
HSBC Business will accept payments via the file-payment endpoint for subsequent processing via BACS or Faster Payments (FPS) as
designated in the LocalInstrument field.
For POST /file-payment-consents:
Field
Notes
Error Code if invalid
FileType
FileType should be equal to UK.OBIE.pain.001.001.08
400 - UK.OBIE.Field.Invalid
FileHash
A base64 encoding of a SHA256 hash of the file to be uploaded
FileReference
For BACS and FPS:
FileReference is optional, cannot be more than 18 characters, must be
Alphanumeric (no special characters) and must match the reference (per
the below mapping) in the File
(Whilst it is possible for the PSU to add the reference when they are in the
HSBC domain, it is recommended that it is provided by the TPP to ensure
a seamless customer journey)
400 - UK.OBIE.Field.Invalid
ControlSum
Total of all individual amounts included in the File. We would reject any
instructions where this does not match up to the sum of all the instructed
amounts
400 - UK.OBIE.Field.Invalid
123
PUBLIC
LocalInstrument
If LocalInstrument contains UK.OBIE.BACS we will consider the payment
scheme as BACS.
If LocalInstrument contains UK.OBIE.FPS we will consider the payment
scheme as FPS.
If LocalInstrument is empty, we will consider the payment scheme as
BACS.
For all other values the request will be rejected.
400 - UK.OBIE.Field.Invalid
NumberOfTransactions
NumberOfTransactions should be between 1- 25 - Maximum allowed
Number of Transactions in a file is 25. If this number is 0 or it exceeds 25,
the request will be rejected.
400 - UK.OBIE.Field.Invalid
RequestedExecutionDateTime
For BACS:
The RequestedExecutionDateTime should be between Date of Request + 2
working days to Date of Request + 45 days. If the
RequestedExecutionDateTime does not fall in that range or if it falls on a
weekend or bank holiday or past dated, the request will be rejected.
Whilst it is possible for the PSU to add the RequestedExecutionDate when
they are in the HSBC domain, it is recommended that it is provided by the
TPP (to ensure a seamless customer journey).
For FPS:
If RequestedExecutionDateTime is same as Date of Request then we will
consider it as Immediate FPS
If RequestedExecutionDateTime is between Date of Request + 45 days
(>Date of Request <= 45 days), then it will be considered as Future Dated
FPS.
If the RequestedExecutionDateTime does not fall in that range, or is not
provided by the TPP, the request will be rejected
400 - UK.OBIE.Field.Invalid
DebtorAccount
DebtorAccount should be not be same as any of the creditorAccounts.
SchemeName we currently support is UK.OBIE.SortCodeAccountNumber.
DebtorAccount.identification should only be numeric and MUST be 14
number long(6 digit Sort code and 8 digits account number)
400 - UK.OBIE.Field.Invalid
RemittanceInformation
We advise you not to populate this field. If populated we would reject the
instruction
400 - UK.OBIE.Field.Invalid
authorisationType
HSBC Business Any or Single
(see section Multi-Authorisation)
For POST /file-payment-consents/{ConsentId}/file and POST/file-payments:
For the best experience using the File Payment endpoint we advise you keep the information in your metadata and the File consistent
this will ensure the best chances of a successful journey.
The file must contain a reference for each individual transaction. If this is not the case the request will be rejected.
Example XML We advise that you use the below file as a guide for your payments
<?xml version="1.0" encoding="UTF-8" ?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.08" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<CstmrCdtTrfInitn>
<GrpHdr>
<MsgId>ABC120928CCT001</MsgId>
<NbOfTxs>3</NbOfTxs>
<CtrlSum>0.03</CtrlSum>
</GrpHdr>
<PmtInf>
<ReqdExctnDt>
<Dt>2020-11-17</Dt>
</ReqdExctnDt>
<DbtrAcct>
<Id>
<Othr>
<Id>40041060993603</Id>
</Othr>
</Id>
</DbtrAcct>
124
PUBLIC
<CdtTrfTxInf>
<Amt>
<InstdAmt Ccy="GBP">0.01</InstdAmt>
</Amt>
<Cdtr>
<Nm>DEF Electronics</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<Othr>
<Id>23683707994125</Id>
</Othr>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>CINV</Ustrd>
</RmtInf>
</CdtTrfTxInf>
<CdtTrfTxInf>
<Amt>
<InstdAmt Ccy="GBP">0.01</InstdAmt>
</Amt>
<Cdtr>
<Nm>GHI Semiconductors</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<Othr>
<Id>42000089561223</Id>
</Othr>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>CINV</Ustrd>
</RmtInf>
</CdtTrfTxInf>
<CdtTrfTxInf>
<Amt>
<InstdAmt Ccy="GBP">0.01</InstdAmt>
</Amt>
<Cdtr>
<Nm>ABC Corporation</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<Othr>
<Id>42000089561223</Id>
</Othr>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>CINV</Ustrd>
</RmtInf>
</CdtTrfTxInf>
</PmtInf>
</CstmrCdtTrfInitn>
</Document>
When using the above file please note the below table too as it shows how the file will be used in fulfilling the BACS payment
consent.
As such, please use the below mapping table in addition to the above validations to prevent POST rejections.
XML Path
Validations
Document/CstmrCdtTrfInitn/GrpHdr/CtrlSum
Mandatory,Decimal and restriction to not pass more than 2 decimal places
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf
Mandatory 1 to 25
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Cdtr/Nm
Mandatory String with 1-18
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id/Othr/Id
Mandatory with [\d]{14}
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt/InstdAmt
Mandatory, Decimal and restriction to not pass more than 2 decimal places
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt/InstdAmt@Ccy
Mandatory, Enum with only GBP
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/RmtInf/Ustrd
Mandatory with maxOccurence as 1, length restriction 1-18, lowercase and
uppercase letters and numbers are allowed only (a-z, A-Z, 0-9)
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id/Othr/Id
Mandatory, string and restriction [\d]{14}
Document/CstmrCdtTrfInitn/GrpHdr/MsgId
Optional,String,1-18
Document/CstmrCdtTrfInitn/GrpHdr/NbOfTxs
Mandatory- unsignedByte ,1 to 25,
Document/CstmrCdtTrfInitn/PmtInf/ReqdExctnDt/Dt
Mandatory ,Date
Document
Mandatory
Document/CstmrCdtTrfInitn
Mandatory
Document/CstmrCdtTrfInitn/GrpHdr
Mandatory
Document/CstmrCdtTrfInitn/PmtInf
Mandatory,1 and 1 only
Document/CstmrCdtTrfInitn/PmtInf/ReqdExctnDt
Optional Dt only
125
PUBLIC
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct
Optional
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id/Other
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Cdtr
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id/Other
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/RmtInf
Mandatory
Example XML We advise that you use the below file as a guide for your payments
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.08" xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance">
<CstmrCdtTrfInitn>
<GrpHdr>
<NbOfTxs>2</NbOfTxs>
<CtrlSum>0.02</CtrlSum>
</GrpHdr>
<PmtInf>
<ReqdExctnDt>
<Dt>2021-08-04</Dt>
</ReqdExctnDt>
<CdtTrfTxInf>
<Amt>
<InstdAmt Ccy="GBP">0.01</InstdAmt>
</Amt>
<Cdtr>
<Nm>ATBEN5</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<Othr>
<Id>20045083651142</Id>
</Othr>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>ref2</Ustrd>
</RmtInf>
</CdtTrfTxInf>
</PmtInf>
<PmtInf>
<ReqdExctnDt>
<Dt>2021-08-04</Dt>
</ReqdExctnDt>
<CdtTrfTxInf>
<Amt>
<InstdAmt Ccy="GBP">0.01</InstdAmt>
</Amt>
126
PUBLIC
<Cdtr>
<Nm>ATBEN5</Nm>
</Cdtr>
<CdtrAcct>
<Id>
<Othr>
<Id>20045083651142</Id>
</Othr>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>ref1</Ustrd>
</RmtInf>
</CdtTrfTxInf>
</PmtInf>
</CstmrCdtTrfInitn>
</Document>
When using the above file please note the below table too as it shows how the file will be used in fulfilling the FPS payment
consent.
As such, please use the below mapping table in addition to the above validations to prevent POST rejections.
XML Path
Validations
Document/CstmrCdtTrfInitn/GrpHdr/CtrlSum
Mandatory,Decimal and restriction to not pass more than 2 decimal places
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf
Mandatory 1 to 25
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Cdtr/Nm
Mandatory String with 1-18
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id/Othr/Id
Mandatory with [\d]{14}
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt/InstdAmt
Mandatory, Decimal and restriction to not pass more than 2 decimal places
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt/InstdAmt@Ccy
Mandatory, Enum with only GBP
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/RmtInf/Ustrd
Mandatory with maxOccurence as 1,length restriction 1-18
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id/Othr/Id
Mandatory, string and restriction [\d]{14}
Document/CstmrCdtTrfInitn/GrpHdr/MsgId
Optional,String,1-18
Document/CstmrCdtTrfInitn/GrpHdr/NbOfTxs
Mandatory- unsignedByte ,1 to 25,
Document/CstmrCdtTrfInitn/PmtInf/ReqdExctnDt/Dt
Mandatory ,Date
Document
Mandatory
Document/CstmrCdtTrfInitn
Mandatory
Document/CstmrCdtTrfInitn/GrpHdr
Mandatory
Document/CstmrCdtTrfInitn/PmtInf
Mandatory,1 and 1 only
Document/CstmrCdtTrfInitn/PmtInf/ReqdExctnDt
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct
Optional
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id/Other
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Cdtr
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id/Othr
Mandatory
Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/RmtInf
Mandatory
127
PUBLIC
24.2.2. HSBC Corporate UK and HSBC Innovation Banking HSBCnet
HSBCnet will accept payments via the file-payment endpoint for subsequent processing via appropriate payments processing system.
Instructions can only be submitted in XMLV3 format, and the file size must be <6MB.
For POST /file-payment-consents:
Field
Notes
Error Code if invalid
FileType
FileType should be equal to UK.OBIE.pain.001.001.03
FileHash
A base64 encoding of a SHA256 hash of the file to be uploaded
SupplementaryData/AuthorisationLevel
Mandatory field assuming one of the following values -
-Pre Authorised
-File Level With Summary
-File Level With Details
String value that describes the Authorisation Level details for the
payment
SupplementaryData/ConnectProfileId
Mandatory string value containing the Profile Identification Code
(PIC)
This is shared with the client when they are onboarded to the file
upload service and will be emailed to them following initial setup.
TPP must ask the user to provide their PIC and pass it onto HSBC via
API request.
SupplementaryData/FileName
Mandatory String value describing the File Name.
should be 255 characters.
For POST /file-payment-consents/{ConsentId}/file and POST/file-payments: For the best experience using the File Payment endpoint
we advise you keep the information in your metadata and the File consistent this will ensure the best chances of a successful
journey.
Example XML We advise that you use the below file as a guide for your payments
<?xml version="1.0" encoding="utf-8"?>
<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
<CstmrCdtTrfInitn>
<GrpHdr>
<MsgId>Unique MSG Reference</MsgId>
<CreDtTm>2021-10-15T20:25:37</CreDtTm>
<NbOfTxs>2</NbOfTxs>
<CtrlSum>0.02</CtrlSum>
<InitgPty>
<Nm>Customer Name</Nm>
<Id>
<OrgId>
<Othr>
<Id>ClientPICCode</Id>
</Othr>
</OrgId>
</Id>
</InitgPty>
</GrpHdr>
<PmtInf>
<PmtInfId>Debit reference</PmtInfId>
<PmtMtd>TRF</PmtMtd>
<NbOfTxs>2</NbOfTxs>
<CtrlSum>0.02</CtrlSum>
<PmtTpInf>
<SvcLvl>
<Cd>4 letter code defining Payment service</Cd>
128
PUBLIC
</SvcLvl>
</PmtTpInf>
<ReqdExctnDt>2021-10-15</ReqdExctnDt>
<Dbtr>
<Nm>Customer Name</Nm>
<PstlAdr>
<StrtNm>Street Name</StrtNm>
<BldgNb>Building Number</BldgNb>
<PstCd>Post Code</PstCd>
<TwnNm>Town Name</TwnNm>
<CtrySubDvsn>County</CtrySubDvsn>
<Ctry>GB</Ctry>
</PstlAdr>
<CtryOfRes>GB</CtryOfRes>
</Dbtr>
<DbtrAcct>
<Id>
<IBAN>Debit IBAN Account</IBAN>
</Id>
<Ccy>GBP</Ccy>
</DbtrAcct>
<DbtrAgt>
<FinInstnId>
<BIC>DB BIC Code</BIC>
<PstlAdr>
<Ctry>GB</Ctry>
</PstlAdr>
</FinInstnId>
</DbtrAgt>
<ChrgBr>4 letter code defining where charge should be allocated</ChrgBr>
<CdtTrfTxInf>
<PmtId>
<InstrId>Unique Instruction Reference</InstrId>
<EndToEndId>Unique E2E Reference</EndToEndId>
</PmtId>
<Amt>
<InstdAmt Ccy="GBP">0.01</InstdAmt>
</Amt>
<CdtrAgt>
<FinInstnId>
<BIC>Credit BIC code</BIC>
<PstlAdr>
<Ctry>GB</Ctry>
</PstlAdr>
</FinInstnId>
</CdtrAgt>
<Cdtr>
<Nm>PVT Profile</Nm>
<PstlAdr>
<StrtNm>ABC AB</StrtNm>
<PstCd>31212</PstCd>
<TwnNm>ABC</TwnNm>
<Ctry>GB</Ctry>
</PstlAdr>
</Cdtr>
<CdtrAcct>
<Id>
<IBAN>Credit IBAN Accoun</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Payment Reference</Ustrd>
</RmtInf>
</CdtTrfTxInf>
<CdtTrfTxInf>
<PmtId>
<InstrId>Unique Instruction Reference</InstrId>
<EndToEndId>Unique E2E Reference</EndToEndId>
</PmtId>
<Amt>
<InstdAmt Ccy="GBP">0.01</InstdAmt>
</Amt>
<CdtrAgt>
<FinInstnId>
<BIC>Credit BIC code</BIC>
<PstlAdr>
<Ctry>GB</Ctry>
</PstlAdr>
</FinInstnId>
</CdtrAgt>
<Cdtr>
<Nm>Test Profile</Nm>
<PstlAdr>
<StrtNm>ABC AB</StrtNm>
<PstCd>31212</PstCd>
<TwnNm>ABC</TwnNm>
<Ctry>GB</Ctry>
</PstlAdr>
</Cdtr>
129
PUBLIC
<CdtrAcct>
<Id>
<IBAN>Credit IBAN Accoun</IBAN>
</Id>
</CdtrAcct>
<RmtInf>
<Ustrd>Payment Reference</Ustrd>
</RmtInf>
</CdtTrfTxInf>
</PmtInf>
</CstmrCdtTrfInitn>
</Document>
When using the above file please note the below table too as it shows how the file will be used in fulfilling the payment consent.
As such, please use the below mapping table in addition to the above validations to prevent POST rejections.
XML Tag
Mandatory
Type / Code
Path
<GrpHdr>
Yes
/Document/CstmrCdtTrfInitn/GrpHdr
<MsgId>
Yes
text{1,35}
/Document/CstmrCdtTrfInitn/GrpHdr/MsgId
<CreDtTm>
Yes
dateTime
/Document/CstmrCdtTrfInitn/GrpHdr/CreDtTm
<NbOfTxs>
No
text [0-9]{1,15}
/Document/CstmrCdtTrfInitn/GrpHdr/NbOfTxs
<InitgPty>
Yes
/Document/CstmrCdtTrfInitn/GrpHdr/InitgPty
<OrgId>
Yes
/Document/CstmrCdtTrfInitn/GrpHdr/InitgPty/Id/OrgId
<Id>
Yes
text{1,35}
/Document/CstmrCdtTrfInitn/GrpHdr/InitgPty/Id/OrgId/Othr/Id
<PmtInfId>
Yes
text{1,35}
/Document/CstmrCdtTrfInitn/PmtInf/PmtInfId
<NbOfTxs>
Yes
text [0-9]{1,15}
/Document/CstmrCdtTrfInitn/PmtInf/NbOfTxs
<PmtMtd>
Yes
text
/Document/CstmrCdtTrfInitn/PmtInf/PmtMtd
<Cd>
Yes
text{1,4}
/Document/CstmrCdtTrfInitn/PmtInf/PmtTpInf/SvcLvl/Cd
<ReqdExctnDt>
Yes
date
/Document/CstmrCdtTrfInitn/PmtInf/ReqdExctnDt
<Dbtr>
Yes
/Document/CstmrCdtTrfInitn/PmtInf/Dbtr
<DbtrAcct>
Yes
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct
<Id>
Yes
Choice
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id
<IBAN>
Yes
text [A-Z]{2,2}[0-9]{2,2}[a-zA-
Z0-9]{1,30}
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAcct/Id/IBAN
<DbtrAgt>
Yes
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAgt
<FinInstnId>
Yes
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAgt/FinInstnId
<BIC>
Yes
text [A-Z]{6,6}[A-Z2-9][A-NP-Z0-
9]([A-Z0-9]{3,3}){0,1}
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAgt/FinInstnId/BIC
<Id>
Yes
Choice
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAgtAcct/Id
<IBAN>
Yes
text [A-Z]{2,2}[0-9]{2,2}[a-zA-
Z0-9]{1,30}
/Document/CstmrCdtTrfInitn/PmtInf/DbtrAgtAcct/Id/IBAN
<ChrgBr>
Yes
text{1,4}
/Document/CstmrCdtTrfInitn/PmtInf/ChrgBr
<PmtId>
Yes
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/PmtId
<InstrId>
Yes
text{1,35}
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/PmtId/InstrId
<EndToEndId>
Yes
text{1,35}
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/PmtId/EndToEndId
<Amt>
Yes
Choice
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt
<InstdAmt>
Yes
0 <= decimal
td = 18
fd = 5
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Amt/InstdAmt
<FinInstnId>
Yes
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAgt/FinInstnId
<BIC>
Yes
text [A-Z]{6,6}[A-Z2-9][A-NP-Z0-
9]([A-Z0-9]{3,3}){0,1}
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAgt/FinInstnId/BIC
130
PUBLIC
<Nm>
Yes
text{1,140}
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Cdtr/Nm
<PstlAdr>
Yes
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/Cdtr/PstlAdr
<Id>
Yes
Choice
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id
<IBAN>
Yes
text [A-Z]{2,2}[0-9]{2,2}[a-zA-
Z0-9]{1,30}
/Document/CstmrCdtTrfInitn/PmtInf/CdtTrfTxInf/CdtrAcct/Id/IBAN
To define the execution instrument please follow the below instructions to populate the XML file.
Debtor
Acct
Country
<PmtMtd>
<SvcLvl>
<Cd>
Rule to identify transaction type
Payment Type
GB
TRF or TRA
URNS
Faster Payments
GB
TRF or TRA
URGP, PRPT,
SDVA
<SvcLvl><Cd> is either of "URGP" ,"PRPT", "SDVA"
AND Payment amount ccy is GBP
AND Debit Account Country and Beneficiary Account Country are
same
CHAPS Payments
GB
TRF or TRA
URGP, PRPT,
SDVA
<SvcLvl><Cd> is either of "URGP" ,"PRPT", "SDVA"
AND Payment amount ccy is not GBP
Cross border payments
GB
TRF or TRA
URGP, PRPT,
SDVA
<SvcLvl><Cd> is either of "URGP" ,"PRPT", "SDVA"
AND Payment amount ccy is GBP
AND Debit Account Country and Beneficiary Account Country are
different
Cross border payments
GB
TRF or TRA
NURG
<SvcLvl><Cd> is "NURG"
BACS Payments
GB
DD
NURG
<SvcLvl><Cd> is either of "NURG"
BACS DDs
GB
DD
NURG
<SvcLvl><Cd> is either of "NURG"
AND <LclInstrm><Prtry> is "0N" or " 0C" OR "0S"
BACS DDs
24.3. Payment Status
24.3.1. HSBC Business
Endpoint: GET /file-payments/{FilePaymentId}
Status
Instrument
Status Type
Notes
InitiationPending
BACS and FPS
Interim
The file payment instruction has been successfully
received but not yet set-up (i.e. multi-authorisation is
required or the payments are future-dated)
131
PUBLIC
InitiationCompleted
BACS and FPS
Final
The file payment has been set up successfully
InitiationFailed
BACS and FPS
Final
For BACS this will be the case if one or more of the
payments has been rejected downstream. For FPS this
will only be the case if all payments have been rejected
downstream
Endpoint: GET /file-payments/{FilePaymentId}/payment-details
Status
Instrument
Status
Type
Notes
AcceptedSettlementInProcess
FPS
Interim
Payment initiation has been accepted for execution.
Debit and credit have not been posted
Pending
FPS
Interim
When further authorisation is required (in HSBC
Business direct channel)
AcceptedCreditSettlementCompleted
FPS
Final
Payment request has been processed, i.e., debit and
credit have been posted successfully
AcceptedTechnicalValidation
FPS
Interim
For future-dated payments only, payment request
has been fully authorised. Debit and credit have not
been posted
Rejected
FPS
Final
Payment request is rejected, no debit or credit
posted
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
-
24.3.2. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet UK
Endpoint: POST /file-payments
Status
Status Type
Notes
InitiationPending
Interim
The file payment instruction has been successfully received
but not yet set-up.
Endpoint: GET /file-payments/{FilePaymentId}
Status
Status Type
Notes
InitiationPending
Interim
The file payment instruction has been successfully received
but not yet set-up.
InitiationCompleted
Final
The file payment has been set up successfully
InitiationFailed
Final
The file payment has been rejected by downstream while
processing.
For HSBC Business and HSBC Corporate (HSBCnet), other statuses are applicable if a payment requires authorisation by an
authorising party. See section -
132
PUBLIC
25. Major Beneficiaries
25.1. Paying a Major Beneficiary
25.1.1. HSBC Personal, first direct
When making a payment to a major beneficiary PISPs will need to provide the a) Major Beneficiary name, b) Sort code and account
number and c) Payment reference.
Important information
➢ Sort code + account number should match with the BACS list of major beneficiaries or the payment will be rejected.
➢ Beneficiary name should match with BACS list of major beneficiaries or the payment will be rejected.
➢ In case of existing beneficiary, payment reference should match with the existing record or the payment will be rejected.
➢ Payments to a major beneficiary when paying a credit card the reference must contain at least 4 numeric digits.
➢ Payments to major beneficiaries where the reference has less than four digits can only be made through the App-to-App
redirection journey. If these payments are submitted through the online journey they will be rejected.
➢ For payments to charities, unless there is a specific reference, the last four digits of the account number should be used to
populate the reference field.
25.1.2. HSBC Business
Beneficiaries can be identified by their account number. However, sometimes the account number is not available or unique. That is
the case with certain major beneficiaries - large companies (sometimes referred to as Verified Organisations) whose bank details are
protected or replicated for several purposes. For example, some utilities companies, government institutions, etc.
These major beneficiaries are selected by the user through a dedicated search facility, through which the beneficiary can be identified.
In these cases, we will not necessarily have the beneficiary account details and will use the beneficiary ID previously provided.
Important information
➢ All other major beneficiaries -that are not included in the dedicated search list will be treated as a minor beneficiary.
➢ For other major beneficiaries, we will look up the creditor details against the major beneficiary list. Then we will surface a
list of possible matches to the customer to choose the right beneficiary on screen.
➢ We will provide the list of possible matches both on the existing beneficiary list and the major beneficiary list.
➢ Please note that when attempting to make a payment to certain major beneficiaries (e.g. credit card companies), your
reference must be numeric otherwise you run the risk of the payment being rejected.
➢ Payments to a major beneficiary when paying a credit card the reference must contain at least 4 numeric digits.
25.1.3. HSBC Kinetic
HSBC Kinetic support payments to all major beneficiaries via App-to-App.
133
PUBLIC
26. Multi-Authorisation
26.1. Implemented Endpoints
26.1.1. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-payments
POST /domestic-payments
Y
Y
Y
N
Domestic-payments
GET /domestic-payments/{DomesticPaymentId}
Y
Y
Y
N
Domestic-scheduled-
payments
POST /domestic-scheduled-payments
Y
Y
Y
N
Domestic-scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
Y
N
Domestic-standing-orders
POST /domestic-standing-orders
Y
N
Y
N
Domestic-standing-orders
GET /domestic-standing-
orders/{DomesticStandingOrderId}
Y
N
Y
N
International-payments
POST /international-payments
Y
N
N
Y
International-payments
GET /international-payments/{InternationalPaymentId}
Y
N
N
Y
International-scheduled-
payments
POST /international-scheduled-payments
Y
N
N
Y
International-scheduled-
payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
N
Y
International-standing-
orders
POST /international-standing-orders
N
N
N
N
International-standing-
orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
N
N
N
N
file-payments
POST /file-payments
Y
N
Y
N
file-payments
GET /file-payments/{FilePaymentId}
Y
N
Y
N
26.1.2. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Business
Current
Accounts
Deposit
Accounts
Foreign
Currency
Accounts
Domestic-payments
POST /domestic-payments
Y
Y
N
Domestic-payments
GET /domestic-payments/{DomesticPaymentId}
Y
Y
N
Domestic-scheduled-
payments
POST /domestic-scheduled-payments
Y
Y
N
Domestic-scheduled-
payments
GET /domestic-scheduled-
payments/{DomesticScheduledPaymentId}
Y
Y
N
Domestic-standing-orders
POST /domestic-standing-orders
Y
Y
N
Domestic-standing-orders
GET /domestic-standing-orders/{DomesticStandingOrderId}
Y
Y
N
International-payments
POST /international-payments
Y
N
Y
International-payments
GET /international-payments/{InternationalPaymentId}
Y
N
Y
134
PUBLIC
International-scheduled-
payments
POST /international-scheduled-payments
Y
N
Y
International-scheduled-
payments
GET /international-scheduled-
payments/{InternationalScheduledPaymentId}
Y
N
Y
International-standing-orders
POST /international-standing-orders
Y
N
Y
International-standing-orders
GET /international-standing-
orders/{InternationalStandingOrderPaymentId}
Y
N
Y
file-payments
POST /file-payments
Y
N
N
file-payments
GET /file-payments/{FilePaymentId}
Y
N
N
➢ multiAuthorisation/numberRequired & multiAuthorisation/numberReceived fields will not be formatted in the response since
these are not available at HSBCnet UK.
➢ Multi Authorisation response for POST /international-standing-orders & GET /international-standing-
orders/{InternationalStandingOrderPaymentId} will not be formatted in the response.
➢
formatted.
26.2. TPP Authorisation Type
It is essential that any TPP initiating payments through Business Banking indicates their requirement in the AuthorisationType field. In
-authorisation is
supported (AuthorisationType = Any). Failure to indicate Authorisation Type may result in failed payments if the TPP does not support
multi-authorisation.
26.3. HSBC Business Multi-Authorisation
Payment limits for individual users are defined at HSBC. If a user initiates a payment above their limit it will require additional
authorisation by another user with a sufficient limit at a later time. The first user will be advised that this additional authorisation is
rocessed
by HSBC.
If dual control is enabled and if the user initiates a payment within their limit it will require one additional authorisation by a different
user with sufficient limits. If the user initiates a payment above their limits it will require two additional authorisation by two different
users with sufficient limits. The requestor of the payment will be advised that additional authorisations are required which is carried
If dual control is enabled and if the user requested to setup a Standing Order and the amount indicated by this user is within their
limits it will require one additional authorisation by a different user with sufficient limits. The requestor will be advised that additional
135
PUBLIC
26.4. Multi-Authorisation Object Status
For payments that require further authorisation, a request for a multi-authorisation status will return one of the following statuses:
➢ AwaitingFurtherAuthorisation:
▪ When a user has initiated a payment above their payment limit and that payment has yet to be authorized by
▪ When dual control is enabled and a user has initiated a payment or set up a standing order
➢ Rejected:
▪ When a user has initiated a payment above their payment limit and that payment has been rejected by a user
▪ When dual control is enabled and a payment or standing order has been rejected by a subsequent authoriser
For the avoidance of doubts this refers to the MultiAuthorisation object in the payment-order consent, and not to Payment Status
Object.
26.5. Refund Account Details for Multi-Authorisation
Payments
For processing of refunds for multi-authorised payments, TPPs should consider the below:
➢ Refund account details will not be shared with the PISP as part of the response to the payment fulfillment call by the PISP.
fully authorised.
➢ The refund account details are ready to be shared only after the payment/standing order has been fully authorised (within
the direct channel).
➢ In order to receive the refund account details, the PISP will have to make a call to GET/<payment-type>/{payment-ID}.
➢
➢ Based on when the payment has been fully authorised in the direct channel, the TPP may have to make multiple calls to
GET/<payment-type>/{payment-ID} to receive the refund account details.
136
PUBLIC
Confirmation of Funds Summary
137
PUBLIC
27. Confirmation of Funds Summary
27.1. Implemented Endpoints
27.1.1. HSBC Personal, first direct, M&S Bank
Resource
Endpoints
Personal
Current
Accounts
Savings
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Money
Confirmation-of-
funds
POST/funds-confirmation-consents
Y
Y
Y
Y
Y
Confirmation-of-
funds
DELETE/funds-confirmation-
consents/{ConsentID}
Y
Y
Y
Y
Y
Confirmation-of-
funds
GET/funds-confirmation-consents/{ConsentID}
Y
Y
Y
Y
Y
Confirmation-of-
funds
POST/funds-confirmations
Y
Y
Y
Y
Y
27.1.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Savings
Accounts
Deposit
Accounts
Credit
Cards
Foreign
Currency
Accounts*
Global
Wallet
Confirmation-of-
funds
POST/funds-confirmation-consents
Y
N
Y
Y
Y
Y
Confirmation-of-
funds
DELETE/funds-confirmation-
consents/{ConsentID}
Y
N
Y
Y
Y
Y
Confirmation-of-
funds
GET/funds-confirmation-
consents/{ConsentID}
Y
N
Y
Y
Y
Y
Confirmation-of-
funds
POST/funds-confirmations
Y
N
Y
Y
Y
Y
*As per direct channel availability, this functionality will not be available for customers on a weekly basis between Saturday 22:00 and
Sunday 08:00 GMT.
For Credit Cards only card holder accounts (child) are in scope for Confirmation of Funds. Requests for Confirmation of Funds to a
Credit Card control account (parent) and Savings account are not supported.
Currently a request to a Credit Card control account (parent) will return an error message that does not align with the account
functionality.
-
standards on both desktop and mobile devices.
COF received for a PIS request is an optional call. When a user does not have the correct entitlements an error message will be
returned to the TPP. When a COF call is not fulfilled a payment can still be completed.
138
PUBLIC
27.1.3. HSBC Kinetic
Resource
Endpoints
Business
Current
Accounts
Credit
Cards
Confirmation-of-
funds
POST/funds-confirmation-consents
Y
Y
Confirmation-of-
funds
DELETE/funds-confirmation-
consents/{ConsentID}
Y
Y
Confirmation-of-
funds
GET/funds-confirmation-
consents/{ConsentID}
Y
Y
Confirmation-of-
funds
POST/funds-confirmations
Y
Y
27.1.4. HSBC Corporate UK and HSBC Innovation Banking - HSBCnet
Resource
Endpoints
Business
Current
Accounts
Credit
Cards
Confirmation-of-
funds
POST/funds-confirmation-consents
Y
Y
Confirmation-of-
funds
DELETE/funds-confirmation-
consents/{ConsentID}
Y
Y
Confirmation-of-
funds
GET/funds-confirmation-
consents/{ConsentID}
Y
Y
Confirmation-of-
funds
POST/funds-confirmations
Y
Y
27.2. Request Fields
For POST /funds-confirmations:
Field
Notes
Error Code if invalid
InstructedAmount / Currency
Currency in the request should match the Account Currency of
the PSU, for which the PSU has given consent.
400 - UK.OBIE.Field.Invalid
139
PUBLIC
28. Variable Recurring Payments - Sweeping
28.1. Key Information
HSBC Personal, first direct, HSBC Business and HSBC Kinetic support variable recurring payments for Sweeping from current
accounts.
Please note there is a risk that payment requests received between 18:00 - 23:45 which are deemed to require additional fraud checks
have the potential to be rejected/declined, unless the fraud checks can be completed with the customer on the same day.
28.2. Payment Refunds
Refunds functionality is not implemented for VRP Sweeping.
28.3. Implemented Endpoints
28.3.1. HSBC Personal, first direct
Resource
Endpoints
Personal
Current
Accounts
Domestic-vrps
POST/domestic-vrp-consents
Y
Domestic-vrps
GET/domestic-vrp-consents/{ConsentId}
Y
Domestic-vrps
DELETE/domestic-vrp-consents/{ConsentId}
Y
Domestic-vrps
POST/domestic-vrps
Y
Domestic-vrps
GET/domestic-vrps/{DomesticVRPId}
Y
Domestic-vrps
POST/domestic-vrp-
consents/{ConsentId}/funds-confirmation
Y
Domestic-vrps
POST/ events
Y
Sweeping Payments will be rejected if Trusted Beneficiary exemption fails at the time of fulfilment.
140
PUBLIC
28.3.2. HSBC Business
Resource
Endpoints
Business
Current
Accounts
Domestic-vrps
POST/domestic-vrp-consents
Y
Domestic-vrps
GET/domestic-vrp-consents/{ConsentId}
Y
Domestic-vrps
DELETE/domestic-vrp-consents
/{ConsentId}
Y
Domestic-vrps
POST/domestic-vrps
Y
Domestic-vrps
GET/domestic-vrps/{DomesticVRPId}
Y
Domestic-vrps
POST/domestic-vrp-
consents/{ConsentId}/funds-
confirmation
Y
Domestic-vrps
POST/ events
Y
28.3.3. HSBC Kinetic
Resource
Endpoints
Business
Current
Accounts
Domestic-vrps
POST/domestic-vrp-consents
Y
Domestic-vrps
GET/domestic-vrp-consents/{ConsentId}
Y
Domestic-vrps
DELETE/domestic-vrp-consents/{ConsentId}
Y
Domestic-vrps
POST/domestic-vrps
Y
Domestic-vrps
GET/domestic-vrps/{DomesticVRPId}
Y
Domestic-vrps
POST/domestic-vrp-
consents/{ConsentId}/funds-confirmation
Y
Domestic-vrps
POST/ events
Y
141
PUBLIC
28.4. Request Fields
28.4.1. HSBC Personal, first direct
For POST /domestic-vrp-consents and POST /domestic-vrps
Request Field
Description
HTTP
Status
Code
Error Code
Error Description
Maximum individual Amount
Transaction Limit Checks
first direct: £49,999
400
UK.OBIE.Field.Invalid
"Maximum Individual
amount is exceeding
limit"
Maximum individual Amount
Minimum Amount: £0.01
400
UK.OBIE.Field.Invalid
"Max individual amount
is below the minimum
amount"
Maximum individual Amount
Negative amount gives constraint violation error
400
UK.OBIE.Field.Invalid
Constraint Violatation
Maximum individual Amount
Only up to 2 decimal places allowed
400
UK.OBIE.Field.Invalid
Maximum Individual
Amount must not exceed
2 decimal places
Maximum individual
Amount → Currency
Currency can only be GBP
400
UK.OBIE.Field.Unexpected
Invalid Currency
Periodic Limit → Amount
Limit of lower period should be lesser than limit
on higher period. Example
Maximum individual amount <
Fortnightly should be < than Monthly,Half Yearly
Monthly should be < than Half Yearly,Yearly
Half Yearly should be < than Yearly
400
UK.OBIE.Field.Unexpected
Periodic Limit amount is
below the minimum
amount
Periodic Limit → Amount
Minimum Amount: £0.01
400
UK.OBIE.Field.Unexpected
Periodic Limit amount is
below the minimum
amount
Periodic Limit → Amount
Only up to 2 decimal places allowed
400
UK.OBIE.Field.Unexpected
Instructed amount must
not exceed 2 decimal
places
PeriodAlignment
PeriodAlignment must be Consent if
PeriodType=Fortnight
400
UK.OBIE.Field.Invalid
CreditorAccount -> Identification
CreditorAccount Identification can only be 14
digits
400
UK.OBIE.Field.Invalid
DebtorAccount -> Identification
DebtorAccount Identification can only be 14 digits
400
UK.OBIE.Field.Invalid
Creditor Account Name
No special character allowed
400
UK.OBIE.Field.Unexpected
X-HSBC-TPP-ID
if present - Length should not be greater than 18
Char
400
UK.OBIE.Field.Invalid
TPP Id length cannot be
more than 18 characters
SupplementaryData
Reject if supplementary data is present (as its
unused)
RemittancInformation.Reference
RemittancInformation Reference is missing
400
UK.OBIE.Field.Missing
RemittancInformation.Reference
Reference should be Max 18 char
400
UK.OBIE.Field.Invalid
Risk Object
Risk object should be present
400
UK.OBIE.Field.Missing
Mandatory field missing
VRPTypes
Must be sweeping
400
UK.OBIE.Field.Invalid
Invalid field
OBDomesticVRPControlParameters
.PeriodicLimits
Must contain at least 1 item
400
UK.OBIE.Field.Expected
PSUAuthenticationMethods
For sweeping only UK.OBIE.SCANotRequired is
accepted
400
142
PUBLIC
28.4.2. HSBC Business
Request Field
Description
Error Code if invalid
Periodic Limit → Amount
Limit of lower period should be lesser than limit on higher
period. Example
Maximum individual amount < Daily,Weekly,...
Daily should be < than Weekly,Fortnightly...
Weekly should be < than Fortnightly,Monthly...
Fortnightly should be < than Monthly,Half Yearly
Monthly should be < than Half Yearly,Yearly
Half Yearly should be < than Yearly
400 - UK.OBIE.Field.Unexpected
OBCashAccountDebtorWithName.
SchemeName
If DebtorAccount provided must be
UK.OBIE.SortCodeAccountNumber
400 - UK.OBIE.Unsupported.Scheme
OBCashAccountDebtorWithName.
Identification
If provided: must be exactly 14 digits (0-9) and first digit must
be 4. Must not be equal to CreditorAccount Identification
400 - UK.OBIE.Field.Invalid
OBCashAccountCreditor3. SchemeName
Must be UK.OBIE.SortCodeAccountNumber
400 - 4UK.OBIE.Unsupported.Scheme
OBCashAccountCreditor3.Identification
Must be exactly 14 digits (0-9)
Must not be equal to DebtorAccount Identification
400 - UK.OBIE.Field.Invalid
OBCashAccountCreditor3.Name
Must be 18 characters or fewer
Must be the same allowed characters as in Domestic SIP 0-9
a-z A-Z ?/&.*-
400 - UK.OBIE.Unsupported.Scheme
RemittanceInformation
Object RemittanceInformation must be provided
400 - UK.OBIE.Field.Expected
RemittanceInformation.Reference
Field Reference must be provided within
RemittanceInformation object
This field must be no more than 18 characters and can
contain A to Z, a to z, 0 to 9 and the special characters & - /
(spaces are also allowed).
400 - UK.OBIE.Field.Expected (if not
provided)
400 - UK.OBIE.Field.Invalid (if provided
OBDomesticVRPControlParameters.
ValidFromDateTime
If not provided, the from datetime of the request will be set
by us of when we received the instruction. This field must not
be > ValidToDateTime.
Past timestamp allowed only for the current date of when the
instruction is submitted. Past date is not permitted.
400 - UK.OBIE.Field.Invalid
OBDomesticVRPControlParameters.
ValidToDateTime
If provided, must be >= now and must be >=
ValidFromDateTime
400 - UK.OBIE.Field.Invalid
OBDomesticVRPControlParameters.
MaximumIndividualAmount
Must be provided
400 - UK.OBIE.Field.Expected
OBDomesticVRPControlParameters.Amount
Must be at most 2 decimal places
400 - UK.OBIE.Field.Invalid
OBDomesticVRPControlParameters.Currency
Must be GBP
400 - UK.OBIE.Unsupported.Currency
OBDomesticVRPControlParameters.PeriodicLimi
ts
Must contain at least 1 item
400 - UK.OBIE.Field.Expected
OBDomesticVRPControlParameters.PeriodType
Each PeriodType must be used at most 1 time in the items
within PeriodicLimits
400 - UK.OBIE.Field.Invalid
OBDomesticVRPControlParameters.PeriodAlign
ment
PeriodAlignment must be Consent if PeriodType=Fortnight
400 - UK.OBIE.Field.Invalid
OBDomesticVRPControlParameters.VRPType
Must contain UK.OBIE.VRPType.Sweeping and it must be the
only value provided
400 - UK.OBIE.Field.Invalid
OBDomesticVRPControlParameters.PSUAuthent
icationMethods
Must contain UK.OBIE.SCANotRequired
and it must be the only value provided
400 - UK.OBIE.Field.Invalid
143
PUBLIC
28.5. Payment Limits
28.5.1. HSBC Personal, first direct
28.5.2. HSBC Business
-up and
payment fulfilment.
Fortnight = 14 days,
One month = 31 days, Half Year = 183 days, One Year = 366 days). This will be checked at consent setup.
28.5.3. HSBC Kinetic
-
up and payment fulfilment.
ays,
One month = 31 days, Half Year = 183 days, One Year = 366 days). This will be checked at consent setup.
28.6. Fees for CHAPS Payments
The PSU can select a different account for bearing the charges for the CHAPS transaction.
The charge will be a dynamic amount for each CHAPS transaction request.
28.7. Cut-Off Time for CHAPS Payments
HSBC Personal, first direct
Cut-off time for CHAPS payment is 8:00 AM to 3:30 PM UK time. Any request for a CHAPS payment outside these values will be held
and processed the next working day.
144
PUBLIC
HSBC Business
Cut-off time for CHAPS payment is 8:00 AM to 5:10 PM UK time. Any request for a CHAPS payment outside these values will be
rejected. These cut-off times are aligned to the offering on the direct channels.
28.8. Payment Status
For Sweeping payments, a request for a payment status HSBC returns one of the following payment statuses:
Endpoint: POST /domestic-vrps
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
All preceding checks such as technical validation and
customer profile were successful therefore the
payment initiation has been accepted for execution.
Debit and credit have not been posted.
pay/no-pay decision. The terminal status can be
accessed via the GET/domestic-vrps
/{DomesticVRPId}
200
Final
All brands
Payment request is rejected (no Debit and no Credit
posted to the account)
201
Final
All brands
When the trusted beneficiary has been deleted
between VRP consent set-up and payment initiation,
the request will be rejected with:
StatusReason: UK.OBIE.ExemptionNotApplied
StatusReasonDescription: "Failed Trusted beneficiary
check"
Endpoint: GET/domestic-vrps/{DomesticVRPId}
Status
API Call
Status
Status
Type
Applicable
to
Account Position
200
Interim
All brands
All preceding checks such as technical validation and
customer profile were successful therefore the
payment initiation has been accepted for execution.
Debit and credit have not been posted.
pay/no-pay decision.
Credit Settlement
200
Final
All brands
Payment request has been processed successfully
(i.e. Debit and Credit have been posted successfully).
Current balance reflects position after the Debit /
Credit has taken place
200
Final
All brands
Payment request is rejected (no Debit and no Credit
posted to the account)
201
Final
All brands
When the trusted beneficiary has been deleted
between VRP consent set-up and payment initiation,
the request will be rejected
For CHAPS payments, a request for a payment status will return one of the following statuses:
➢ Pending (when multi-authorisation is required in HSBCs direct channel)
145
PUBLIC
➢ Rejected
➢ AcceptedSettlementCompleted
TPPs can request & receive payment status updates for up to 10 days after the payment has been posted. A final payment status can
In a scenario where a TPP terminates the connection before they have received a response from the POST endpoint, the payment may
still have been submitted for processing. I this scenario, the TPP should resubmit the payment with the same idempotency key (x-
idempotency-key) so that they can check the payment status. This will not result in a duplicate payment if using the same
idempotency key.
28.9. Additional Notes
In a single consent the following rules apply:
➢ The max number of periodic limits is 6 (Day, Week, Fortnight, Month, Half-Year, Year)
➢ Periodic limits cannot be repeated in a consent e.g. Day, Day, Week, Week.
Debtor Account and Creditor Account in fulfilment request should match the consented payload.
If provided, debtor account must be a PCA (for HSBC Personal and first direct) or BCA (for HSBC Business and HSBC Kinetic). If
another account type is provided, PSU will be presented with a hard-stop error and a CTA to exit HSBC and return to the TPP.
For HSBC Kinetic, if a PSU wishes to reinstate a beneficiary (using VRP re-authentication) after having deleted it from the trusted
beneficiary list, they will have to wait until the next day to undertake this.
29. Two-way Notice of Revocation
response
146
PUBLIC
29.1. Implemented Endpoints
29.1.1. HSBC Personal, first direct, M&S Bank
Endpoints
Implemented?
POST /event-subscriptions
Y
GET /event-subscriptions
Y
PUT /event-subscriptions/{EventSubscriptionId}
Y
DELETE /event-subscriptions/{EventSubscriptionId}
Y
POST /events
Y
For AIS/VRP/COF consents of Personal Banking that are authorized prior to 22nd Sept 2022, the JWT response to TPP will have urn
set to "uk:org:openbanking:consent-authorization-revoked" and for the consents authorized on or after 22nd Sept 2022 will have urn
set to "uk:org:openbanking:consent-access-revoked"
29.1.2. HSBC Business
Endpoints
Implemented?
POST /event-subscriptions
Y
GET /event-subscriptions
Y
PUT /event-subscriptions/{EventSubscriptionId}
Y
DELETE /event-subscriptions/{EventSubscriptionId}
Y
POST /events
Y
29.1.3. HSBC Kinetic
Endpoints
Implemented?
POST /event-subscriptions
Y
GET /event-subscriptions
Y
PUT /event-subscriptions/{EventSubscriptionId}
Y
DELETE /event-subscriptions/{EventSubscriptionId}
Y
POST /events
Y
29.2. Request Fields
For POST /event-subscriptions:
147
PUBLIC
Field
Notes
Error Code if invalid
OBEventPolling1/maxEvents
Mandatory
Max events supported in a request response cycle is 100
Allowed value between 1 to 100
400 - UK.OBIE.Field.Invalid
OBEventPolling1/returnImmediately
Mandatory
Value should always be true as only short polling is supported
400 - UK.OBIE.Field.Invalid
The events sent by ASPSP to TPP in POST /events response should be acknowledged by TPP in the subsequent /POST events request.
In the instance where the TPP fails to acknowledge events, ASPSPs will attempt to send the same event up to 5 times, following
which the event will be dropped from the next polling cycle.
The TPP can trigger the POST /events endpoint only after an hour of the last polling cycle.
148
PUBLIC
30. Error Codes
30.1. Common, Authorisation and Token Errors
The list of common authorisation and token errors can be found here.
30.2. Account Information Service (AIS) Errors
The Account Information Service (AIS) errors list can be found here.
The list covers the points listed below.
➢ Consents
➢ Accounts
➢ Balances
➢ Transactions
➢ Beneficiaries
➢ Direct Debits
➢ Standing Orders
➢ Scheduled Payments
➢ Product
➢ Party
30.3. Payment Initiation Service (PIS) Errors
The Payment Initiation Service (PIS) errors list can be found here.
The list covers the points listed below.
Consents:
➢ Domestic Payment Consents
➢ Domestic Scheduled Payment Consents
➢ Domestic Standing Order Consents
➢ International Payment Consents
➢ International Scheduled Payment Consents
➢ International Standing Order Consents
149
PUBLIC
➢ File Payment Consents
Fulfilment:
➢ Domestic Payments
➢ Domestic Payment ID
➢ Domestic Scheduled Payments
➢ Domestic Scheduled Payment ID
➢ Domestic Standing Orders
➢ Domestic Standing Order ID
➢ International Payments
➢ International Payment ID
➢ International Scheduled Payments
➢ International Scheduled Payment ID
➢ International Standing Orders
➢ International Standing Order ID
30.4. Card Based Payment Instrument Issuer (CBPII) Errors
The Card Based Payment Instrument Issuer (CBPII) errors list can be found here.
30.5. Event Notification Errors
The Event Notification errors list can be found here.
150
PUBLIC
31. Disclaimer
This document contains information about the current functioning of certain HSBC Group's Open Banking API endpoints as of the
date of publication. While we have taken reasonable steps to ensure the accuracy, correctness and completeness of the information
tion of
any kind, whether express or implied. The use of this information is at your sole risk. We shall not be liable for any loss or damage
whatsoever and howsoever arising as a result of your use of or reliance on the information contained in this document to the
maximum extent permitted by law.