# Payments API

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 | Type | Description |
|---|---|---|---|
| `X-HSBC-Request-Correlation-Id` | header | string | 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

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `paymentDirection` | string *(required)* | 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


#### Examples

```bash
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 '{ ... }'
```

```javascript
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();
```

```python
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())
```

```java
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());
```

#### Example response

```json
{
  "payments": [
    {}
  ],
  "retrievalStatus": "COMPLETE"
}
```