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:
Response:

​
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:

​
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:
Response:

​
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:
Response:

​
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:

​
Error Responses

All endpoints may return the following error responses: 401 Unauthorized
404 Not Found
409 Conflict

​
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