> ## Documentation Index > Fetch the complete documentation index at: https://docs.lite.sa/llms.txt > Use this file to discover all available pages before exploring further. # Register a settlement account > Registers a seller bank account that can receive payouts. The IBAN is verified with the bank, the name must match the account holder, and the IBAN must belong to `national_id`. All checks run synchronously; a `201` means the account can receive payouts immediately. ## OpenAPI ````yaml /openapi/account-settlement.json post /settlements/settlement-accounts openapi: 3.1.0 info: title: lite - Account Settlement version: 1.0.0 servers: - url: https://api.lite.sa/v1 description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Settlement Windows description: Manage settlement windows for merchant payout cycles - name: Transactions description: Query settlement transactions and their details - name: Settlement description: >- Register verified seller settlement accounts, view acceptance account balances, and pay out on demand from an acceptance account to a settlement account paths: /settlements/settlement-accounts: servers: - url: https://api.lite.sa description: Production post: tags: - Settlement summary: Register a settlement account description: > Registers a seller bank account that can receive payouts. The IBAN is verified with the bank, the name must match the account holder, and the IBAN must belong to `national_id`. All checks run synchronously; a `201` means the account can receive payouts immediately. operationId: lite.settlement.createSettlementAccount parameters: - $ref: '#/components/parameters/x-idempotency-key-required' - $ref: '#/components/parameters/x-correlation-id' requestBody: $ref: '#/components/requestBodies/CreateSettlementAccount' responses: '201': $ref: '#/components/responses/SettlementAccountDetails' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/SettlementAccountRejected' '500': $ref: '#/components/responses/InternalServerError' '503': $ref: '#/components/responses/ProviderUnavailable' security: - ApiKeyAuth: [] components: parameters: x-idempotency-key-required: name: x-idempotency-key in: header required: true description: >- Unique key for idempotent request processing. Retrying with the same key and body returns the original result; reusing a key with a different body returns 409. schema: type: string format: uuid example: baf6a8e2-0c89-46ef-9ca5-faa65b99bcd5 x-correlation-id: name: x-correlation-id in: header required: false description: >- Unique identifier for request tracing. Generated by the client or server if not provided. schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 requestBodies: CreateSettlementAccount: description: Settlement account details required: true content: application/json: schema: $ref: '#/components/schemas/CreateSettlementAccountRequest' responses: SettlementAccountDetails: description: Settlement account details. content: application/json: schema: $ref: '#/components/schemas/SettlementAccount' BadRequest: description: > The request was invalid or malformed. Returned when: - Request validation fails (missing required fields, invalid field formats) - Payment details do not match the session (amount, currency, order reference mismatch) - The operation is not allowed given the current resource state content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Unauthorized: description: | Authentication failed — missing or invalid token. Returned when: - The JWT bearer token is missing, expired, or has an invalid signature - The API key is missing or invalid - The authenticated session token is invalid content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Forbidden: description: > Request blocked by security policy. Returned when: - A security threat is detected (SQL injection, XSS, NoSQL injection, LDAP injection, path traversal) - Header injection or suspicious headers are detected - The request payload exceeds the maximum allowed size - Geo-region validation fails (user country does not match client region) content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' Conflict: description: | The request conflicts with the current state of the resource. Returned when: - A resource with the same unique key already exists - The operation cannot be performed due to a conflicting state content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' SettlementAccountRejected: description: > The settlement account could not be verified with the bank. Error codes: - `ACCOUNT_VERIFICATION_FAILED`: the bank could not verify the IBAN - `ACCOUNT_NAME_MISMATCH`: the name does not match the account holder - `ACCOUNT_NAME_UNVERIFIABLE`: the bank did not return a name that can be matched - `ACCOUNT_OWNER_MISMATCH`: the IBAN does not belong to `national_id` content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalServerError: description: > An unexpected error occurred on the server. Returned when an unhandled exception or infrastructure failure prevents the request from being processed. Retry the request with exponential backoff. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' ProviderUnavailable: description: > The bank verification service is unavailable or timed out (`PROVIDER_UNAVAILABLE`). Retry with the same `x-idempotency-key`. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' schemas: CreateSettlementAccountRequest: type: object description: Request to register a settlement account (seller bank account) required: - name - national_id - iban properties: name: type: string description: Account holder name. Must match the name on the bank account. maxLength: 255 example: Mohammed Ali Alharbi national_id: type: string description: >- Account holder National ID (starts with 1) or Iqama number (starts with 2). Must own the IBAN. pattern: ^[12][0-9]{9}$ example: '1012345678' iban: type: string description: Saudi IBAN of the account holder pattern: ^SA[0-9]{2}[0-9A-Z]{20}$ example: SA0380000000608010167519 currency: type: string description: ISO 4217 currency code default: SAR enum: - SAR example: SAR SettlementAccount: type: object description: >- A settlement account (seller bank account) that can receive payouts from an acceptance account required: - id - status - name - masked_national_id - masked_iban - currency - created_at - updated_at properties: id: type: string format: uuid description: Unique settlement account identifier example: 4b0f6c1e-2d3a-4f5b-8c7d-9e0f1a2b3c4d status: type: string description: Settlement account status oneOf: - title: Active const: ACTIVE description: Verified and able to receive payouts - title: Deleted const: DELETED description: Removed by the merchant, can no longer receive payouts name: type: string description: Account holder name as submitted, verified against the bank records example: Mohammed Ali Alharbi masked_national_id: type: string description: Account holder National ID or Iqama number, masked example: 1*******78 masked_iban: type: string description: Account IBAN, masked example: SA03****************7519 currency: type: string description: ISO 4217 currency code example: SAR created_at: type: string format: date-time description: Timestamp when the account was registered example: '2026-09-29T10:00:00.000Z' updated_at: type: string format: date-time description: Timestamp of the last update example: '2026-09-29T10:00:00.000Z' ErrorResponse: type: object required: - error properties: error: type: object required: - code - message - timestamp properties: code: type: string description: Error code identifying the type of error example: PAYMENT_DETAILS_MISMATCH message: type: string description: Human-readable error description example: The request was invalid or malformed details: type: object description: Additional error details correlationId: type: string format: uuid description: Correlation ID for tracking the request example: 550e8400-e29b-41d4-a716-446655440000 timestamp: type: string format: date-time description: Timestamp when the error occurred example: '2024-12-16T10:30:00.000Z' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: API key for service-to-service or merchant authentication. BearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT Bearer token obtained from user authentication. Passed as Authorization: Bearer . ````