Open Banking - developer.hsbc.com · HSBC has made all reasonable efforts to apply the OBIE...

PUBLIC

Open Banking

Implementation Guide

Date: 26-04-19

1 PUBLIC

Table of contents

Introduction 2

Key Changes 3

Transactions API v1.1.0 5

Accounts and Transactions Summary v2.0.0 10

Account Request API v2.0.0 11


Party API v2.0.0 15

Products API v2.0.0 16

Accounts and Transactions Summary 3.1.0 18

Account Request API v3.1.0 20


Party API v3.1.0 24

Products v3.1.0 25

Payment Initiation Summary v3.1.0 27

Domestic Payment v3.1.0 28

Domestic Scheduled Payment v3.1.0 29

Domestic Standing Order v3.1.0 30

Confirmation of Funds Summary v3.1.0 34

Limits 36

Versions and Deprecation 38

Disclaimer 39

2 PUBLIC

Introduction

Updated 10-03-19

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 document covers items HSBC wishes

to provide further detail on.

We welcome feedback to make this document as useful as possible.

HSBC encourages developers to adopt the latest vesion of APIs. We will make reasonable endeavours to fix

defects in all APIs in parallel, but will prioritise the latest version.

To keep each section independent and minimise cross-referencing, text is duplicated between versions of APIs, even if they are otherwise identical; this is clearly noted in-line.

3 PUBLIC

Key Changes

Updated 23-04-19

HSBC Personal and Business Separation – added section

Updated 10-03-19

Numerous v3.1.0 APIs – added sections

Transactions API v.1.1.0 – Added Response Fields information

Transactions API v.2.0.0 – Added Response Fields information

Limits – added section

Deprecation – added section

Parallel running – modified to reflect intended deprecation of APIs and new API versions

4 PUBLIC

Accounts and Transactions 1.1.0

5 PUBLIC

Transactions API v1.1.0

Updated 10-03-19

Transactions 2.0.0 onwards have been enhanced to accept durations greater than 180 days, to honour the

different permutations of fromBookingDateTime and toBookingDateTime, to state the times it is returning as

00:00:00 and 23:59:59, and to return Pending transactions.

Truncation

The date ranges of the transactions returned by the GET /accounts/{AccountId}/transactions message depend

upon 2 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), transactionToDate = the date the request is sent in

When the the TPP sends in GET /accounts/{AccountId}/transactions, it can send in fromBookingDateTime and

toBookingDateTime

HSBC will accept a future-dated toBookingDateTime, but will truncate it from the time period it returns –

termed 'future truncation'

If no dates are provided, and the time between the transactionFromDate and transactionToDate is > than

180 days, HSBC will return using the intent's transactionFromDate to the transactionFromDate + 180 days

HSBC will truncate dates that don't crossover with the intent's transactionFromDate and transactionToDate

– termed 'crossover truncation'

If the resulting duration is > 180 days

HSBC will restrict to the earliest 180 days; this is a proprietary HSBC function – termed 'max duration

truncation'

If the TPP wants more than the truncated time period, they must send in multiple requests for different date periods

(each of which could have paginated responses)

To identify that future truncation, crossover truncation or max duration truncation have occurred, the TPP

may wish to check the 'self' link returned, which will contain proprietary fromBookingDateTime and

toBookingDateTime fields; it is not possible to identify the reason

6 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


Example 3: crossover truncation, but future truncation is irrelvant


|--------------| ... 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


X ... today is irrelevant

<Nothing> ... accessible period after truncation

Example 5: no date period in the intent

(----...------------------) ... INTENT period not sent in, so ASSUMED TO BE TODAY – 2190 days (6 years)

|----------| ... GET /TRANSACTION period

X ... today

|----------| ... accessible period after truncation

Transaction Ordering

HSBC returns the transactions in reverse date order (i.e. most recent first).

7 PUBLIC

Pagination

