# Payments API

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

### 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 | 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. |
| `status` | query | array | Optional and repeatable. Restrict the summary to these payment statuses. |
| `valueDateFrom` | query | string | Only include payments with a value date on or after this ISO-8601 date. Defaults to 90 days ago. |
| `valueDateTo` | query | string | Only include payments with a value date on or before this ISO-8601 date. Defaults to today. |
| `paymentDirection` | query | string | 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, valueDateFrom is more than 90 days ago or valueDateTo is before valueDateFrom
- **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


#### Examples

```bash
curl "https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/summary" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-HSBC-Request-Correlation-Id: YOUR_X_HSBC_REQUEST_CORRELATION_ID"
```

```javascript
const response = await fetch("https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/summary", {
  headers: {
      "Authorization": "Bearer YOUR_TOKEN",
      "X-HSBC-Request-Correlation-Id": "YOUR_X_HSBC_REQUEST_CORRELATION_ID"
  },
});

const data = await response.json();
```

```python
import requests

url = "https://interact-uat.hsbc.com/payment-service/api/v0/payment-instructions/summary"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-HSBC-Request-Correlation-Id": "YOUR_X_HSBC_REQUEST_CORRELATION_ID",
}

response = requests.get(url, headers=headers)
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/summary"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .header("X-HSBC-Request-Correlation-Id", "YOUR_X_HSBC_REQUEST_CORRELATION_ID")
    .GET()
    .build();

HttpResponse<String> response = client.send(
    request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
```

#### Example response

```json
{
  "summary": {
    "statusCounts": {
      "RECEIVED_BY_BANK": 5,
      "FAILED": 2
    }
  },
  "meta": {
    "retrievalStatus": "COMPLETE"
  }
}
```