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, paymentDirection is 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

curl -X POST "https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/query" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "X-HSBC-Request-Correlation-Id: YOUR_X_HSBC_REQUEST_CORRELATION_ID" \ -H "Content-Type: application/json" \ -d '{ ... }'

const response = await fetch("https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/query", { method: "POST", headers: { "Authorization": "Bearer YOUR_TOKEN", "X-HSBC-Request-Correlation-Id": "YOUR_X_HSBC_REQUEST_CORRELATION_ID" }, body: JSON.stringify({ /* ... */ }), }); const data = await response.json();

import requests url = "https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/query" headers = { "Authorization": "Bearer YOUR_TOKEN", "X-HSBC-Request-Correlation-Id": "YOUR_X_HSBC_REQUEST_CORRELATION_ID", } response = requests.post(url, headers=headers, json={ # ... }) print(response.json())

HttpClient client = HttpClient.newHttpClient(); HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/query")) .header("Authorization", "Bearer YOUR_TOKEN") .header("X-HSBC-Request-Correlation-Id", "YOUR_X_HSBC_REQUEST_CORRELATION_ID") .POST(HttpRequest.BodyPublishers.ofString("{ ... }")) .build(); HttpResponse<String> response = client.send( request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body());