Page size is nominally 50 transactions, but is variable according to circumstances, for example 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.

The following shows a worked example of max duration truncation and pagination; note how the truncation in

effect requires the TPP to go forward in time, but the pagination within that period goes backwards in time:

(oldest) (most recent)

|-----------------------------------------------| ...TPP request is > 180 days

|-----------------------| ...HSBC truncates dates to earliest 180 days

|<--50--| ...first paginated response in the most recent from the earliest 180 days

|<--50--| ...second paginated response

|<--50--| ...third paginated response

|-----------------------| ...the TPP must then make a totally separate call for remaining time

|<--50--| ...fourth paginated response / first paginated response to second block

|<--50--| ...fifth

|<--50--| ...sixth

TPPs may wish to keep their requests less than 180 days and to go backwards in time themselves, so

that the following pattern can be achieved.


|-----------------------| ...TPP request is 180 days

|<--50--| ...first paginated response

|<--50--| ...second

|<--50--| ...third

|-----------------------| ...TPP request is 180 days

|<--50--| ...fourth

|<--50--| ...fifth

|<--50--| ...sixth

8 PUBLIC

Date Filtering

HSBC expects both the fromBookingDateTime and toBookingDateTime parameters to be passed in; if only one

is passed in, it will not be honoured (exact behaviour will be determined according to which parameter and other

factors).

Time Filtering

HSBC does not utilise times in transaction date-times, so the time components of fromBookingDateTime and

toBookingDateTime are ignored, however HSBC will return the fromBookingDateTime and toBookingDateTime in

the 'self' link without the time parameters in them, however it will set them to values of 00:00:00, which is

incorrect for the toBookingDateTime, as it will actually return data until 23:59:59. To illustrate:

Request: date1-time1 date2-time2

Period of data actually returned: date1-00:00:00 date2-23:59:59

Values in the 'self' link: fromBookingDateTime=date1-00:00:00 and toBookingDateTime=date2-00:00:00

Booked and Pending Transactions

GET /accounts/{AccountId}/transactions only returns booked transactions.

Response Fields

Field Notes

OBReadTransaction4/Data/Transaction/BankTransactionCode/code

Not returned

OBReadTransaction4/Data/Transaction/ProprietaryBankTransactionCode/code

Not returned

9 PUBLIC


10 PUBLIC

Accounts and Transactions Summary v2.0.0

Updated 30-08-18

Implemented Endpoints

The following Account and Transaction endpoints are implemented:

Resource Endpoints Mandatory Implemented

account-requests

POST /account-requests GET /account-requests/{AccountRequestId} DELETE /account-requests/{AccountRequestId}

Mandatory Mandatory Mandatory

Y Y Y

accounts GET /accounts GET /accounts/{AccountId}

Mandatory Mandatory

Y Y

balances GET /accounts/{AccountId}/balances GET /balances

Mandatory Optional

Y N

transactions GET /accounts/{AccountId}/transactions GET /transactions

Mandatory Optional

Y N

beneficiaries GET /accounts/{AccountId}/beneficiaries GET /beneficiaries

Conditional Optional

Y N

direct-debits GET /accounts/{AccountId}/direct-debits GET /direct-debits


Y N

standing-orders GET /accounts/{AccountId}/standing-orders GET /standing-orders


Y N

products GET /accounts/{AccountId}/product GET /products


Y N

offers GET /accounts/{AccountId}/offers GET /offers


N N

party GET /accounts/{AccountId}/party GET /party

Conditional Conditional

Y * N

scheduled-payments

GET /accounts/{AccountId}/scheduled-payments GET /scheduled-payments


Y N

statements GET /accounts/{AccountId}/statements GET /accounts/{AccountId}/statements/{StatementId} GET /accounts/{AccountId}/statements/{StatementId}/file GET /accounts/{AccountId}/statements/{StatementId}/transactions GET /statements

Conditional Conditional Conditional Conditional Optional

N N N N N

