# Payments API

Base URL: `https://interact-uat.hsbc.com/payment-service/`

### 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 | 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 |
|---|---|---|
| `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` | string *(required)* | OW = outward; IW = inward. |
| `paymentType` | string | Required when paymentDirection is OW. |
| `account` | object *(required)* |  |
| `reference` | string |  |
| `msgtype` | string |  |


#### Responses

- **200** — The event history for the requested payment instruction
- **400** — Invalid request — for example, both uetr and payId are absent, paymentDirection is not OW or IW, or required account fields 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


#### Examples

```bash
curl -X POST "https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/events" \
  -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/events", {
  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/events"
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/events"))
    .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());
```