# Transactions Service API

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

### GET /v2/transactions/history

**Get v2 transaction history**

Returns paginated Open Banking-mapped transactions for a single account in the standard `data`/`meta` envelope. Set `includeRawHSBCnetData=true` to include raw source fields in each transaction. Use header `test: 1` to return seeded in-memory data instead of calling the upstream service. Customer IDs mapped in the internal test-data hashmap are served from test-data-viewer automatically and mapped back to the same response shape.

Requires authentication: **neoSessionCookie** (cookie) or **xHSBCCustIdHeader** (header) or **b2bBearerToken** (header)


#### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `X-HSBC-Account-Id` | header | string *(required)* | HSBC account identifier for the requested transaction history. |
| `X-HSBC-Account-Currency` | header | string | Optional account currency used to label returned amounts. |
| `X-HSBC-Request-Correlation-Id` | header | string | Optional caller-provided correlation identifier. |
| `X-HSBC-CUSTID` | header | string | Customer identifier used for the customer-id header authentication journey. |
| `test` | header | string | Set to 1 to serve seeded in-memory data instead of calling the upstream transaction-history service. |
| `offset` | query | integer | Zero-based starting index for pagination. |
| `limit` | query | integer | Maximum number of records to return. |
| `includeRawHSBCnetData` | query | boolean | When true, includes a normalized raw HSBCnet data object in each mapped transaction. |
| `lookbackDays` | query | integer | Number of days of transaction history to request. |


#### Responses

- **200** — Transactions retrieved successfully
- **400** — Invalid request parameters or missing required headers.
- **401** — Missing or invalid authentication.
- **403** — Caller is authenticated but not entitled for the requested account.
- **500** — Unexpected service failure.
- **502** — Downstream transaction-history service returned an invalid or failing response.


#### Examples

```bash
curl "https://interact-uat.hsbc.com/yi-transactions-service/v2/transactions/history" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "X-HSBC-Account-Id: YOUR_X_HSBC_ACCOUNT_ID" \
  -H "X-HSBC-Account-Currency: YOUR_X_HSBC_ACCOUNT_CURRENCY" \
  -H "X-HSBC-Request-Correlation-Id: YOUR_X_HSBC_REQUEST_CORRELATION_ID" \
  -H "X-HSBC-CUSTID: YOUR_X_HSBC_CUSTID" \
  -H "test: YOUR_TEST"
```

```javascript
const response = await fetch("https://interact-uat.hsbc.com/yi-transactions-service/v2/transactions/history", {
  headers: {
      "Authorization": "Bearer YOUR_TOKEN",
      "X-HSBC-Account-Id": "YOUR_X_HSBC_ACCOUNT_ID",
      "X-HSBC-Account-Currency": "YOUR_X_HSBC_ACCOUNT_CURRENCY",
      "X-HSBC-Request-Correlation-Id": "YOUR_X_HSBC_REQUEST_CORRELATION_ID",
      "X-HSBC-CUSTID": "YOUR_X_HSBC_CUSTID",
      "test": "YOUR_TEST"
  },
});

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

```python
import requests

url = "https://interact-uat.hsbc.com/yi-transactions-service/v2/transactions/history"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "X-HSBC-Account-Id": "YOUR_X_HSBC_ACCOUNT_ID",
    "X-HSBC-Account-Currency": "YOUR_X_HSBC_ACCOUNT_CURRENCY",
    "X-HSBC-Request-Correlation-Id": "YOUR_X_HSBC_REQUEST_CORRELATION_ID",
    "X-HSBC-CUSTID": "YOUR_X_HSBC_CUSTID",
    "test": "YOUR_TEST",
}

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/yi-transactions-service/v2/transactions/history"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .header("X-HSBC-Account-Id", "YOUR_X_HSBC_ACCOUNT_ID")
    .header("X-HSBC-Account-Currency", "YOUR_X_HSBC_ACCOUNT_CURRENCY")
    .header("X-HSBC-Request-Correlation-Id", "YOUR_X_HSBC_REQUEST_CORRELATION_ID")
    .header("X-HSBC-CUSTID", "YOUR_X_HSBC_CUSTID")
    .header("test", "YOUR_TEST")
    .GET()
    .build();

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

#### Example response

```json
{
  "data": {
    "transactions": [
      {
        "AccountId": "QA72BBME000000000001000033001",
        "TransactionId": "BANK-REF-123456",
        "TransactionReference": "CUST-REF-7890",
        "StatementReference": [],
        "TransactionInformation": "Salary payment",
        "CreditDebitIndicator": "Credit",
        "Status": "BOOK",
        "BookingDateTime": "2026-08-02T00:00:00Z",
        "ValueDateTime": "2026-08-02T00:00:00Z",
        "Amount": {
          "Amount": "1250.00",
          "Currency": "GBP"
        },
        "BankTransactionCode": {
          "Code": "CRED",
          "SubCode": "SALA"
        },
        "ProprietaryBankTransactionCode": {
          "Issuer": "HSBC",
          "Code": "TFR"
        },
        "BtrCode": "TFR",
        "SeqNo": "1",
        "BlendedTransactionParty": null,
        "BlendedTransactionReference": null
      }
    ]
  },
  "meta": {
    "pagination": {
      "totalResults": 1,
      "offset": 0,
      "limit": 500,
      "count": 1
    },
    "success": true,
    "message": "Transactions retrieved successfully",
    "status": 200,
    "timestamp": "2026-08-04T08:20:54Z"
  }
}
```