* An empty data set will always be returned

11 PUBLIC

Account Request API v2.0.0

Updated 30-08-18

Overview

The following values that are not in strikethrough are accepted in OBReadRequest1/Data/Permissions:

ReadAccountsBasic

ReadAccountsDetail

ReadBalances

ReadBeneficiariesBasic

ReadBeneficiariesDetail

ReadDirectDebits

ReadOffers

ReadPAN

ReadParty (see below note)

ReadPartyPSU

ReadProducts

ReadScheduledPaymentsBasic

ReadScheduledPaymentsDetail

ReadStandingOrdersBasic

ReadStandingOrdersDetail

ReadStatementsBasic

ReadStatementsDetail

ReadTransactionsBasic

ReadTransactionsCredits

ReadTransactionsDebits

ReadTransactionsDetail

Although POST /account-requests accepts a value of ReadParty in the OBReadRequest1/Data/Permissions

field, GET /accounts/{AccountId}/party will always return an empty data set.

12 PUBLIC


Updated 10-03-19

Truncation

The date ranges of the transactions returned by the GET /accounts/{AccountId}/transactions message depends

upon two date ranges, indicating the intent and requested time periods. The behaviour of the API can change






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 +7 days from the date the POST

/account-requests was sent in.


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



To identify that future truncation or crossover truncation truncation have occurred, the TPP may wish to

check the 'self' link returned, which will contain proprietary fromBookingDateTime and toBookingDateTime

fields; it is not possible to identify the reason


|---------------------| ... INTENT period


X ... today





X ... today


13 PUBLIC












|-------------------------| ... INTENT period not sent in, so defaulted to today – 2190 days to today


X ... today




Pagination

Page size is nominally 400 transactions, but is variable according to circumstances, for example a page will at

most return 180 days of data 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.

The following shows a worked example of pagination:



|<-400--| ...first paginated response

|<-400--| ...second

|<-30---| ...third, which happens to end the first 180 day block

|<-400--| ...fourth

|<-400--| ...fifth

|<--20--| ...sixth

Date Filtering

HSBC accepts one, both or neither of the fromBookingDateTime and toBookingDateTime parameters being

passed in.

Time Filtering


toBookingDateTime are ignored, and data will be returned from the fromBookingDateTime 00:00:00 until the

toBookingDateTime 23:59:59 (subject to pagination).

14 PUBLIC


GET /accounts/{AccountId}/transactions can return both Booked and Pending transactions.

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.

Response Fields

Field Notes


Not returned


Populated with the following values:

))) - 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

15 PUBLIC

Party API v2.0.0

Updated 30-08-18

Overview

Subject to having correct permissions, the Party API will always return an empty data set.

16 PUBLIC

Products API v2.0.0

Updated 30-08-18

Overview

The following table summarises the possible responses

Resp. Product Section Subset Data Section

Descripiton

Product ID Product Name

Product Details

Credit Interest

Overdraft Interest

Other Fees & Charges

1

If the “Product ID” field in the “Product” section of the response has a value then TPP can refer to Open Data API for complete product reference data for the account

2

If the “Product ID” in the “Product” 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.

3

If the “Product ID” in the “Product” section has a 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.

4

If the response contains the “Product Name” field in the “Product” section with the “Product Id” field masked and subset data sections are not populated then that means the data is not available to be shared in this instance.

5

If the “Product ID” in the “Product” 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.

17 PUBLIC


18 PUBLIC

Accounts and Transactions Summary 3.1.0

Updated 10-03-19

Note: the only changes between this and Accounts and Transaction 2.0.0are renaming of the account-access-

consents resource and endpoint, and the response field population notes



Resource Endpoints Mandatory Implemented

account-access-consents

POST/account-access-consents GET /account-access-consents/{ConsentId} DELETE /account-access-consents/{ConsentId}

Mandatory Mandatory Mandatory

Y Y Y

