# Transactions Service API

Transactions Service provides raw and Open Banking-mapped account transaction history.

Authenticated history operations accept a verified `neosession` cookie, an `X-HSBC-Cust-Id` header when no cookie is present, or a B2B bearer token.

Operations:
- `GET /v1/transactions/history` - raw HSBCnet transaction-history response.
- `GET /v2/transactions/history` - paginated Open Banking-mapped transaction history.
- `/v1/test-transactions` - development and test-only in-memory transaction-store operations.

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

### GET /v1/transactions/history

**Get raw HSBCnet-compatible transaction history**

Returns transaction history in the raw HSBCnet-compatible `responseBody` and `stmtTranList` structure. Use header `test: 1` to return seeded in-memory data instead of calling a downstream service. Configured synthetic customer IDs are served from test-data-viewer automatically, bypassing DSP and HSBCnet, and are adapted to the same raw response structure.

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. |
| `lookbackDays` | query | integer | Number of days of transaction history to request. |


#### Responses

- **200** — Raw transaction history 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/v1/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/v1/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/v1/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/v1/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
{
  "responseBody": {
    "accountId": "GBHRFBCA40117703000087",
    "totalCount": "1",
    "pagingInfo": {
      "startIndex": "0",
      "endIndex": "0",
      "isMoreRec": "N"
    },
    "sortInfo": {
      "sortColumn": "PD",
      "sortOrder": "D"
    },
    "stmtTranList": [
      {
        "lastUpdtTmStmp": "2026-08-04T09:44:48.427694Z",
        "bosPostDt": "2026-08-03",
        "seqNo": "1",
        "bosLastTmStmp": "2026-08-04T10:44:48Z",
        "narrative": {
          "rawNarrative": "/REMI/Example remittance narrative",
          "shortNarrative": "N",
          "normalizedNarrative": [
            "/REMI/Example remittance narrative"
          ]
        },
        "bosPostTmStamp": "07.42.32",
        "amt": "-67.89",
        "rvrslInd": "N",
        "type": {
          "isoFamCode": "MDOP",
          "cfonbCode": "44",
          "bosCode": "TT",
          "orginalCode": "-0072",
          "btrCode": "TT",
          "baiCode": "0495",
          "isoDomnCode": "PMNT",
          "swiftCode": "NTRF",
          "isoSubFamCode": "OTHR"
        },
        "tC": "S",
        "crDbInd": "D",
        "ref": {
          "bank": "RBE03086K8JOQ60W",
          "channel": "RBE03086K8JOQ60W",
          "customer": "Example customer reference"
        },
        "postDate": "2026-08-03",
        "blendedTransactionParty": "Example remittance party",
        "blendedTransactionReference": null,
        "valDt": "2026-08-03",
        "openingBalance": "",
        "runningBalance": "",
        "closingBalance": ""
      }
    ]
  },
  "statusCode": "200"
}
```


---

### 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"
  }
}
```


---

### GET /v1/test-transactions

**Get seeded transactions**

Returns the transactions in the in-memory test store for a customer and account. This endpoint is intended for development and testing only and does not require authentication.

#### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `customerId` | query | string *(required)* | Customer identifier used to scope the in-memory test store. |
| `accountId` | query | string *(required)* | Account identifier used to scope the in-memory test store. |


#### Responses

- **200** — Seeded transactions retrieved successfully
- **400** — Invalid test-store request.
- **401** — Unauthorized — authentication credentials missing or invalid
- **403** — Forbidden — insufficient permissions for this resource
- **500** — Internal server error


#### Examples

```bash
curl "https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```javascript
const response = await fetch("https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions", {
  headers: {
      "Authorization": "Bearer YOUR_TOKEN"
  },
});

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

```python
import requests

url = "https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}

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/v1/test-transactions"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .GET()
    .build();

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

#### Example response

```json
{
  "responseBody": {
    "accountId": "GBHRFBCA40117703000087",
    "pagingInfo": {
      "startIndex": "0",
      "endIndex": "0",
      "isMoreRec": "N"
    },
    "sortInfo": {
      "sortColumn": "PD",
      "sortOrder": "D"
    },
    "stmtTranList": [
      {
        "postDate": "2026-07-07",
        "seqNo": "1",
        "amt": "-3.20",
        "crDbInd": "D"
      }
    ]
  }
}
```


---

### POST /v1/test-transactions

**Add or replace a seeded transaction**

Adds a transaction to the in-memory test store. Supplying an existing `index` for the same customer and account replaces that entry in place. This endpoint is intended for development and testing only and does not require authentication.

#### Request body

Content type: `application/json`

| Field | Type | Description |
|---|---|---|
| `customerId` | string *(required)* | Customer identifier used to scope the seed store. |
| `accountId` | string *(required)* | Account identifier used to scope the seed store. |
| `currency` | string | Currency used to label mapped Amount.Currency values. |
| `index` | integer | Optional positive index. Reusing an index replaces that entry in place. |
| `transaction` | object *(required)* | Raw HSBCnet stmtTranList entry. It must contain crDbInd, amt, and either postDate or bosPostDt. |


#### Responses

- **200** — Transaction added or replaced successfully
- **400** — Invalid test-store request.
- **401** — Unauthorized — authentication credentials missing or invalid
- **403** — Forbidden — insufficient permissions for this resource
- **500** — Internal server error


#### Examples

```bash
curl -X POST "https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ ... }'
```

```javascript
const response = await fetch("https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions", {
  method: "POST",
  headers: {
      "Authorization": "Bearer YOUR_TOKEN"
  },
  body: JSON.stringify({ /* ... */ }),
});

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

```python
import requests

url = "https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}

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/yi-transactions-service/v1/test-transactions"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .POST(HttpRequest.BodyPublishers.ofString("{ ... }"))
    .build();

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

#### Example response

```json
{
  "message": "Transaction added"
}
```


---

### DELETE /v1/test-transactions

**Delete seeded transactions**

Removes all in-memory transactions for a customer and account. This endpoint is intended for development and testing only and does not require authentication.

#### Parameters

| Name | In | Type | Description |
|---|---|---|---|
| `customerId` | query | string *(required)* | Customer identifier used to scope the in-memory test store. |
| `accountId` | query | string *(required)* | Account identifier used to scope the in-memory test store. |


#### Responses

- **200** — Seeded transactions deleted successfully
- **400** — Invalid test-store request.
- **401** — Unauthorized — authentication credentials missing or invalid
- **403** — Forbidden — insufficient permissions for this resource
- **500** — Internal server error


#### Examples

```bash
curl -X DELETE "https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

```javascript
const response = await fetch("https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions", {
  method: "DELETE",
  headers: {
      "Authorization": "Bearer YOUR_TOKEN"
  },
});

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

```python
import requests

url = "https://interact-uat.hsbc.com/yi-transactions-service/v1/test-transactions"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
}

response = requests.delete(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/v1/test-transactions"))
    .header("Authorization", "Bearer YOUR_TOKEN")
    .DELETE()
    .build();

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

#### Example response

```json
{
  "message": "Transactions deleted"
}
```