Skip to main content

​
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: 
{
  "currency": "string",
  "bankCode": "string",
  "bankName": "string",
  "accountNumber": "string",
  "accountName": "string",
  "accountId": "string"
}
Response: 
{
  "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: 
{
  "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: 
{
  "currency": "string",
  "accountId": "string",
  "settlementAccountId": "string",
  "duration": "T1|T2|WEEKLY|MONTHLY"
}
Response: 
{
  "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: 
{
  "currency": "string",
  "accountId": "string",
  "settlementAccountId": "string",
  "duration": "T1|T2|WEEKLY|MONTHLY"
}
Response: 
{
  "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: 
{
  "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 
{
  "statusCode": 401,
  "message": "Unauthorized",
  "data": null
}
404 Not Found 
{
  "statusCode": 404,
  "message": "Resource not found",
  "data": null
}
409 Conflict 
{
  "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