accounts GET /accounts GET /accounts/{AccountId}

Mandatory Mandatory

Y Y

balances GET /accounts/{AccountId}/balances GET /balances

Mandatory Optional

Y N

transactions GET /accounts/{AccountId}/transactions GET /transactions

Mandatory Optional

Y N

beneficiaries GET /accounts/{AccountId}/beneficiaries GET /beneficiaries


Y N

direct-debits GET /accounts/{AccountId}/direct-debits GET /direct-debits


Y N

standing-orders GET /accounts/{AccountId}/standing-orders GET /standing-orders


Y N

products GET /accounts/{AccountId}/product GET /products


Y N

offers GET /accounts/{AccountId}/offers GET /offers


N N

party GET /accounts/{AccountId}/party GET /party

Conditional Conditional

Y * N

scheduled-payments

GET /accounts/{AccountId}/scheduled-payments GET /scheduled-payments


Y N

statements GET /accounts/{AccountId}/statements GET /accounts/{AccountId}/statements/{StatementId} GET /accounts/{AccountId}/statements/{StatementId}/file GET /accounts/{AccountId}/statements/{StatementId}/transactions GET /statements

Conditional Conditional Conditional Conditional Optional

N N N N N

19 PUBLIC

* An empty data set will always be returned

20 PUBLIC

Account Request API v3.1.0

Updated 10-03-19

Overview

The following values that are not in strikethrough are accepted in OBReadRequest1/Data/Permissions:

ReadAccountsBasic

ReadAccountsDetail

ReadBalances

ReadBeneficiariesBasic

ReadBeneficiariesDetail

ReadDirectDebits

ReadOffers

ReadPAN

ReadParty (see below note)

ReadPartyPSU

ReadProducts

ReadScheduledPaymentsBasic

ReadScheduledPaymentsDetail

ReadStandingOrdersBasic

ReadStandingOrdersDetail

ReadStatementsBasic

ReadStatementsDetail

ReadTransactionsBasic

ReadTransactionsCredits

ReadTransactionsDebits

ReadTransactionsDetail

Although POST /account-requests accepts a value of ReadParty in the OBReadRequest1/Data/Permissions

field, GET /accounts/{AccountId}/party will always return an empty data set.

21 PUBLIC


Updated 10-03-19

Truncation

The date ranges of the transactions returned by the GET /accounts/{AccountId}/transactions message depends

upon two date ranges, indicating the intent and requested time periods. The behaviour of the API can change






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 +7 days from the date the POST

/account-requests was sent in.


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



To identify that future truncation or crossover truncation truncation have occurred, the TPP may wish to

check the 'self' link returned, which will contain proprietary fromBookingDateTime and toBookingDateTime

fields; it is not possible to identify the reason


|---------------------| ... INTENT period


X ... today





X ... today


22 PUBLIC












|-------------------------| ... INTENT period not sent in, so defaulted to today – 2190 days to today


X ... today




Pagination

Page size is nominally 400 transactions, but is variable according to circumstances, for example a page will at

most return 180 days of data 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.

The following shows a worked example of pagination:



|<-400--| ...first paginated response

|<-400--| ...second

|<-30---| ...third, which happens to end the first 180 day block

|<-400--| ...fourth

|<-400--| ...fifth

|<--20--| ...sixth

Date Filtering

HSBC accepts one, both or neither of the fromBookingDateTime and toBookingDateTime parameters being

passed in.

Time Filtering


toBookingDateTime are ignored, and data will be returned from the fromBookingDateTime 00:00:00 until the

toBookingDateTime 23:59:59 (subject to pagination).

23 PUBLIC


GET /accounts/{AccountId}/transactions can return both Booked and Pending transactions.

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.

Response Fields

Field Notes


Not returned


Populated with the following values:

))) - 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

24 PUBLIC

Party API v3.1.0

Updated 10-03-19

Overview

Subject to having correct permissions, the Party API will always return an empty data set.

