Payments API
Search payment instructions, track payment files, and retrieve payment event history for authenticated customers. All operations require a valid NEO session cookie.
Base URL:
https://interact-uat.hsbc.com/payment-service/
POST
/api/v0/payment-instructions/query
Search payment instructions
Returns the payment instructions the authenticated customer is entitled to, filtered by the criteria in the request body. Results are aggregated across multiple payment data sources.
Note: this path uses the action suffix /query because the search criteria cannot be expressed as query parameters — it is an action on the payment instructions collection rather than a direct resource lookup.
Parameters
| Name | In | Description |
|---|---|---|
|
X-HSBC-Request-Correlation-Id
string |
header | Optional trace identifier forwarded to downstream services and recorded in logs. Include this value when raising support requests. A UUID is recommended; auto-generated when not supplied. |
Request Body application/json
| Field | Description |
|---|---|
|
paymentDirection
required
string |
Required. OW = outward payment; IW = inward payment. |
|
uetr
array |
Filter by one or more UETRs (Unique End-to-end Transaction References). |
|
valueDate
object |
|
|
amount
object |
|
|
accountNumberEquals
string |
Exact account number to match. |
|
accountNumberPartial
string |
Partial account number to match (substring). |
|
status
array |
Filter by one or more payment statuses. |
|
bankReference
array |
|
|
paymentType
array |
|
|
accountLocation
array |
|
|
bankLocation
array |
|
|
messageType
array |
|
|
accounts
array |
Filter by one or more specific accounts. |
|
fileUuid
string |
Filter by the identifier of the file the payment instructions belong to. |
|
requestOrigin
string |
Identifies the calling feature. Use SEARCH_UETR when searching by UETR, or SEARCH_PAYMENT_DETAILS when fetching details for a known payment. |
Responses
- 200 Payment instructions matching the supplied search criteria
-
400
Invalid request — for example,
paymentDirectionis missing or a date range is invalid - 401 Missing or invalid NEO session
- 403 The authenticated customer is not entitled to any accounts for the requested payment direction
- 429 Too many requests — rate limit exceeded
- 500 Unexpected server error
- 503 All payment data sources are temporarily unavailable
GET
/api/v0/payment-instructions/summary
Payment Status Summary
Returns the number of payment instructions grouped by status for the authenticated customer, optionally filtered by value-date range and payment direction. Counts are aggregated across multiple payment data sources.
Parameters
| Name | In | Description |
|---|---|---|
|
X-HSBC-Request-Correlation-Id
string |
header | Optional trace identifier forwarded to downstream services and recorded in logs. Include this value when raising support requests. A UUID is recommended; auto-generated when not supplied. |
|
status
array |
query | Optional and repeatable. Restrict the summary to these payment statuses. |
|
valueDateFrom
string |
query | Only include payments with a value date on or after this ISO-8601 date. Defaults to 90 days ago. |
|
valueDateTo
string |
query | Only include payments with a value date on or before this ISO-8601 date. Defaults to today. |
|
paymentDirection
string |
query | Optional. Restrict the summary to this payment direction. Defaults to OW. |
Responses
- 200 Payment instruction counts keyed by status
-
400
Invalid query parameters — for example,
valueDateFromis more than 90 days ago orvalueDateTois beforevalueDateFrom - 401 Missing or invalid NEO session
- 429 Too many requests — rate limit exceeded
- 500 Unexpected server error
- 503 All payment data sources are temporarily unavailable
- 403 Forbidden — insufficient permissions for this resource
POST
/api/v0/payment-instructions/events
Payment Event History
Returns the event history for a single payment instruction. The account, payment type, and direction are supplied in the request body and checked against the authenticated customer's entitlements.
Parameters
| Name | In | Description |
|---|---|---|
|
X-HSBC-Request-Correlation-Id
string |
header | Optional trace identifier forwarded to downstream services and recorded in logs. Include this value when raising support requests. A UUID is recommended; auto-generated when not supplied. |
Request Body application/json
| Field | Description |
|---|---|
|
uetr
string |
UETR of the payment instruction. At least one of uetr or payId must be provided. |
|
payId
string |
Payment identifier. At least one of uetr or payId must be provided. |
|
paymentDirection
required
string |
OW = outward; IW = inward. |
|
paymentType
string |
Required when paymentDirection is OW. |
|
account
required
object |
|
|
reference
string |
|
|
msgtype
string |
Responses
- 200 The event history for the requested payment instruction
-
400
Invalid request — for example, both
uetrandpayIdare absent,paymentDirectionis notOWorIW, or requiredaccountfields are missing - 401 Missing or invalid NEO session
- 403 The authenticated customer is not entitled to view events for the requested account
- 429 Too many requests — rate limit exceeded
- 500 Unexpected server error
- 503 The payment event service is temporarily unavailable
GET
/api/v0/payment-files
Payment File List
Returns the payment files for the authenticated customer, optionally filtered by creation-date range, file status, file name, or file reference.
Parameters
| Name | In | Description |
|---|---|---|
|
X-HSBC-Request-Correlation-Id
string |
header | Optional trace identifier forwarded to downstream services and recorded in logs. Include this value when raising support requests. A UUID is recommended; auto-generated when not supplied. |
|
fromMillis
long |
query | Only include files created on or after this instant (ISO-8601 UTC). When omitted, no lower bound is applied. |
|
toMillis
long |
query | Only include files created on or before this instant (ISO-8601 UTC). When omitted, no upper bound is applied. |
|
fileStatus
array |
query | Optional and repeatable. Restrict results to these file statuses. When omitted, all statuses are returned. |
|
fileName
string |
query | Optional. Restrict results to files matching this file name. |
|
fileReference
string |
query | Optional. Restrict results to files matching this file reference. |
Responses
- 200 Payment files matching the supplied filters
- 401 Missing or invalid NEO session
- 429 Too many requests — rate limit exceeded
- 500 Unexpected server error
- 503 The payment file service is temporarily unavailable
- 400 Bad request — invalid or missing parameters
- 403 Forbidden — insufficient permissions for this resource
GET
/api/v0/payment-files/summary
File Status Summary
Returns the number of payment files grouped by status for the authenticated customer, optionally filtered by creation-date range and file status.
Parameters
| Name | In | Description |
|---|---|---|
|
X-HSBC-Request-Correlation-Id
string |
header | Optional trace identifier forwarded to downstream services and recorded in logs. Include this value when raising support requests. A UUID is recommended; auto-generated when not supplied. |
|
fileStatus
array |
query | Optional and repeatable. Restrict the summary to these file statuses. When omitted, all statuses are counted. |
|
creationDateFrom
string |
query | Only count files created on or after this instant (ISO-8601 UTC). |
|
creationDateTo
string |
query | Only count files created on or before this instant (ISO-8601 UTC). |
Responses
- 200 Payment file counts keyed by status
- 401 Missing or invalid NEO session
- 429 Too many requests — rate limit exceeded
- 500 Unexpected server error
- 503 The payment file service is temporarily unavailable
- 400 Bad request — invalid or missing parameters
- 403 Forbidden — insufficient permissions for this resource
GET
/api/v0/payment-files/statuses/{transactionId}
Payment Status Timeline
Returns the ordered status timeline for a single payment instruction for the authenticated customer. The file identifier must be supplied as the fileUuid query parameter.
Parameters
| Name | In | Description |
|---|---|---|
|
X-HSBC-Request-Correlation-Id
string |
header | Optional trace identifier forwarded to downstream services and recorded in logs. Include this value when raising support requests. A UUID is recommended; auto-generated when not supplied. |
|
transactionId
required
string |
path | The identifier of the payment instruction whose status timeline should be returned. |
|
fileUuid
required
string |
query | The identifier of the file the payment instruction belongs to. |
Responses
- 200 The status timeline for the requested payment instruction
-
400
fileUuidis missing or blank - 401 Missing or invalid NEO session
- 429 Too many requests — rate limit exceeded
- 500 Unexpected server error
- 503 The payment file service is temporarily unavailable
- 403 Forbidden — insufficient permissions for this resource
GET
/api/v0/payment-files/timeline/{fileUuid}
File Status Timeline
Returns the ordered status timeline for a single payment file for the authenticated customer.
Parameters
| Name | In | Description |
|---|---|---|
|
X-HSBC-Request-Correlation-Id
string |
header | Optional trace identifier forwarded to downstream services and recorded in logs. Include this value when raising support requests. A UUID is recommended; auto-generated when not supplied. |
|
fileUuid
required
string |
path | The identifier of the payment file whose status timeline should be returned. |
Responses
- 200 The status timeline for the requested payment file
-
400
fileUuidis blank - 401 Missing or invalid NEO session
- 429 Too many requests — rate limit exceeded
- 500 Unexpected server error
- 503 The payment file service is temporarily unavailable
- 403 Forbidden — insufficient permissions for this resource