> ## Documentation Index
> Fetch the complete documentation index at: https://dvaultdocs.dukka.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlement API

> Manage transaction settlements and reconciliations

# Settlement API Documentation

## Overview

The Settlement API provides endpoints for managing settlement accounts and automatic settlement configurations for the wallet service.

## Base URL

`/api/v1/settlement`

## Authentication

All endpoints require authentication using an API key in the request headers:

* `X-API-KEY`: Your API key
* `X-Tenant-ID`: Tenant identifier (required for most endpoints)

## Endpoints

### Register Settlement Account

Register a new settlement account for a tenant.

**Endpoint:** `POST /register`

**Headers:**

* `X-API-KEY` (optional): API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Request Body:**

```json theme={null}
{
  "currency": "string",
  "bankCode": "string",
  "bankName": "string",
  "accountNumber": "string",
  "accountName": "string",
  "accountId": "string"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "settlementAccountId": "string",
    "tenantId": "string",
    "userId": "string",
    "currency": "string",
    "bankCode": "string",
    "bankName": "string",
    "accountNumber": "string",
    "accountName": "string"
  }
}
```

### Get Settlement Accounts

Retrieve settlement accounts with filtering and pagination.

**Endpoint:** `GET /accounts`

**Headers:**

* `X-API-KEY`: API key for authentication
* `X-Tenant-ID` (optional): Tenant identifier

**Query Parameters:**

* `settlementAccountId`: Filter by settlement account ID
* `tenantId`: Filter by tenant ID
* `userId`: Filter by user ID
* `currency`: Filter by currency
* `bankCode`: Filter by bank code
* `bankName`: Filter by bank name
* `accountNumber`: Filter by account number
* `accountName`: Filter by account name
* `page`: Page number (default: 0)
* `size`: Page size (default: 20)
* `sort`: Sort field and direction (e.g., "createdAt,desc")

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "settlementAccountId": "string",
        "tenantId": "string",
        "userId": "string",
        "currency": "string",
        "bankCode": "string",
        "bankName": "string",
        "accountNumber": "string",
        "accountName": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}
```

### Setup Auto Settlement

Configure automatic settlement for a settlement account.

**Endpoint:** `POST /auto-settlement`

**Headers:**

* `X-API-KEY`: API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Request Body:**

```json theme={null}
{
  "currency": "string",
  "accountId": "string",
  "settlementAccountId": "string",
  "duration": "T1|T2|WEEKLY|MONTHLY"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 201,
  "message": "string",
  "data": {
    "id": "number",
    "accountId": "string",
    "tenantId": "string",
    "userId": "string",
    "currency": "string",
    "settlementAccountId": "string",
    "duration": "string",
    "cronExpression": "string",
    "nextSettlementDate": "string",
    "previousSettlementDate": "string"
  }
}
```

### Update Auto Settlement Config

Update an existing auto settlement configuration.

**Endpoint:** `POST /update/{uuid}`

**Headers:**

* `X-API-KEY`: API key for authentication
* `X-Tenant-ID`: Tenant identifier

**Path Parameters:**

* `uuid`: Settlement account ID

**Request Body:**

```json theme={null}
{
  "currency": "string",
  "accountId": "string",
  "settlementAccountId": "string",
  "duration": "T1|T2|WEEKLY|MONTHLY"
}
```

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "id": "number",
    "accountId": "string",
    "tenantId": "string",
    "userId": "string",
    "currency": "string",
    "settlementAccountId": "string",
    "duration": "string",
    "cronExpression": "string",
    "nextSettlementDate": "string",
    "previousSettlementDate": "string"
  }
}
```

### Get Auto Settlement Configs

Retrieve auto settlement configurations with filtering and pagination.

**Endpoint:** `GET /auto-settlement-configs`

**Headers:**

* `X-API-KEY`: API key for authentication
* `X-Tenant-ID` (optional): Tenant identifier

**Query Parameters:**

* `settlementAccountId`: Filter by settlement account ID
* `accountId`: Filter by account ID
* `userId`: Filter by user ID
* `tenantId`: Filter by tenant ID
* `currency`: Filter by currency
* `page`: Page number (default: 0)
* `size`: Page size (default: 20)
* `sort`: Sort field and direction (e.g., "createdAt,desc")

**Response:**

```json theme={null}
{
  "statusCode": 200,
  "message": "string",
  "data": {
    "content": [
      {
        "id": "number",
        "accountId": "string",
        "tenantId": "string",
        "userId": "string",
        "currency": "string",
        "settlementAccountId": "string",
        "duration": "string",
        "cronExpression": "string",
        "nextSettlementDate": "string",
        "previousSettlementDate": "string"
      }
    ],
    "totalElements": "number",
    "totalPages": "number",
    "size": "number",
    "number": "number"
  }
}
```

## Error Responses

All endpoints may return the following error responses:

**401 Unauthorized**

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
```

**404 Not Found**

```json theme={null}
{
  "statusCode": 404,
  "message": "Resource not found",
  "data": null
}
```

**409 Conflict**

```json theme={null}
{
  "statusCode": 409,
  "message": "Duplicate settlement account",
  "data": null
}
```

## Notes

* All timestamps are in ISO-8601 format
* Settlement durations:
  * T1: Next-day settlement
  * T2: Two-day settlement
  * WEEKLY: Weekly settlement
  * MONTHLY: Monthly settlement
* Platform admins cannot create settlement accounts
* Account numbers are masked in responses for security
* Auto settlement configurations use cron expressions for scheduling
* Settlement accounts must be unique per tenant, user, currency, and account number
* Account currency must match the settlement account currency
* Auto settlement configurations are tenant-specific
* Failed settlements can be retried manually
* Settlement history is maintained for audit purposes