25 PUBLIC

Products v3.1.0

Updated 10-03-19

Overview

The following table summarises the possible responses

Resp. Product Section Subset Data Section

Descripiton

Product ID Product Name

Product Details

Credit Interest

Overdraft Interest

Other Fees & Charges

1

If the “Product ID” field in the “Product” section of the response has a value then TPP can refer to Open Data API for complete product reference data for the account

2

If the “Product ID” in the “Product” 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.

3

If the “Product ID” in the “Product” section has a 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.

4

If the response contains the “Product Name” field in the “Product” section with the “Product Id” field masked and subset data sections are not populated then that means the data is not available to be shared in this instance.

5

If the “Product ID” in the “Product” 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.

26 PUBLIC

Payment Initiation 3.1.0

27 PUBLIC

Payment Initiation Summary v3.1.0

Updated: 10-03-19



Resource Endpoints Implemented

domestic-payment-consents



domestic-payments

domestic-payments

POST /domestic-payment-consents

GET /domestic-payment-consents/{ConsentId}

GET /domestic-payment-consents/{ConsentId}/funds-confirmation

POST /domestic-payments

GET /domestic-payments/{DomesticPaymentId}

Y

Y

N

Y

Y (restricted *)

domestic-scheduled-payment-consents

domestic-scheduled-payment-consents

domestic-scheduled-payments

domestic-scheduled-payments

POST /domestic-scheduled-payment-consents

GET /domestic-scheduled-payment-consents/{ConsentId}

POST /domestic-scheduled-payments

GET /domestic-scheduled-payments/{DomesticScheduledPaymentId}

Y

Y

Y

Y (restricted *)

domestic-standing-order-consents

domestic-standing-order-consents

domestic-standing-orders

domestic-standing-orders

POST /domestic-standing-order-consents

GET /domestic-standing-order-consents/{ConsentId}

POST /domestic-standing-orders

GET /domestic-standing-orders/{DomesticStandingOrderId}

Y

Y

Y

N

international-payment-consents



international-payments

international-payments

POST /international-payment-consents

GET /international-payment-consents/{ConsentId}

GET /international-payment-consents/{ConsentId}/funds-confirmation

POST /international-payments

GET /international-payments/{InternationalPaymentId}

N

N

N

N

N

international-scheduled-payment-consents



international-scheduled-payments

international-scheduled-payments

POST /international-scheduled-payment-consents

GET /international-scheduled-payment-consents/{ConsentId}

GET /international-scheduled-payment-consents/{ConsentId}/funds-confirmation

POST /international-scheduled-payments

GET /international-scheduled-payments/{InternationalScheduledPaymentId}

N

N

N

N

N

international-standing-order-consents

international-standing-order-consents

international-standing-orders

international-standing-orders

POST /international-standing-order-consents

GET /international-standing-order-consents/{ConsentId}

POST /international-standing-orders

GET /international-standing-orders/{InternationalStandingOrderPaymentId}

N

N

N

N

file-payment-consents




file-payments

file-payments

file-payments

POST /file-payment-consents

GET /file-payment-consents/{ConsentId}

POST /file-payment-consents/{ConsentId}/file

GET /file-payment-consents/{ConsentId}/file

POST /file-payments

GET /file-payments/{FilePaymentId}

GET /file-payments/{FilePaymentId}/report-file

N

N

N

N

N

N

N

* Implemented for HSBC Commerical Banking only

28 PUBLIC

Domestic Payment v3.1.0

Updated 10-03-19

Request Fields

Field Notes Error Code if Invalid

authorisationType HSBC Retail, FD, M&S Bank – Single

HSBC Commerical – 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 See Limits section at end of document. 400 - UK.OBIE.Field.Invalid

MerchantCategoryCode If PaymentContextCode = EcommerceGoods or EcommerceServices, this field is mandatory and therefore must be validated by the TPP

