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

# Real-time Settlement

> Enable real-time balance settlements from agents or representatives in the field directly to your central account.

## Introduction

The Real-time Settlement feature establishes a direct payment channel between your agents in the field and your central system. As agents are equipped with Flouci, this system allows them to send money to you and instantly have their balance reflected in real-time.

This solution is designed to:

* **Reduce Risk:** Block agents who have accumulated a high cash balance.
* **Optimize Resources:** Facilitate seamless reconciliation between your accounts and your agents' balances.

This is achieved via two dedicated API endpoints: a `check` endpoint to validate an agent's status and a `confirm` endpoint to log the payment details in your system.

## Authentication

To secure the communication between Flouci and your system, you will need to provide a JWT token. This token must be included in the `Authorization` header of every API request. These tokens will need to be renewed periodically.

<ParamField header="Authorization" type="string" required>
  Your JWT token for authenticating the request. Format: `Bearer {JWT_TOKEN}`
</ParamField>

***

## Check Agent Endpoint

This endpoint is used to check if an agent has a valid ID and to retrieve their current due amount before a payment is initiated. The agent ID can be any easily identifiable string, such as a phone number, a national ID number, or a custom alphanumeric code.

<RequestExample>
  ```bash cURL theme={null}
  # GET /flouci/check/{agentId}
  curl -X GET 'https://<YOUR_DOMAIN>/flouci/check/AGENT12345' \
    -H 'Authorization: Bearer {JWT_TOKEN}'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "code": "0",
    "desc": "Agent Name",
    "amount": "250000" 
  }
  ```
</ResponseExample>

### Path Parameters

<ParamField path="agentId" type="string" required>
  The unique identifier for the agent.
</ParamField>

### Response Body

<ResponseField name="code" type="string" required>
  Indicates the status of the agent ID.

  * `"0"`: Valid agent ID.
  * `"1"`: Invalid agent ID.
</ResponseField>

<ResponseField name="desc" type="string" required>
  The agent's full name. This will be an empty string if the agent ID is invalid.
</ResponseField>

<ResponseField name="amount" type="string" required>
  The total amount due from the agent, in millimes. The agent can choose to pay this amount or a different one.
</ResponseField>

### HTTP Status Codes

* `200 OK`: Request was successful.
* `403 Forbidden`: Unauthorized request (e.g., invalid JWT token).

***

## Confirm Payment Endpoint

This endpoint is called to confirm that the payment details were successfully received and stored by your system after the agent completes a transaction.

<RequestExample>
  ```bash cURL theme={null}
  # POST /flouci/confirm
  curl -X POST 'https://<YOUR_DOMAIN>/flouci/confirm' \
    -H 'Authorization: Bearer {JWT_TOKEN}' \
    -H 'Content-Type: application/json' \
    -d '{
          "transactionId": "TXN_1a2b3c4d5e6f",
          "agentId": "AGENT12345",
          "amount": 50000
        }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "code": "0"
  }
  ```
</ResponseExample>

### Request Body

<ParamField body="transactionId" type="string" required>
  The unique ID for the Flouci transaction.
</ParamField>

<ParamField body="agentId" type="string" required>
  The unique identifier for the agent who made the payment.
</ParamField>

<ParamField body="amount" type="integer" required>
  The amount paid by the agent, in millimes.
</ParamField>

### Response Body

<ResponseField name="code" type="string" required>
  Indicates the status of the confirmation.

  * `"0"`: Transaction successfully stored.
  * `"1"`: Invalid agent ID.
  * `"2"`: Invalid amount.
  * `"3"`: Invalid transaction (e.g., transaction ID already registered).
</ResponseField>

### HTTP Status Codes

* `200 OK`: Request was successful.
* `403 Forbidden`: Unauthorized request (e.g., invalid JWT token).