MerchantCustomerIdentification If PaymentContextCode = EcommerceGoods or EcommerceServices, this field is mandatory and therefore must be validated by the TPP

DeliveryAddress If PaymentContextCode = EcommerceGoods, this field is mandatory and therefore must be validated by the TPP

29 PUBLIC

Domestic Scheduled Payment v3.1.0

Updated 10-03-19

Request Fields

For POST /domestic-scheduled-payment-consents and POST /domestic-scheduled-payments:


authorisationType HSBC Retail, FD, M&S Bank – Single

HSBC Commerical – Any or Single

RequestedExecutionDateTime HSBC Retail, FD, M&S Bank - Must be > today and ≤ 365 days ahead

HSBC Commerical - Must be > today and ≤ 45 days ahead

400 - UK.OBIE.Field.InvalidDate



InstructedAmount/Currency Must be GBP 400 - UK.OBIE.Field.Unexpected

InstructedAmount/Amount See Limits section at end of document. 400 - UK.OBIE.Field.Invalid




30 PUBLIC

Domestic Standing Order v3.1.0

Updated 10-03-19

Request Fields

For POST /domestic-standing-order-consents and POST /domestic-standing-orders:


Frequency See separate Permitted Frequency Values section

400 - UK.OBIE.Unsupported.Frequency

NumberOfPayments Mutually exclusive with presence of FinalPaymentDateTime; one and only one must be present

Must be > 0 and ≤ 999

400 - UK.OBIE.Field.Invalid

FirstPaymentDateTime Must be > tomorrow and ≤ 365 days ahead

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):




Example 3 (misaligned):




Note: the time element has removed from above DateTime examples, for simplicity.


31 PUBLIC


RecurringPaymentAmount Optional

If Present ReurringPaymentAmount = FinalPaymentAmount = FirstPaymentAmount


FinalPaymentAmount Optional

If Present FinalPaymentAmount = ReurringPaymentAmount = FirstPaymentAmount


FirstPaymentAmount Mandatory

See Limits section at end of document




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

FinalPaymentDateTime Mutually exclusive with presence of NumberOfPayments; one and only one must be present

Must be > tomorrow

Must be > FirstPaymentDateTime


RecurringPaymentDateTime Must be > tomorrow and ≤ 365 days ahead

Must be > FirstPaymentDateTime





Permitted Frequency Values

IntrvlWkDay:01:01 Every Monday

IntrvlWkDay:01:02 Every Tuesday

IntrvlWkDay:01:03 Every Wednesday

IntrvlWkDay:01:04 Every Thursday

IntrvlWkDay:01:05 Every Friday

-

IntrvlWkDay:02:01 Every 2 Weeks - Mon.

IntrvlWkDay:02:02 Every 2 Weeks - Tue.

IntrvlWkDay:02:03 Every 2 Weeks - Wed.

IntrvlWkDay:02:04 Every 2 Weeks - Thu.

IntrvlWkDay:02:05 Every 2 Weeks - Fri.

-

IntrvlMnthDay:01:01 Monthly - 1st

IntrvlMnthDay:01:02 Monthly - 2nd

IntrvlMnthDay:01:03 Monthly - 3rd

IntrvlMnthDay:01:04 Monthly - 4th


















IntrvlMnthDay:01:22 Monthly - 22nd

IntrvlMnthDay:01:23 Monthly - 23rd





32 PUBLIC





-

IntrvlMnthDay:03:01 1 Jan,Apr,Jul,Oct

IntrvlMnthDay:03:01 1 Feb,May,Aug,Nov

IntrvlMnthDay:03:01 1 Mar,Jun,Sep,Dec



























































































-

IntrvlMnthDay:12:01 Yearly

33 PUBLIC

Confirmation of Funds 3.1.0

PUBLIC

Confirmation of Funds Summary v3.1.0

Updated 10-03-19


The following Confirmation of Funds endpoints are implemented:

Resource Endpoints Implemented

funds-confirmation-consent POST /funds-confirmation-consents

GET /funds-confirmation-consents/{ConsentId}

DELETE /funds-confirmation-consents/{ConsentId}

Y

Y

Y

funds-confirmation POST /funds-confirmations Y

35 PUBLIC

General

36 PUBLIC

Limits

Updated 10-03-19

Retail Limits

Brand Area Daily LImit

HSBC Retail Daily Remitter Limit £25,000

Daily Beneficiary Limit £25,000

Faster Payment Limit (Per Transaction)

£25,000

First Direct Daily Remitter Limit £250,000

Daily Beneficiary Limit £250,000


£49,999.99

M&S Bank Daily Remitter Limit No Limit

Daily Beneficiary Limit No Limit


£10,000

37 PUBLIC

Commerical Limits

User Payment Type Daily LImit

Primary User CHAPS £1.5m

BACS £100,000

International £100,000

FPS £100,000

Combined £1.5m

Secondary User CHAPS As defined by primary user

BACS As defined by primary user

International As defined by primary user

FPS As defined by primary user

Combined As defined by primary user

38 PUBLIC

Versions and Deprecation

Updated 26-04-19

Deprecation

HSBC intends to deprecate the Accounts and Transactions 1.1 endpoints on 30 June 2019 (separate

communcations will be issued in relation to this matter). HSBC retains the right to delay deprecation and/or not

deprecate an API at its sole discretion and without notice.

From 15 march 2019, defect fixing on Accounts and Transactions 1.will be limited to critical and security-related

items

HSBC encourages developers to only use the v2.0.0 onwards for new registrations

Parallel Running

V1, v2 and v3.1 APIs co-exist in parallel; subject to the deprecation notice above.

HSBC encourages developers to only use a single version of an API and not combine them.

The results of previous POST /account-requests messages are compatible with fulfilment endpoints of later

versions, subject to the relevant consent having being possible in the prior POST /account-requests; for

example, if the TPP wishes to access the scheduled-payments API, a v2 or later POST /account-requests must

be submitted with the relevant permission, as that did not exist in the v1 POST /account-requests.

HSBC Personal and Business Separation

Prior to Separation

HSBC exposes a combined set of endpoints for HSBC personal and HSBC business, with a single base URL.

After Separation

HSBC exposes a separate set of endpoints for HSBC personal and HSBC business, with two base URLs. The

HSBC personal base URL is the same as the combined URL. The HSBC business URL is new.

TPPs working with both personal and business customers will have to distinguish between HSBC personal and

HSBC business at the bank selection stage of their journey. This is because a different set of endpoints (leading

to a separate redirection journey) will have to be called for each customer group.

TPPs working with HSBC business customers will have to register a new Client ID with the new HSBC business

identifier, as it will have a distinct URL, software statement and consent store. They will also have to associate

their new Client ID with consents for business customers. As a result, any existing lasting consents for business

customers will have to be recreated because each consent is associated with a unique Client ID.

TPPs working with personal HSBC customers only are not required to make any changes.

URLs are listed on the official OBIE website with the HSBC-specific pages under the following location

https://openbanking.atlassian.net/wiki/spaces/AD/pages/89948737/ASPSP+Implementation+Guides

https://openbanking.atlassian.net/wiki/spaces/AD/pages/89948737/ASPSP+Implementation+Guides

39 PUBLIC

Disclaimer

This document contains information about the current functioning of certain of HSBC Group's Open Banking API

endpoints as at the date of publication (26-04-19). While we have taken reasonable steps to ensure the

accuracy, correctness and completeness of the information contained in this document, information is provided

on an "as is" basis and we do not give or make any warranty or representation 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.

Open Banking - developer.hsbc.com · HSBC has made all reasonable efforts to apply the OBIE...

Documents

Transcript of Open Banking - developer.hsbc.com · HSBC has made all reasonable efforts to apply the OBIE...