# Cancel Payment
Source: https://docs.flouci.com/api-reference/advanced-payment-flow/cancel-payment

Cancel a pre-authorized payment and release the reserved funds.

This endpoint cancels a pre-authorized payment and releases the reserved funds back to the customer's payment method. Use this when you decide not to capture the reserved funds.

<Warning>
  A pre-authorized payment can only be cancelled if it has not already been confirmed or cancelled.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/api/v2/cancel_payment' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>' \
    -d '{
      "payment_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
    }'
  ```
</RequestExample>

### Body

<ParamField type="string">
  The ID of the pre-authorized payment to cancel.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "result": {
      "payment_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "status": "cancelled",
      "cancelled_at": "2025-01-15T10:30:00Z"
    },
    "status": "success"
  }
  ```

  ```json Error theme={null}
  {
    "status": "error",
    "message": "Pre-auth payment cannot be cancelled",
    "code": "CANCELLATION_FAILED"
  }
  ```
</ResponseExample>


# Pay with Binding
Source: https://docs.flouci.com/api-reference/advanced-payment-flow/confirm-binding

Create a payment using an existing customer binding — no redirect needed.

This endpoint creates a payment using an existing binding. The customer's saved payment method is charged directly — no checkout redirect is needed (except for 3DS verification when required).

### Body

<ParamField type="string">
  The amount to be paid in millimes.
</ParamField>

<ParamField type="string">
  An ID for you to track the payment. This is a free field that Flouci doesn't check against.
</ParamField>

<ParamField type="boolean">
  Whether to accept card payments.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a successful payment (used if 3DS redirect is required).
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a failed payment (used if 3DS redirect is required).
</ParamField>

<ParamField type="string">
  The binding identifier returned from the initial [Create Binding](/api-reference/advanced-payment-flow/create-binding) payment.
</ParamField>

<ParamField type="string">
  The same unique internal identifier used when creating the binding.
</ParamField>

<ParamField type="integer">
  The card's CVC/CVV code for payment verification.
</ParamField>

<ParamField type="string">
  The webhook URL you want to receive payment confirmation on. Signed with `X-Flouci-Signature`; set `webhook_version` to `2` for a JSON event. See [Payment Webhooks](/api-reference/payment-webhooks).
</ParamField>

<ParamField type="URL">
  The URL of the image to display on the payment page.
</ParamField>

<ParamField type="integer">
  The session timeout in seconds.
</ParamField>

<Tip>
  Use the [Verify Payment](/api-reference/verify-transaction) endpoint to check the payment status, or listen for the webhook notification.
</Tip>


# Confirm Payment
Source: https://docs.flouci.com/api-reference/advanced-payment-flow/confirm-payment

Confirm a pre-authorized payment and capture the reserved funds.

This endpoint captures the reserved funds of a pre-authorized payment. You can confirm the full reserved amount or a partial amount less than or equal to the original pre-authorization.

<Info>
  If you specify an `amount` lower than the original pre-authorized amount, only that partial amount is captured and the remaining funds are released back to the customer.
</Info>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/api/v2/confirm_payment' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>' \
    -d '{
      "payment_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "amount": "8500"
    }'
  ```
</RequestExample>

### Body

<ParamField type="string">
  The ID of the pre-authorized payment to confirm.
</ParamField>

<ParamField type="string">
  The amount in millimes to capture. Must be less than or equal to the original pre-authorized amount. If omitted, the full pre-authorized amount is captured.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "result": {
      "payment_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "status": "confirmed",
      "amount": "8500",
      "confirmed_at": "2025-01-15T10:30:00Z"
    },
    "status": "success"
  }
  ```

  ```json Error theme={null}
  {
    "status": "error",
    "message": "Pre-auth payment cannot be confirmed",
    "code": "CONFIRMATION_FAILED"
  }
  ```
</ResponseExample>


# Create Binding
Source: https://docs.flouci.com/api-reference/advanced-payment-flow/create-binding

Link a customer's Flouci account to your application for future payments.

This endpoint initiates the binding process by creating a payment with a unique `client_id`. The first transaction links the customer's Flouci wallet or card to your application. Subsequent payments using the same `client_id` will use the saved payment method.

<RequestExample>
  ```bash cURL theme={null}
  curl --location 'https://developers.flouci.com/api/v2/generate_payment' \
    --header 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>' \
    --header 'Content-Type: application/json' \
    --data '{
      "amount": "40300",
      "developer_tracking_id": "<YOUR_TRACKING_ID>",
      "accept_card": true,
      "success_link": "https://example.com/success",
      "fail_link": "https://example.com/failure",
      "client_id": "<unique_internal_id>"
    }'
  ```
</RequestExample>

### Body

<ParamField type="string">
  The amount to be paid in millimes.
</ParamField>

<ParamField type="string">
  An ID for you to track the payment. This is a free field that Flouci doesn't check against.
</ParamField>

<ParamField type="boolean">
  Whether to accept card payments.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a successful payment.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a failed payment.
</ParamField>

<ParamField type="string">
  A unique internal identifier for the customer. This is the key that creates and references the binding — subsequent payments with the same `client_id` will use the saved payment method.
</ParamField>

<ParamField type="string">
  The webhook URL you want to receive payment confirmation on. Signed with `X-Flouci-Signature`; set `webhook_version` to `2` for a JSON event. See [Payment Webhooks](/api-reference/payment-webhooks).
</ParamField>

<ParamField type="URL">
  The URL of the image to display on the payment page.
</ParamField>

<ParamField type="integer">
  The session timeout in seconds.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "result": {
      "success": true,
      "payment_id": "FoPKKHqfQIKfBqhEj8M47A",
      "link": "https://flouci.com/pay/FoPKKHqfQIKfBqhEj8M47A",
      "developer_tracking_id": "<YOUR_TRACKING_ID>"
    },
    "name": "developers",
    "code": 0,
    "version": "v2"
  }
  ```

  ```json Error theme={null}
  {
    "result": {
      "status": 400,
      "message": "Bad Request"
    }
  }
  ```
</ResponseExample>

<Note>
  The customer completes this first payment through the Flouci checkout page. Once completed, the `client_id` is bound to their payment method for future use. You can get the Binding Id from the verify API after the payment is done.
</Note>


# Get Bindings
Source: https://docs.flouci.com/api-reference/advanced-payment-flow/get-bindings

Retrieve all bindings associated with a customer.

This endpoint returns the list of saved payment method bindings for a given `client_id`. Use it to check which bindings are available before initiating a [Pay with Binding](/api-reference/advanced-payment-flow/confirm-binding) request.

<RequestExample>
  ```bash cURL theme={null}
  curl --location --globoff 'https://developers.flouci.com/api/v2/bindings/list?client_id=<UNIQUE_INTERNAL_ID>' \
    --header 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>'
  ```
</RequestExample>

### Query Parameters

<ParamField type="string">
  The unique internal identifier used when creating the binding.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "result": {
      "success": true,
      "bindings": [
        {
          "binding_id": "6255d6ea-0e38-4b3e-98a6-fc4afa673f9f",
          "client_id": "3f861af8-0f0c-34ef-8c88-d8d110952ef7",
          "card_last_four": "4012",
          "card_brand": "Visa",
          "status": "active",
          "created_at": "2025-01-15T10:30:00Z"
        }
      ]
    },
    "status": "success"
  }
  ```

  ```json Error theme={null}
  {
    "result": {
      "status": 400,
      "message": "Invalid client_id"
    }
  }
  ```
</ResponseExample>


# Initiate Pre-Authorization
Source: https://docs.flouci.com/api-reference/advanced-payment-flow/initiate-pre-authorization

Pre-authorize a payment to be captured later.

Pre-Authorization is a payment process where a cardholder's funds are temporarily held to ensure the availability of the specified amount for a future transaction. This process involves verifying the card details and reserving the funds without actually transferring them, allowing merchants to confirm the card's validity and the customer's ability to pay.

Once the pre-authorization is approved, the funds are earmarked and can be captured later when the final transaction is completed, providing flexibility and security for both merchants and customers in managing payments.

## Initiate Pre-Authorization

This endpoint initiates a pre-authorization for a payment.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/api/v2/generate_payment' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>' \
    -d '{
      "amount": 1000,
      "success_link": "https://your-website.com/success",
      "fail_link": "https://your-website.com/fail",
      "webhook": "https://your-website.com/webhook",
      "developer_tracking_id": "YOUR_TRACKING_ID",
      "pre_authorization": true
    }'
  ```
</RequestExample>

### Body

<ParamField type="integer">
  The amount to be paid in millimes.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a successful payment.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a failed payment.
</ParamField>

<ParamField type="string">
  The webhook URL you want to receive payment confirmation on. Signed with `X-Flouci-Signature`; set `webhook_version` to `2` for a JSON event. See [Payment Webhooks](/api-reference/payment-webhooks).
</ParamField>

<ParamField type="string">
  An ID for you to track the payment. This is a free field that Flouci doesn't check against.
</ParamField>

<ParamField type="boolean">
  Must be set to `true` to create a pre-authorization.
</ParamField>

<ParamField type="boolean">
  Whether to accept card payments.
</ParamField>

<ParamField type="URL">
  The URL of the image to display on the payment page. This field is optional, and the default image is the image of the merchant in the Flouci portal.
</ParamField>

<ParamField type="integer">
  The session timeout in seconds.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "result": {
      "success": true,
      "payment_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "link": "https://flouci.com/pay/a1b2c3d4-e5f6-7890-1234-567890abcdef",
      "developer_tracking_id": "YOUR_TRACKING_ID"
    },
    "name": "developers",
    "code": 0,
    "version": "v2"
  }
  ```

  ```json Error theme={null}
  {
    "result": {
      "status": 400,
      "message": "Bad Request"
    }
  }
  ```
</ResponseExample>


# Payment Binding
Source: https://docs.flouci.com/api-reference/advanced-payment-flow/payment-binding

Binding-based payments for recurring transactions and saved payment method workflows.

<Info>
  This feature is exclusive to a select number of partners on demand.
</Info>

Flouci Advanced APIs allow merchants to create **binding-based payment flows** where customers link their Flouci account or saved card once, then pay with a single tap on subsequent transactions — no redirects except for 3DS, no re-entering credentials.

## How it works

<Steps>
  <Step title="Create a binding">
    Make a first payment with a unique `client_id`. The customer completes checkout normally, and their payment method is saved for future use. See [Create Binding](/api-reference/advanced-payment-flow/create-binding).
  </Step>

  <Step title="Pay with the binding">
    For subsequent transactions, send the `binding_id`, `client_id`, and `cvc` along with the payment amount. No checkout redirect needed (except for 3DS). See [Pay with Binding](/api-reference/advanced-payment-flow/confirm-binding).
  </Step>

  <Step title="Verify the payment">
    Use the standard [Verify Payment](/api-reference/verify-transaction) endpoint to confirm the transaction status.
  </Step>
</Steps>

## Use cases

<CardGroup>
  <Card title="Recurring payments" icon="repeat" href="/api-reference/recurring-payments/overview">
    For subscriptions, memberships and scheduled billing use the dedicated Recurring Payments API: Flouci debits the customer's wallet on each cycle without the customer present. Pay with Binding requires the card's `cvc` on every charge, so it cannot debit a saved card unattended.
  </Card>

  <Card title="One-click checkout" icon="bolt">
    Returning customers pay instantly without re-entering payment details or being redirected.
  </Card>

  <Card title="In-app purchases" icon="mobile">
    Native mobile experiences where payments happen seamlessly within your app.
  </Card>

  <Card title="Saved payment methods" icon="credit-card">
    Let customers save their preferred payment method for faster future transactions.
  </Card>
</CardGroup>


# eKYC/eKYB
Source: https://docs.flouci.com/api-reference/eKYC-eKYB



These APIs are available to partners on demand. To obtain more information, please contact our support team at [dev-support@flouci.com](mailto:dev-support@flouci.com).

Flouci eKYC APIs manage user registration, authentication, document submission, and the digital onboarding and identification process. It describes the necessary steps to enable companies to remotely verify the identity of their customers, while ensuring compliance with regulatory requirements.

The document also details the main available endpoints for interacting with the eKYC system, as well as implementation considerations for front-end and back-end systems.

### Overview of the eKYC Process Integration

The eKYC process can be integrated directly into the user registration flow or enabled for specific user categories to verify their identity.

Users are invited to provide documents and personal information to create their profile. The latter is then evaluated for approval or rejection of their account application.

The required documents, defined by the partner institution, may include:

* Uploading or scanning official documents;
* Making a proof-of-life video compared to identity documents;
* Providing a signature;
* Filling out a form containing personal information.

Partner institutions agents have access to the submitted documents and information to approve or reject the account creation request.

### eKYC Process Configuration

During configuration, the necessary steps and required documents are defined according to the specific needs of the partner institution. Substitution options are also available, for example, allowing a CIN to be replaced by a passport for certain verifications. This configuration is associated with a specific API key; thus, all users sharing this key follow the same verification rules.

To configure the eKYC process, it is recommended to collaborate with Kaoun to:

* Define the specific needs of your organization;
* Identify the mandatory documents;
* Determine the possible alternatives to meet regulatory and operational requirements.


# Generate Payment
Source: https://docs.flouci.com/api-reference/generate-transaction

Generate a new payment and get a redirection link for the user to complete the payment in.

This endpoint creates a new payment and returns a URL to redirect the user to for completing the payment.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/api/v2/generate_payment' \
    -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>' \
    -H 'Content-Type: application/json' \
    -d '{
      "amount": "40300",
      "developer_tracking_id": "<YOUR_TRACKING_ID>",
      "accept_card": true,
      "success_link": "https://your-website.com/success",
      "fail_link": "https://your-website.com/fail",
      "webhook": "https://your-website.com/webhook",
      "webhook_version": 2
    }'
  ```
</RequestExample>

### Body

<ParamField type="string">
  The amount to be paid in millimes.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a successful payment.
</ParamField>

<ParamField type="string">
  The URL to redirect the user to after a failed payment.
</ParamField>

<ParamField type="string">
  The webhook URL you want to receive payment confirmation on. Every call is signed with `X-Flouci-Signature`; see [Payment Webhooks](/api-reference/payment-webhooks).
</ParamField>

<ParamField type="integer">
  The format of the webhook call. `1` sends `GET <webhook>?payment_id=<id>&success=<True|False>`; `2` sends a `POST` with a signed JSON `payment.succeeded` or `payment.failed` event. Any other value is rejected with `400`. See [Payment Webhooks](/api-reference/payment-webhooks).
</ParamField>

<ParamField type="string">
  An ID for you to track the payment. This is a free field that Flouci doesn't check against.
</ParamField>

<ParamField type="integer">
  The session timeout in seconds.
</ParamField>

<ParamField type="boolean">
  Whether to accept card payments.
</ParamField>

<ParamField type="URL">
  The URL of the image to display on the payment page. This field is optional, and the default image is the image of the merchant in the Flouci portal.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "result": {
      "success": true,
      "payment_id": "AgCKuBm0S5uLPghBo571MQ",
      "link": "https://checkout.flouci.com/company_name/AgCKuBm0S5uLPghBo571MQ",
      "developer_tracking_id": "<DEVELOPER_TRACKING_ID>"
    },
    "name": "developers",
    "code": 0,
    "version": "v2"
  }
  ```

  ```json Error theme={null}
  {
    "result": {
      "status": 400,
      "message": "Bad Request"
    }
  }
  ```
</ResponseExample>


# Get POS Transaction Status
Source: https://docs.flouci.com/api-reference/get-pos-transaction-status

Retrieve the status of a POS transaction using Flouci's POS devices, from your external system.

This endpoint retrieves the status of a POS transaction.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://developers.flouci.com/partners/transactions/get_pos_transaction_status?developer_tracking_id=dev_track_123' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</RequestExample>

### Query Parameters

<ParamField type="uuid">
  Unique transaction ID from Flouci. Mutually exclusive with `developer_tracking_id`.
</ParamField>

<ParamField type="string">
  An ID for you to track the payment. This is a free field that Flouci doesn't check against. May return multiple rows if you reused the same tracking ID.
</ParamField>

<ParamField type="string">
  Optional terminal identifier to narrow the lookup to a single terminal.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "transactions": [
      {
        "developer_tracking_id": "7cd66b29-a8b7-4e4c-aedf-0d98eeb92703",
        "flouci_transaction_id": "1b7b29df-6826-4b33-b5a6-fb86fcc15e5c",
        "payment_status": "PS",
        "payment_method": "card",
        "amount_in_millimes": 50000,
        "currency": "TND",
        "terminal_id": "T001",
        "settlement_status": "AVAILABLE"
      }
    ],
    "status_code": 200
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="developer_tracking_id" type="string">
  Your merchant-supplied reference. May be `null`.
</ResponseField>

<ResponseField name="flouci_transaction_id" type="string">
  Unique POS transaction identifier from Flouci.
</ResponseField>

<ResponseField name="payment_status" type="string">
  POS payment status code: `PS` (succeeded), `PP` (pending), `PF` (failed), `PR` (refunded), `RP` (refund pending), `RF` (refund failed), `PU` (unknown), `PA` (authorized).
</ResponseField>

<ResponseField name="payment_method" type="string">
  One of `card`, `wallet`, `nfc`, `check`, or `cash`.
</ResponseField>

<ResponseField name="amount_in_millimes" type="integer">
  Transaction amount in millimes.
</ResponseField>

<ResponseField name="currency" type="string">
  Currency code. Currently always `TND`.
</ResponseField>

<ResponseField name="terminal_id" type="string">
  Identifier of the terminal that processed the transaction. May be `null`.
</ResponseField>

<ResponseField name="settlement_status" type="string">
  Settlement lifecycle state for this transaction. For POS, possible values are `PROCESSING` (auth pending), `AVAILABLE` (settled into your wallet), or `NOT_APPLICABLE` (failed / refunded). POS transactions never reach `IN_PAYOUT` or `PAID` — they settle directly into your Flouci wallet rather than entering the card payout pipeline. See [Settlement Status](/api-reference/verify-transaction#settlement-status) for the full reference.
</ResponseField>

<Note>
  In test mode, NFC mock responses do not include `settlement_status`. Production responses always include it.
</Note>


# Initiate POS Transaction
Source: https://docs.flouci.com/api-reference/initiate-pos-transaction

Create and send a transaction to a Flouci POS terminal from your external system.

This endpoint creates and sends a transaction to a POS terminal.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/partners/transactions/init_pos_transaction' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>' \
    -H 'Content-Type: application/json' \
    -d '{
      "id_terminal": "terminal",
      "serial_number": "SN123456",
      "amount_in_millimes": 1000,
      "payment_method": "WALLET",
      "developer_tracking_id": "dev_track_123"
    }'
  ```
</RequestExample>

### Body

<ParamField type="string">
  Unique identifier of the POS terminal.
</ParamField>

<ParamField type="string">
  Serial number of the POS terminal.
</ParamField>

<ParamField type="integer">
  Transaction amount in millimes.
</ParamField>

<ParamField type="string">
  Payment method (NFC, CARD, WALLET, CHECK).
</ParamField>

<ParamField type="string">
  An ID for you to track the payment. This is a free field that Flouci doesn't check against
</ParamField>

<ParamField type="string">
  Webhook URL to notify transaction status.
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "terminal_id": "terminal",
    "developer_tracking_id": "dev_track_123",
    "message": "Transaction initiated successfully",
    "status_code": 201
  }
  ```
</ResponseExample>


# Native Wallet Payments
Source: https://docs.flouci.com/api-reference/partner-payment

Endpoints for partners to manage user accounts and transactions.

## Initiate Account Linking

This endpoint initiates the process of linking a customer's Flouci wallet to their partner account by sending an OTP code.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/partners/accounts/initiate_link_account' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>' \
    -H 'Content-Type: application/json' \
    -d '{
      "phone_number": "55555555"
    }'
  ```
</CodeGroup>

### Body

<ParamField type="string">
  The customer's phone number (MSSDN).
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "session_id": "ad4ead7c-c3e9-4531-b678-dcb8b68ba166",
    "name": "Foulen Ben Foulen",
    "phone_number": "55555555",
    "message": "Verification code is sent to: "
  }
  ```
</ResponseExample>

***

## Confirm Account Linking

***

## Authenticate Session

This endpoint creates a short-lived session token for the user to access wallet functionalities.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST '@IP/api/accounts/authenticate' \
    -H 'Authorization: Api-Key <' \
    -H 'Content-Type: application/json' \
    -d '{
      "tracking_id": "5a3c7b16-f197-474a-b1b3-e3bcb96690e5",
      "phone_number": "55555555"
    }'
  ```
</CodeGroup>

### Body

<ParamField type="uuid">
  The unique user identifier from the confirm linking step.
</ParamField>

<ParamField type="string">
  The customer's phone number (MSSDN).
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 300,
    "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
  ```
</ResponseExample>

***

## Refresh Session

This endpoint generates a new access token after the previous one has expired.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET '@IP/api/accounts/authenticate/refresh' \
    -H 'Authorization: Bearer YOUR_REFRESH_TOKEN'
  ```
</CodeGroup>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expires_in": 300
  }
  ```
</ResponseExample>

***

## Get Balance

This endpoint allows the user to check their wallet balance in millimes.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET '@IP/partners/v1/transactions/balance?phone_number=55555555&tracking_id=602e300d-bee8-49a6-b5b7-438912669a27' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</CodeGroup>

### Query Parameters

<ParamField type="string">
  The customer's phone number (MSSDN).
</ParamField>

<ParamField type="uuid">
  The unique user identifier.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "wallet_id": "2131239123891028390",
    "balance_in_millimes": 1387410
  }
  ```
</ResponseExample>

***

## Get History

This endpoint allows you to view the customer's transaction history from the partner application.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET '@IP/partners/v1/transactions/history?phone_number=55555555&tracking_id=602e300d-bee8-49a6-b5b7-438912669a27' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</CodeGroup>

### Query Parameters

<ParamField type="string">
  The customer's phone number (MSSDN).
</ParamField>

<ParamField type="uuid">
  The unique user identifier.
</ParamField>

<ParamField type="datetime">
  Start date to filter history (ISO 8601 format).
</ParamField>

<ParamField type="datetime">
  End date to filter history (ISO 8601 format).
</ParamField>

<ParamField type="integer">
  Page number.
</ParamField>

<ParamField type="integer">
  Number of items per page (max 10000).
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
      {
        "operation_id": "906178af-6cb0-4fdb-be76-519199b6c679",
        "sender": "55000000",
        "status": "Approved",
        "time_created": "2025-02-23T23:00:46.294232+01:00",
        "payload": {
          "blockchain_ref": "5B935D",
          "operation_type": "PAYMENT",
          "product": "001"
        }
      }
    ]
  }
  ```
</ResponseExample>

***

## Initiate Payment

This endpoint allows the user to pay for a service.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST '@IP/partners/v1/transactions/initiate_payment' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>' \
    -H 'Content-Type: application/json' \
    -d '{
      "phone_number": "55555555",
      "tracking_id": "602e300d-bee8-49a6-b5b7-438912669a27",
      "amount_in_millimes": "1000",
      "product": "001"
    }'
  ```
</CodeGroup>

### Body

<ParamField type="string">
  The customer's phone number (MSSDN).
</ParamField>

<ParamField type="uuid">
  The unique user identifier.
</ParamField>

<ParamField type="integer">
  The transaction amount in millimes.
</ParamField>

<ParamField type="string">
  Product code (e.g., `001`).
</ParamField>

<ParamField type="string">
  Webhook URL to notify transaction status.
</ParamField>

<ResponseExample>
  ```json 201 theme={null}
  {
    "success": true,
    "hash": "AB31047652EEA9B923C6BC931EB989A5BE13442D9DAC09920513A6022F6067A9",
    "blockchain_ref": "AB3104"
  }
  ```
</ResponseExample>


# Payment Webhooks
Source: https://docs.flouci.com/api-reference/payment-webhooks

Receive a signed server-to-server notification when a payment succeeds or fails, and verify that it really comes from Flouci.

When you pass a `webhook` URL to [Generate Payment](/api-reference/generate-transaction), Flouci calls it once the payment reaches a final state. Every call carries an `X-Flouci-Signature` header computed with your app's **private token**, so you can reject any request that does not come from Flouci before acting on it.

You choose the format per payment with the `webhook_version` field:

| `webhook_version` | Format | When to use it |
| - | - | - |
| `1` (default) | `GET <webhook>?payment_id=<id>&success=<True\|False>` | Existing integrations. Nothing to change, but add the signature check. |
| `2` | `POST` with a JSON event body | New integrations, or if you also handle [subscription webhooks](/api-reference/recurring-payments/webhooks): same format, one handler for both. |

<Warning>
  Verify the signature before you trust a webhook, then confirm the payment with [Verify Payment](/api-reference/verify-transaction) before you deliver goods. Without the check, anyone who knows your webhook URL can send you a fake `success=True`.
</Warning>

## Delivery

Both versions are delivered the same way:

| | |
| - | - |
| Signature header | `X-Flouci-Signature: t=<unix timestamp>,v1=<hex HMAC-SHA256>` |
| Key | Your app's private token: the second half of your `Authorization: Bearer <public>:<private>` credential |
| Retries | 5 retries with exponential backoff (1 min, 2 min, 4 min, …) while your endpoint does not answer 2xx |
| Duplicates | A payment is notified once your endpoint answered 2xx. A retry can still reach you twice, so make your handler idempotent on `payment_id` (version 1) or `event_id` (version 2). |
| Timeout | Answer within a few seconds and do your processing after acknowledging. |

The signature is always `HMAC-SHA256(private_token, "<t>.<signed content>")`. Only the signed content differs between the versions:

| Version | Signed content |
| - | - |
| `1` | The query string `payment_id=<payment_id>&success=<success>`, with both values exactly as you received them |
| `2` | The raw request body, byte for byte |

Compare the result to `v1` in constant time, and reject timestamps older than a few minutes to block replays.

## Version 1 — signed GET (default)

```http theme={null}
GET https://your-website.com/webhook?payment_id=AgCKuBm0S5uLPghBo571MQ&success=True
X-Flouci-Signature: t=1791014400,v1=5f0c3e…
```

<ResponseField name="payment_id" type="string">
  The payment concerned, as returned by Generate Payment.
</ResponseField>

<ResponseField name="success" type="string">
  `True` when the payment succeeded, `False` when it failed. The first letter is uppercase; use the value exactly as received when you compute the signature.
</ResponseField>

<CodeGroup>
  ```python Python theme={null}
  import hashlib
  import hmac
  import time

  def verify_flouci_get_webhook(payment_id: str, success: str, signature_header: str, private_token: str, tolerance_seconds: int = 300) -> bool:
      parts = dict(item.split("=", 1) for item in signature_header.split(","))
      timestamp, received = parts["t"], parts["v1"]
      if abs(time.time() - int(timestamp)) > tolerance_seconds:
          return False
      signed = f"{timestamp}.payment_id={payment_id}&success={success}"
      expected = hmac.new(private_token.encode(), signed.encode(), hashlib.sha256).hexdigest()
      return hmac.compare_digest(expected, received)

  # Flask example
  # ok = verify_flouci_get_webhook(request.args["payment_id"], request.args["success"],
  #                                request.headers["X-Flouci-Signature"], PRIVATE_TOKEN)
  ```

  ```javascript Node.js theme={null}
  const crypto = require("crypto");

  function verifyFlouciGetWebhook(paymentId, success, signatureHeader, privateToken, toleranceSeconds = 300) {
    const parts = Object.fromEntries(signatureHeader.split(",").map((p) => p.split("=")));
    if (Math.abs(Date.now() / 1000 - Number(parts.t)) > toleranceSeconds) return false;
    const expected = crypto
      .createHmac("sha256", privateToken)
      .update(`${parts.t}.payment_id=${paymentId}&success=${success}`)
      .digest("hex");
    const a = Buffer.from(expected, "hex");
    const b = Buffer.from(parts.v1, "hex");
    return a.length === b.length && crypto.timingSafeEqual(a, b);
  }

  // Express example
  // const ok = verifyFlouciGetWebhook(req.query.payment_id, req.query.success, req.get("X-Flouci-Signature"), PRIVATE_TOKEN);
  ```
</CodeGroup>

## Version 2 — signed JSON events

Send `"webhook_version": 2` with [Generate Payment](/api-reference/generate-transaction) to receive a `POST` instead:

```http theme={null}
POST https://your-website.com/webhook
Content-Type: application/json
X-Flouci-Event: payment.succeeded
X-Flouci-Signature: t=1791014400,v1=9a41d2…

{"amount":40300,"created":"2026-10-04T10:00:00.120000+00:00","currency":"TND","developer_tracking_id":"order-1042","event":"payment.succeeded","event_id":"3b8e9c1d-5f2a-5c7e-8d4b-2a1f0e9c7b6a","payment_id":"AgCKuBm0S5uLPghBo571MQ","payment_method":"card"}
```

| Event | When |
| - | - |
| `payment.succeeded` | The customer paid. Confirm with [Verify Payment](/api-reference/verify-transaction), then deliver. |
| `payment.failed` | The payment failed or was refused. |

<ResponseField name="event" type="string">
  `payment.succeeded` or `payment.failed`. Also sent in the `X-Flouci-Event` header.
</ResponseField>

<ResponseField name="event_id" type="string">
  Unique per payment and event, and unchanged when a delivery is retried. Store it and ignore an event you have already processed.
</ResponseField>

<ResponseField name="created" type="timestamp">
  When the event was emitted.
</ResponseField>

<ResponseField name="payment_id" type="string">
  The payment concerned, as returned by Generate Payment.
</ResponseField>

<ResponseField name="developer_tracking_id" type="string">
  The `developer_tracking_id` you sent with Generate Payment.
</ResponseField>

<ResponseField name="amount" type="integer">
  Amount of the payment in millimes.
</ResponseField>

<ResponseField name="currency" type="string">
  Always `TND`. A payment requested in another currency is converted to TND when it is created.
</ResponseField>

<ResponseField name="payment_method" type="string">
  `card`, `flouci` (wallet) or `mpayment`. `NA` when no payment method was used, for example when the payment session expired.
</ResponseField>

The signature check is the same as for subscription events: `HMAC-SHA256` over `"<t>.<raw body>"`. See the Python and Node.js samples in [Subscription Webhooks](/api-reference/recurring-payments/webhooks#verifying-the-signature).

<Tip>
  Sign over the raw request body, not a re-serialized JSON object: any whitespace or key-order difference changes the digest. In Express, use `express.raw({ type: "application/json" })` for the webhook route.
</Tip>

## Moving from version 1 to version 2

<Steps>
  <Step title="Add the signature check to your GET handler">
    This protects your existing integration right away, with no change to your Generate Payment calls.
  </Step>

  <Step title="Deploy a POST handler on the same URL">
    Accept both methods during the migration: verify the signature with the matching rule, then de-duplicate on `payment_id` or `event_id`.
  </Step>

  <Step title="Send webhook_version 2">
    Add `"webhook_version": 2` to your Generate Payment calls. Payments created before the switch keep the version they were created with.
  </Step>
</Steps>

## Limitations

<Note>
  Only payment webhooks are signed. Payout (send money), partner and POS webhooks are not signed yet. Confirm their outcome with the matching status endpoint before acting on them.
</Note>


# QR Code Payments
Source: https://docs.flouci.com/api-reference/qr-code-payments

Generate and verify payments using QR codes only. No redirects.

The endpoints defined in the next section require a special API key generated by Flouci upon request. These endpoints allow for the seemless integration of QR code payments within your external system without redirects or embedding of external pages.
These APIs allow you to generate dynamic QR codes that Flouci wallets - or any other wallet licensed by the Central Bank of Tunisia - can scan and pay. You can simply display the QR code string provided to the client in digital or paper form.

Wallet payments are verified and settled instantly, and will appear in your available balance within seconds.

## Generate Custom QR Code

This API allows you to generate a custom QR code with a specified amount.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET '@IP/api/business/generate_custom_qr_code?amount=1000&merchant_id=123' \
    -H 'Authorization: Api-Key <YOUR_API_KEY>'
  ```
</CodeGroup>

### Query Parameters

<ParamField type="decimal">
  The transaction amount in millimes
</ParamField>

<ParamField type="integer">
  Your merchant ID.
</ParamField>

<ParamField type="uuid">
  A unique ID for the operation. If not provided, a random UUID will be generated.
</ParamField>

<ParamField type="boolean">
  Set to `true` to receive a slug representation of the QR code.
</ParamField>

### Headers

<ParamField type="string">
  Your API key. Should be in the format `Api-Key YOUR_API_KEY`.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "code": 200,
    "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIAQAAAACFI5MzAAABaklEQVR42u3aQW7DMAwFUP//p88j...",
    "operation_uuid": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "code": 400,
    "message": "<parameter> is required"
  }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "code": 403,
    "message": "Forbidden"
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "code": 404,
    "message": "precondition fails, code 3"
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "code": 500,
    "message": "Unexpected Error"
  }
  ```
</ResponseExample>

***

## Verify Custom Transaction

This API allows you to verify the transaction associated with a dynamically generated QR code.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://@IP/api/business/custom_transaction/status?operation_uuid=a1b2c3d3-e5f6-7890-1234-567890abcdef' \
    -H 'Authorization: Api-Key <YOUR_API_KEY>'
  ```
</CodeGroup>

### Query Parameters

<ParamField type="uuid">
  The `operation_uuid` of the dynamic QR code.
</ParamField>

### Headers

<ParamField type="string">
  Your API key. Should be in the format `Api-Key <YOUR_API_KEY>`.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "code": 200,
    "transactions": [
      {
        "transaction_unique_id": "t1u2n3i4q5u6e7i8d9",
        "time": "2025-08-02T12:00:00Z",
        "amount": 1000,
        "channel": "Flouci"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "code": 400,
    "message": "<parameter> is required"
  }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "code": 403,
    "message": "Forbidden"
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "code": 500,
    "message": "Unexpected Error"
  }
  ```

  ```json 503 theme={null}
  {
    "success": false,
    "code": 503,
    "message": "Service unavailable"
  }
  ```
</ResponseExample>

***

## History of Purchases

This API allows you to fetch the transaction history of a merchant.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET '@IP/api/business/custom_transactions/history?merchant_id=123' \
    -H 'Authorization: Api-Key YOUR_API_KEY'
  ```
</CodeGroup>

### Query Parameters

<ParamField type="integer">
  Your merchant ID.
</ParamField>

<ParamField type="datetime">
  The start date of the transaction history.
</ParamField>

<ParamField type="datetime">
  The end date of the transaction history.
</ParamField>

<ParamField type="integer">
  The number of items per page.
</ParamField>

### Headers

<ParamField type="string">
  Your API key. Should be in the format `Api-Key YOUR_API_KEY`.
</ParamField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "success": true,
    "code": 200,
    "result": [
      {
        "transaction_unique_id": "t1u2n3i4q5u6e7i8d9",
        "time": "2025-08-02T12:00:00Z",
        "amount": 1000,
        "channel": "Flouci"
      }
    ]
  }
  ```

  ```json 400 theme={null}
  {
    "success": false,
    "code": 400,
    "message": "<parameter> is required"
  }
  ```

  ```json 403 theme={null}
  {
    "success": false,
    "code": 403,
    "message": "Forbidden"
  }
  ```

  ```json 404 theme={null}
  {
    "success": false,
    "code": 404,
    "message": "precondition fails, code 3"
  }
  ```

  ```json 500 theme={null}
  {
    "success": false,
    "code": 500,
    "message": "Unexpected Error"
  }
  ```
</ResponseExample>


# Real-time Settlement
Source: https://docs.flouci.com/api-reference/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 type="string">
  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 type="string">
  The unique identifier for the agent.
</ParamField>

### Response Body

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

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

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

<ResponseField name="amount" type="string">
  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 type="string">
  The unique ID for the Flouci transaction.
</ParamField>

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

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

### Response Body

<ResponseField name="code" type="string">
  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).


# Refund Payment
Source: https://docs.flouci.com/api-reference/refund-payment

Refund a completed standard payment and return funds to the customer.

This endpoint refunds a completed payment. Once processed, the funds are returned to the original payment method used by the customer.

<Warning>
  Exclusive feature. Only completed payments in a refundable state can be refunded. A payment that has already been refunded or is still pending cannot be refunded again.
</Warning>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST 'https://developers.flouci.com/api/v2/refund_payment' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>' \
    -d '{
      "payment_id": "FoPKKHqfQIKfBqhEj8M47A"
    }'
  ```
</RequestExample>

### Body

<ParamField type="string">
  The ID of the payment to refund. This must be a valid `payment_id` from a previously completed payment.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
    "result": {
      "refund_id": "ref_a1b2c3d4",
      "payment_id": "FoPKKHqfQIKfBqhEj8M47A",
      "amount": "10000",
      "status": "success",
      "refunded_at": "2025-01-15T10:30:00Z"
    },
    "status": "success"
  }
  ```

  ```json Error theme={null}
  {
    "status": "error",
    "message": "Payment cannot be refunded",
    "code": "REFUND_NOT_ALLOWED"
  }
  ```
</ResponseExample>


# Transaction History
Source: https://docs.flouci.com/api-reference/transaction-history

Query your online and POS transaction history with filters for date range, status, terminal, and app token.

The Transaction History endpoint returns a paginated list of your transactions, with optional filters for date range, payment status, app token, and terminal. Each row includes a `settlement_status` field indicating where the transaction sits in the settlement lifecycle.

The endpoint has two branches selected by the `type` query parameter:

* **`type=online`** (default) — returns card, wallet, and mobile-switch payments created through the online payment API.
* **`type=pos`** — returns transactions processed by a POS terminal.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=online&start_date=2026-05-20T00:00:00' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</RequestExample>

## Query Parameters

<ParamField type="integer">
  Identifier of the merchant whose history to query. The merchant must have developer API access enabled.
</ParamField>

<ParamField type="string">
  Which branch of the history to query. Either `online` (returns online payments — card, wallet, mobile switch) or `pos` (returns POS terminal transactions).
</ParamField>

<ParamField type="datetime">
  ISO-8601 datetime. Inclusive lower bound on the transaction creation time. Unbounded if omitted.
</ParamField>

<ParamField type="datetime">
  ISO-8601 datetime. Inclusive upper bound on the transaction creation time. Must be ≥ `start_date` and cannot be in the future.
</ParamField>

<ParamField type="string">
  Optional status filter. Accepts the codes in the table below for both branches — POS queries map them internally to POS payment statuses.
</ParamField>

<ParamField type="uuid">
  **Online only.** Filter results to a specific app token recorded on the payment payload.
</ParamField>

<ParamField type="string">
  **POS only.** Restrict results to a single terminal. Maximum 16 characters. Returns a `1004` validation error if combined with `type=online`.
</ParamField>

### `operation_status` accepted values

The endpoint accepts the same status codes regardless of `type`. For POS queries the code is mapped internally.

| Code | Online (`type=online`) | POS (`type=pos`) |
| - | - | - |
| `S` (Success) | matches `Success` | matches `PAYMENT_SUCCEEDED` |
| `AS` (All success) | matches `Success`, `FlouciSuccess`, `MobileSwitchSuccess` | matches `PAYMENT_SUCCEEDED` |
| `PF` (Payment failure) | matches `PaymentFailure` | matches `PAYMENT_FAILED` |
| `P` (Pending) | matches `Pending` | matches `PAYMENT_PENDING` |

Other status codes are passed through verbatim with no automatic mapping.

### Validation errors

| Code | Reason |
| - | - |
| `1002` | `start_date` is later than `end_date`. |
| `1003` | `start_date` or `end_date` is in the future. |
| `1004` | `terminal_id` supplied together with `type=online`. |

## Response

The endpoint returns a paginated list. Each element is shaped according to the requested `type`.

<Tabs>
  <Tab title="Online (type=online)">
    ```json theme={null}
    {
      "type": "card",
      "amount": 100000,
      "status": "SUCCESS",
      "details": {
        "name": "FOULEN BEN FOULEN",
        "approval_code": "182848"
      },
      "developer_tracking_id": "order_98231",
      "fee": 5000,
      "tva": 950,
      "settlement_status": "AVAILABLE"
    }
    ```

    <ResponseField name="type" type="string">
      Payment method used. One of `card`, `flouci` (wallet), `mpayment` (mobile switch), or `NA`.
    </ResponseField>

    <ResponseField name="amount" type="integer">
      Amount in millimes.
    </ResponseField>

    <ResponseField name="status" type="string">
      Payment status. One of `SUCCESS`, `PENDING`, `EXPIRED`, `FAILURE`, `PREAUTH_SUCCESS`, or `SYSTEM_FAILURE`.
    </ResponseField>

    <ResponseField name="details" type="object">
      Buyer information. Shape depends on the payment `type`.
    </ResponseField>

    <ResponseField name="developer_tracking_id" type="string">
      Your merchant-supplied reference. May be `null`.
    </ResponseField>

    <ResponseField name="subscription_id" type="string">
      **Only on charges of a recurring subscription.** The subscription this payment belongs to — see [Recurring Payments](/api-reference/recurring-payments/overview). Absent on one-off payments.
    </ResponseField>

    <ResponseField name="billing_reason" type="string">
      **Only on charges of a recurring subscription.** `subscription_create`, `subscription_cycle` or `subscription_retry`.
    </ResponseField>

    <ResponseField name="fee" type="integer">
      Per-transaction fee in millimes. Returns an empty string `""` until the fee has been computed.
    </ResponseField>

    <ResponseField name="tva" type="integer">
      VAT in millimes. Returns an empty string `""` until computed.
    </ResponseField>

    <ResponseField name="settlement_status" type="string">
      Settlement lifecycle state for this transaction. See [Settlement Status](/api-reference/verify-transaction#settlement-status).
    </ResponseField>
  </Tab>

  <Tab title="POS (type=pos)">
    ```json theme={null}
    {
      "developer_tracking_id": "order_98231",
      "flouci_transaction_id": "1b7b29df-6826-4b33-b5a6-fb86fcc15e5c",
      "payment_status": "PS",
      "payment_method": "card",
      "amount_in_millimes": 50000,
      "currency": "TND",
      "terminal_id": "T001",
      "settlement_status": "AVAILABLE"
    }
    ```

    <ResponseField name="developer_tracking_id" type="string">
      Your merchant-supplied reference. May be `null`.
    </ResponseField>

    <ResponseField name="flouci_transaction_id" type="string">
      Unique POS transaction identifier.
    </ResponseField>

    <ResponseField name="payment_status" type="string">
      POS payment status code: `PS` (succeeded), `PP` (pending), `PF` (failed), `PR` (refunded), `RP` (refund pending), `RF` (refund failed), `PU` (unknown), `PA` (authorized).
    </ResponseField>

    <ResponseField name="payment_method" type="string">
      One of `card`, `wallet`, `nfc`, `check`, or `cash`.
    </ResponseField>

    <ResponseField name="amount_in_millimes" type="integer">
      Transaction amount in millimes.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Currency code. Currently always `TND`.
    </ResponseField>

    <ResponseField name="terminal_id" type="string">
      Identifier of the terminal that processed the transaction. May be `null`.
    </ResponseField>

    <ResponseField name="settlement_status" type="string">
      Settlement lifecycle state for this transaction. POS values are limited to `PROCESSING`, `AVAILABLE`, and `NOT_APPLICABLE`. See [Settlement Status](/api-reference/verify-transaction#settlement-status).
    </ResponseField>
  </Tab>
</Tabs>

## Examples

<CodeGroup>
  ```bash Last week of online payments theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=online&start_date=2026-05-20T00:00:00' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```

  ```bash Successful POS payments on one terminal theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=pos&terminal_id=T001&operation_status=S' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```

  ```bash Online card payments by app token theme={null}
  curl -X GET 'https://developers.flouci.com/api/developers/history?merchant_id=42&type=online&app_token=602e300d-bee8-49a6-b5b7-438912669a27' \
    -H 'Authorization: Bearer <APP_PUBLIC>:<APP_SECRET>'
  ```
</CodeGroup>

<Warning>
  There is currently no query parameter to filter by `settlement_status`. To separate transactions by settlement state — for example, to identify what has already been wired to your bank versus what is still in flight — filter the returned list client-side on the `settlement_status` field.
</Warning>


# Verify Payment
Source: https://docs.flouci.com/api-reference/verify-transaction

Verify the status of a payment.

This endpoint allows you to check the status of a payment using the `payment_id` returned by the Generate Payment endpoint.
In this endpoint, it is crucial to ensure that the "success" field is true before attempting to parse the API's content. Once confirmed, the payload will reveal the precise status of the transaction at the time of the API call. The transaction status can be one of the following:

* **SUCCESS**: This indicates that the transaction has been confirmed and the payment was successful.
* **PENDING**: The session is still active, and a payment can still be confirmed.
* **EXPIRED**: The session has expired, and no payment is expected.
* **FAILURE**: The payment has failed, and details regarding the failure, including the reason, are accessible via the API.

To confirm a payment, it is essential to verify that the "success" field is true and the status is "SUCCESS". It is advisable to invoke this function upon receiving a success or failure webhook to confirm the transaction's status. However, it is important to avoid making multiple successive calls (pings) to prevent rate limiting and potential IP bans.

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET 'https://developers.flouci.com/api/v2/verify_payment/{payment_id}' \
    -H 'authorization: Bearer <APP_PUBLIC>:<APP_SECRET>' \
  ```
</RequestExample>

### Path Parameters

<ParamField type="string">
  The ID of the payment to verify.
</ParamField>

<ResponseExample>
  ```json Success theme={null}
  {
      "success": true,
      "result": {
          "type": "wallet",
          "amount": 1250,
          "status": "SUCCESS",
          "details": {
              "order_number": "Pb3pNSdyRRWOBdXHDTEdBw",
              "name": "FOULEN BEN FOULEN",
              "approval_code": "182848",
              "phone_number": "",
              "email": "",
              "destination": []
          },
          "developer_tracking_id": "your_internal_tracking_id",
          "settlement_status": "AVAILABLE"
      },
      "status_code": 200,
      "name": "developers",
      "code": 0,
      "version": "2.0.0"
  }
  ```

  ```json Error theme={null}
  {
    "result": {
      "status": 404,
      "message": "Payment not found"
    }
  }
  ```
</ResponseExample>

### Response Fields

<ResponseField name="type" type="string">
  Payment method used. One of `card`, `wallet` (Flouci wallet), `mpayment` (mobile switch), or `NA`.
</ResponseField>

<ResponseField name="amount" type="integer">
  Amount paid in millimes.
</ResponseField>

<ResponseField name="status" type="string">
  Payment status: `SUCCESS`, `PENDING`, `EXPIRED`, `FAILURE`, `PREAUTH_SUCCESS`, or `SYSTEM_FAILURE`.
</ResponseField>

<ResponseField name="details" type="object">
  Buyer information. Shape depends on the payment `type`.
</ResponseField>

<ResponseField name="developer_tracking_id" type="string">
  Your merchant-supplied reference passed at payment creation. May be `null`.
</ResponseField>

<ResponseField name="subscription_id" type="string">
  **Only on charges of a recurring subscription.** The subscription this payment belongs to — see [Recurring Payments](/api-reference/recurring-payments/overview). Absent on one-off payments.
</ResponseField>

<ResponseField name="billing_reason" type="string">
  **Only on charges of a recurring subscription.** Why the charge exists: `subscription_create` (first payment), `subscription_cycle` (renewal) or `subscription_retry` (retry after a failed renewal).
</ResponseField>

<ResponseField name="settlement_status" type="string">
  Where this transaction sits in the settlement lifecycle. See [Settlement Status](#settlement-status) below. One of `PROCESSING`, `AVAILABLE`, `IN_PAYOUT`, `PAID`, or `NOT_APPLICABLE`.
</ResponseField>

***

## Settlement Status

Every transaction returned by the Verify endpoint carries a `settlement_status` field describing where the funds sit between the moment of payment and the moment they reach your bank account.

<Info>
  `settlement_status` is **independent** of `status`. A `SUCCESS` payment can still be `PROCESSING` (settling), `AVAILABLE` (in your balance), `IN_PAYOUT` (committed to a payout), or `PAID` (wired to your bank). Existing fields are unchanged — clients that ignore `settlement_status` see no behavior change.
</Info>

### Lifecycle

On the happy path of a card payment, the status moves forward through these stages:

```
PROCESSING → AVAILABLE → IN_PAYOUT → PAID
```

Wallet, mobile-switch, and POS payments skip `PROCESSING` and land directly in `AVAILABLE` on success — they never enter the card payout pipeline.

### The five values

| Value | Meaning |
| - | - |
| `PROCESSING` | Card payment succeeded but is inside the T+1 settlement window (the day-after-midnight cutoff). For POS, also used while a payment authorization is still in flight. |
| `AVAILABLE` | Eligible for inclusion in the next payout. Reached automatically once a card payment passes T+1, or immediately for wallet, mobile-switch, and POS payments. |
| `IN_PAYOUT` | Committed to a payout request that has been initiated, but the bank wire has **not yet been sent**. Brief in-flight window. |
| `PAID` | Payout wire transfer has been **sent to your bank account**. Terminal state. |
| `NOT_APPLICABLE` | Transaction is outside the settlement lifecycle — failed, expired, refunded, cancelled, pending authorization, or pre-authorized but not finalized. |

### Lifecycle by payment type

| Payment type | Possible values |
| - | - |
| Online card (`type=card`) | `PROCESSING` → `AVAILABLE` → `IN_PAYOUT` → `PAID`, plus `NOT_APPLICABLE` |
| Online wallet (`type=wallet`) | `AVAILABLE` on success, `NOT_APPLICABLE` on failure. Never `PROCESSING`, `IN_PAYOUT`, or `PAID`. |
| Online mobile switch (`type=mpayment`) | Same as wallet. |
| POS | `PROCESSING` (auth pending), `AVAILABLE` (settled into wallet), `NOT_APPLICABLE` (failed / refunded). Never `IN_PAYOUT` or `PAID` — POS doesn't enter the gateway payout pipeline. |

### How to use it

<AccordionGroup>
  <Accordion title="Is this payment in my available balance?">
    Look for `settlement_status == "AVAILABLE"`.
  </Accordion>

  <Accordion title="Will this be on my next payout?">
    Once you request a payout, `AVAILABLE` transactions move to `IN_PAYOUT`, then to `PAID` once the wire is sent.
  </Accordion>

  <Accordion title="Has this hit my bank account?">
    `settlement_status == "PAID"`. This is the terminal state.
  </Accordion>

  <Accordion title="Why isn't this showing up in my balance?">
    Check `status` first — if the payment failed, expired, or is still pending, `settlement_status` will be `NOT_APPLICABLE`. Otherwise it is most likely `PROCESSING` (inside the T+1 window for a card payment).
  </Accordion>
</AccordionGroup>

<Tip>
  For bookkeeping, combine both fields: a transaction is "money that belongs to you" only when `status == "SUCCESS"` **and** `settlement_status` is one of `AVAILABLE`, `IN_PAYOUT`, or `PAID`.
</Tip>


# Changelog
Source: https://docs.flouci.com/changelog

Recent additions and changes to the Flouci Payment API and developer documentation.

Track what's new in the Flouci Payment API. Entries are listed in reverse-chronological order.

<Update label="October 2026" description="Released October 2026">
  ## Signed payment webhooks and JSON payment events

  Payment webhooks now carry an `X-Flouci-Signature` header, an HMAC-SHA256 computed with your app's private token, so you can check that a call comes from Flouci before acting on it. The default `GET <webhook>?payment_id=<id>&success=<True|False>` call is unchanged apart from the new header.

  A new optional `webhook_version` field on [Generate Payment](/api-reference/generate-transaction) lets you receive a signed JSON `POST` instead, with a `payment.succeeded` or `payment.failed` event in the same format as subscription webhooks.

  See [Payment Webhooks](/api-reference/payment-webhooks) for both formats, the verification code and how to migrate.

  <Check>
    Additive and backward compatible. Existing webhook handlers keep working; add the signature check to reject forged calls.
  </Check>
</Update>

<Update label="August 2026" description="Released August 17, 2026">
  ## Card payment error codes are now documented

  The [Error Dictionary](/essentials/error-dictionary) lists the 37 card payment error codes observed in production, with the verbatim message returned by the card processing platform, what each code means, and the action to offer your customer.

  Codes are also grouped into handling patterns so you can implement one behavior per pattern instead of a branch per code — including the two cases that need care: never retry `-2013` or `-2007` on the same order, and always verify the final state of the order after `100801` before offering a retry, to avoid a double debit.

  <Check>
    Documentation only — no API behavior changed. These codes were already returned by the platform.
  </Check>
</Update>

<Update label="May 2026" description="Released May 28, 2026">
  ## Settlement status on Verify and History responses

  Every transaction returned by the [Verify Payment](/api-reference/verify-transaction), [POS Get Transaction Status](/api-reference/get-pos-transaction-status), and [Transaction History](/api-reference/transaction-history) endpoints now carries a `settlement_status` field describing where the funds sit between the moment of payment and the moment they reach your bank account.

  The field is one of five values:

  * `PROCESSING` — succeeded card payment inside the T+1 settlement window
  * `AVAILABLE` — eligible for inclusion in the next payout
  * `IN_PAYOUT` — committed to a payout request, wire not yet sent
  * `PAID` — wired to your bank account (terminal state)
  * `NOT_APPLICABLE` — outside the settlement lifecycle (failed, refunded, pending, etc.)

  See the full reference in [Settlement Status](/api-reference/verify-transaction#settlement-status).

  <Check>
    This change is **additive and backward compatible** — existing `status` and `payment_status` fields are unchanged. Clients that ignore `settlement_status` see no behavior change.
  </Check>

  ## New Transaction History endpoint

  The [Transaction History endpoint](/api-reference/transaction-history) is now documented with full query-parameter, response, and filtering reference for both branches:

  * `type=online` — card, wallet, and mobile-switch payments
  * `type=pos` — POS terminal transactions

  Filters: date range, payment status (`operation_status`), `app_token` (online only), and `terminal_id` (POS only).
</Update>


# Accept Online
Source: https://docs.flouci.com/dashboard/accept-online

Manage API applications, payment links, inventory, and plugins.

The **Accepter en ligne** (Accept Online) section provides all the tools you need to accept payments through digital channels.

## API — Applications

Each application (store) represents an API integration with its own credentials.

<Steps>
  <Step title="View your applications">
    Each store card displays the app name, active status, description, and tokens.
  </Step>

  <Step title="Copy your tokens">
    * **Public Token** — use in frontend API calls (safe to expose)
    * **Private Token** — click **"Afficher le token privé"** to reveal. Use only in your backend and keep it secret.

    <Warning>
      Never expose your private token in client-side code, public repositories, or browser-accessible files.
    </Warning>
  </Step>

  <Step title="Manage applications">
    * Use the **⋮ menu** on any card to edit or delete an application.
    * Click **"+ Nouvelle application"** to create a new store or environment.
  </Step>
</Steps>

## Payment links

Payment links let you accept payments without writing any code — just create a link and share it.

<Steps>
  <Step title="Create a link">
    Click **"+ Nouveau lien de paiement"** and fill in the customer name, description, amount, and expiry date.
  </Step>

  <Step title="Share the link">
    Send the generated link via WhatsApp, Messenger, email, or any other channel.
  </Step>

  <Step title="Track status">
    Monitor each link's status (Pending or Paid) in the list. Use the **⋯ Actions** menu to copy, share, or delete a link.
  </Step>
</Steps>

## Inventory

Manage your product or service catalog directly from the dashboard. Add, edit, or remove items and link them to payment links or terminal sales.

## Plugins

Integrate Flouci into your e-commerce platform with a ready-made plugin:

<CardGroup>
  <Card title="WooCommerce" icon="wordpress">
    For WordPress-based online stores.
  </Card>

  <Card title="PrestaShop" icon="cart-shopping">
    For PrestaShop-powered shops.
  </Card>

  <Card title="Magento" icon="bag-shopping">
    For Magento storefronts.
  </Card>
</CardGroup>

Click **"Télécharger le plugin"** on the dashboard to download and install.


# In-Store
Source: https://docs.flouci.com/dashboard/in-store

Manage physical terminals and check payments.

The **En magasin** (In-Store) section manages your physical payment terminals and check-based transactions.

## Terminals

<Steps>
  <Step title="View your terminals">
    Each terminal card shows its **ID**, **serial number**, and **status** (active/inactive).
  </Step>

  <Step title="Inspect transactions">
    Click **"Voir les transactions"** on any terminal to see its transaction history.
  </Step>

  <Step title="Manage terminals">
    * Use the **⋮ menu** to edit, deactivate, or remove a terminal.
    * Click **"+ Ajouter un terminal"** to register new hardware.
    * Use pagination to browse all terminals (12 per page).
  </Step>
</Steps>

## Checks

Track check reservations in the **Chèques** section. View received checks and monitor their status.


# Invoices
Source: https://docs.flouci.com/dashboard/invoices

Access and download your billing invoices from Flouci.

The **Factures** (Invoices) section contains all billing invoices issued by Flouci (Kaoun), signed and stamped.

## Browse invoices

Each invoice displays:

| Field | Description |
| - | - |
| **Nom de la Facture** | Invoice name/reference |
| **Date** | Issue date |
| **Devise** | Currency |
| **HT** | Amount before tax |
| **TTC** | Amount including tax |

## Download and review

* Click the **download icon** on any invoice to save a PDF copy.
* Review invoices from previous months to track fees and charges over time.

<Note>
  Invoice amounts reflect your transaction volume for the billing period.
</Note>


# Dashboard Overview
Source: https://docs.flouci.com/dashboard/overview

Navigate the Flouci business dashboard and monitor your payment performance.

The **Aperçu** (Overview) page is your starting point after logging into the Flouci business dashboard. It provides a snapshot of your payment activity and quick access to all dashboard features.

## Performance overview

Under **"Vue d'ensemble des performances"**, you can review aggregated transaction data for any selected period:

* **Total transaction volume** — the sum of all processed payments
* **Total transactions** — the number of individual transactions
* **Trend indicators** — showing whether performance is stable, growing, or declining

## Search and filters

Use the toolbar to find specific transactions or narrow your view:

| Control | Description |
| - | - |
| **Rechercher…** | Search by keyword — transaction reference, customer name, etc. |
| **Date Range** | Select a specific time period to analyze |
| **Statut** | Filter by payment status: Paid, Pending, or Failed |
| **Filtres avancés** | Granular filters for payment method, terminal, amount, and more |
| **Réinitialiser** | Clear all active filters |


# Settings
Source: https://docs.flouci.com/dashboard/settings

Manage your business profile, team members, and dashboard preferences.

The **Paramètres** (Settings) section lets you configure your account, manage access, and personalize the dashboard.

## Business profile

Update your public-facing business information:

* Logo
* Business name
* Email and phone number
* Address
* Business type

## Manage users

Control who has access to your business dashboard:

<Steps>
  <Step title="View users">
    See all authorized users and their assigned roles.
  </Step>

  <Step title="Add a user">
    Click **"+ Ajouter un utilisateur"**, enter their details, and assign a role.
  </Step>

  <Step title="Edit or remove">
    Use the **⋯ Actions** menu on any user to change permissions or revoke access.
  </Step>
</Steps>

## Language

Set your preferred dashboard language from the dropdown and click **"Sauvegarder"** to apply.


# Settlements
Source: https://docs.flouci.com/dashboard/settlements

Request payouts and track fund transfers to your bank account.

The **Règlements** (Settlements) section manages the transfer of your Flouci balance to your bank account.

## Balance summary

At the top of the page, you see two key figures:

* **Solde disponible** — funds ready for payout
* **En traitement** — funds currently being processed

## Request a settlement

Click **"Demander un règlement"** to initiate a payout. The settlement amount equals your available balance minus transaction fees and settlement request fees.

<Info>
  Settlement requests are processed during business hours. Check the **Statut** column in your history for real-time status updates.
</Info>

## Settlement history

Each entry in the history table shows:

| Field | Description |
| - | - |
| **Date / Heure** | When the settlement was requested |
| **Statut** | Current status (pending, completed, etc.) |
| **Montant total** | Gross settlement amount |
| **Frais** | Fees deducted |
| **Montant net** | Net amount transferred to your bank |

Click the **receipt icon** on any entry to download proof of settlement.

Use the **Statut** filter to view only pending or completed settlements, and click **Exporter** to download settlement history for your records.


# Transactions
Source: https://docs.flouci.com/dashboard/transactions

View and manage all payment transactions across wallet, card, and check methods.

The **Mouvements** (Transactions) section logs all payment activity across every payment method. Use it for bookkeeping, reconciliation, and tracking individual payments.

## Transaction tabs

Select the tab matching the payment method you want to review:

<Tabs>
  <Tab title="Wallet Transactions">
    Shows all Flouci Wallet payments and cash-outs.
  </Tab>

  <Tab title="Card Transactions">
    Displays all Visa and Mastercard transactions.
  </Tab>

  <Tab title="Check Transactions">
    Lists all check-based payments.
  </Tab>
</Tabs>

## Transaction details

Each transaction entry shows:

| Field | Description |
| - | - |
| **Nom** | Customer or operation name |
| **Date / Heure** | Transaction date and time |
| **Note** | Invoice or order reference |
| **Statut** | Payment status |
| **Montant** | Amount — green (+) for incoming, red (-) for outgoing |

## Filter and export

<Steps>
  <Step title="Search">
    Use **Rechercher…** to find a specific transaction by keyword.
  </Step>

  <Step title="Set date range">
    Define a time window with **Date de début** and **Date de fin**.
  </Step>

  <Step title="Filter by status">
    Use the **Statut** dropdown to isolate paid, pending, or failed transactions.
  </Step>

  <Step title="Export">
    Click **Exporter** to download filtered data as a file for accounting or audit purposes.
  </Step>
</Steps>


# Debugging and support
Source: https://docs.flouci.com/essentials/debug-support

How to get in touch if you need assistance during your integration

For development and integration support, contact:\
**[dev-support@flouci.com](mailto:dev-support@flouci.com)**

For sales questions or general inquiries, contact:\
**[sales@flouci.com](mailto:sales@flouci.com)**

We'll get back to you as quickly as possible!


# Error Dictionary
Source: https://docs.flouci.com/essentials/error-dictionary

Card payment error codes, what they mean, and how to handle them.

When a card payment is declined, the card processing platform returns an error code and a short message. This page lists the codes observed in production, explains what each one means, and gives the action we recommend for your customer.

<Info>
  **Note:** The message in the **Message returned** column is passed through exactly as the processing platform sends it, in English. The list below is built from refusals observed in production — the platform may return other codes that are not listed here. If you hit one, [contact support](/essentials/debug-support) with the order reference.
</Info>

### Error codes

Use your browser's find (`Ctrl` / `Cmd` + `F`) to jump to a code.

| Code | Message returned (verbatim) | What it means | Recommended action |
| - | - | - | - |
| `-2019` | `Decline by iReq in PARes` | 3-D Secure authentication was refused by the issuing bank during verification. | Offer the customer a new payment attempt, or another card. |
| `-2018` | `Declined. DS connection timeout` | Timeout while connecting to the 3-D Secure authentication service. | Temporary incident. Ask the customer to try again in a few minutes. |
| `-2013` | `Customer has no more payment attempts left on this order number` | The number of payment attempts allowed for this order has been used up. | Do not retry on the same order — create a new payment. |
| `-2007` | `Order expired after session time limit/Customer did not complete the authentication in timely manner` | The payment session expired before the customer completed authentication. | Create a new payment. Consider a longer session duration if this happens often. |
| `-2006` | `Issuer Rejected Authentication - card not authenticated/account not verified/transaction denied, ARES.STATUS = N [TDS_AUTH_FAILED]` | The issuing bank did not authenticate the cardholder. | Offer the customer a new payment attempt, or a card enrolled in 3-D Secure. |
| `76` | `Rejected Authorization - Issuer bank is not able to process the transaction Cannot process transaction]` | The issuing bank is unable to process the transaction. | Temporary incident on the bank side. Ask the customer to try again later. |
| `100` | `Rejected Authorization - Card Limit Exceed [Limit exceeded]` | The card limit has been reached. | Tell the customer their card limit is reached and offer another card. |
| `103` | `Contact issuer.` | The issuing bank is asking the cardholder to contact it. | Ask the customer to contact their bank before retrying. |
| `106` | `PIN attempts exceeded. Card is blocked.` | Too many incorrect PIN entries: the card is blocked. | Tell the customer their card is blocked and offer another card. |
| `110` | `Rejected Authorization - Invalid amount [Invalid amount]` | The amount sent is not valid. | Check the amount format and the currency unit. Contact Flouci support if the problem persists. |
| `111` | `Decline. Wrong PAN` | The card number sent is incorrect. | Ask the customer to check their card number. |
| `116` | `Rejected Authorization - Low Balance [116: Not enough money]` | The card balance is insufficient. | Tell the customer the balance is too low and offer another card. |
| `117` | `processing.error.117` | A processing error returned by the gateway, with no detailed description. | Report the case to Flouci support with the order reference. |
| `119` | `Security violation` | The request was rejected for security reasons. | Report the case to Flouci support with the order reference. |
| `120` | `Rejected Authorization - restricted transaction [Transaction was refused]` | The transaction is refused: this operation is not allowed on this card. | Tell the customer the payment was refused and offer another card. |
| `121` | `Rejected Authorization - Limit Exceed [Limit exceeded]` | The authorized limit was exceeded. | Tell the customer their card limit is reached and offer another card. |
| `125` | `Rejected Authorization - Invalid card number [Invalid card number]` | The card number is not valid. | Ask the customer to check their card number. |
| `903` | `Limit exceeded.` | The authorized limit was exceeded. | Tell the customer their card limit is reached and offer another card. |
| `904` | `Invalid message format` | The request sent to the gateway is not correctly formed. | Check the parameters sent to the API. Contact Flouci support if the problem persists. |
| `910` | `Rejected Authorization - Issuer bank not available [Cannot contact bank]` | The issuing bank could not be reached. | Temporary incident. Ask the customer to try again in a few minutes. |
| `913` | `Invalid message format.` | The request sent to the gateway is not correctly formed. | Check the parameters sent to the API. Contact Flouci support if the problem persists. |
| `2003` | `Non-3DS is not allowed - SSL_FORBIDDEN` | A transaction without 3-D Secure authentication was submitted, and it is not allowed. | Contact Flouci support: the merchant account configuration needs to be checked. |
| `100700` | `Challenge was cancelled by the issuer. Authentication has not been sent to Stand-In` | The issuing bank cancelled the authentication step. | Offer the customer a new payment attempt, or another card. |
| `100801` | `Rejected Authorization - Response not received from SvFE [Timer time out]` | No response was received from the card network within the allotted time. | Check the final state of the order before retrying, to avoid a double debit. |
| `100827` | `Rejected Authorization [Do not honor transaction]` | The issuing bank refused the authorization without giving a reason. | Show a generic refusal message. Invite the customer to retry or use another card. |
| `151018` | `EPG Acquirer is not connected to SvFE [CANNOT_SEND_REQUEST]` | The card network is temporarily unreachable. | Temporary incident on the platform side. Ask the customer to try again later. |
| `151019` | `Payment failed. Cann't connect to Payment Gate.` | The connection to the payment gateway failed. | Temporary incident on the platform side. Ask the customer to try again later. |
| `341016` | `Issuer Rejected Authentication - card not authenticated, ARES.STATUS = R [3DS2 authentication is declined by Authentication Response (ARes)]` | The issuing bank refused the 3-D Secure authentication. | Offer the customer a new payment attempt, or another card. |
| `341017` | `Authentication status in ARes is unknown, ARES.STATUS = U` | The result of the 3-D Secure authentication is undetermined. | Temporary incident. Offer the customer a new payment attempt. |
| `341018` | `Issuer Rejected Authentication - Authentication cancelled by customer, RREQ/CRES.STATUS = N [3DS2 CReq cancelled]` | The customer cancelled the 3-D Secure authentication. | This is not a card refusal: simply offer to restart the payment. |
| `341019` | `Issuer Rejected Authentication - CREQ/CRES has error [3DS2 CReq failed]` | An error occurred during the 3-D Secure authentication exchange. | Temporary incident. Offer the customer a new payment attempt. |
| `341020` | `Issuer Rejected Authentication - RREQ.STATUS = U or R [3DS2 unknown status in RReq]` | The 3-D Secure authentication result is unknown or rejected. | Temporary incident. Offer the customer a new payment attempt. |
| `341022` | `Issuer Rejected Authentication - TimeOut ACS bcz customer did not provide OTP with in 10 minutes` | The customer did not enter their verification code (OTP) within the 10-minute window. | This is not a card refusal: simply offer to restart the payment. |
| `341023` | `Issuer Rejected Authentication - TimeOut ACS bcz OTP page is not opened to customer with in 30 Secs` | The verification code (OTP) page did not open within the allotted time. | This is not a card refusal: simply offer to restart the payment. |
| `341024` | `Issuer Rejected Authentication - Exceed OTP attempts` | The customer exceeded the number of allowed verification code (OTP) entries. | This is not a card refusal: simply offer to restart the payment. |
| `341025` | `Issuer Rejected Authentication - CAVV is not generated by issuer, RREQ.STATUS = N` | The issuing bank did not generate the 3-D Secure authentication certificate. | Offer the customer a new payment attempt, or another card. |
| `342034` | `Operation cancelled by user` | The customer cancelled the operation. | This is not a card refusal: simply offer to restart the payment. |

### Handling patterns

Most of the codes above fall into one of the following patterns. If you only implement one behaviour per pattern, implement these.

<AccordionGroup>
  <Accordion title="An ordinary decline — offer another card">
    `-2019`, `-2006`, `100`, `103`, `106`, `110`, `111`, `116`, `120`, `121`, `125`, `903`, `100700`, `100827`, `341016` and `341025` are refusals of that specific card: insufficient balance, limit reached, blocked card, wrong number, or an issuer refusal. Show the refusal and invite the customer to pay with a different card. Do not reveal why the issuer refused beyond what the table suggests.
  </Accordion>

  <Accordion title="Never retry on the same order">
    `-2013` and `-2007` mean the order itself is finished — the attempt budget is spent, or the session expired. Retrying the same `payment_id` will keep failing. Create a new payment instead.
  </Accordion>

  <Accordion title="Verify before retrying, to avoid a double debit">
    `100801` means the card network never answered within the timeout, so the outcome is genuinely unknown — the customer may have been debited. Always check the final state of the order with [Verify Payment](/api-reference/verify-transaction) before offering a retry.
  </Accordion>

  <Accordion title="Temporary — a retry is likely to succeed">
    `-2018`, `76`, `910`, `151018`, `151019`, `341017`, `341019`, `341020` are timeouts or unreachable-service errors on the bank or platform side. Show a "please try again shortly" message rather than a refusal.
  </Accordion>

  <Accordion title="Not a refusal — the customer simply stopped">
    `341018`, `341022`, `341023`, `341024`, `342034` mean the customer cancelled or let the 3-D Secure step time out. The card is fine. Offer to restart the payment without suggesting anything is wrong with their card.
  </Accordion>
</AccordionGroup>

## Recurring payments error codes

The [Recurring Payments](/api-reference/recurring-payments/overview) endpoints report refusals with the HTTP status below and a code: in `result.error` on **Create**, in `message` on the other endpoints. A field that fails validation on Create is returned as `{"<field>": ["<reason>"]}` without a code. These are API-level refusals, not card declines.

| HTTP | `message` | Endpoint | What it means | Recommended action |
| - | - | - | - | - |
| `400` | field `currency` | Create | `currency` is not `TND`. | Send `TND` — subscriptions are TND only. |
| `400` | field `destination` | Create | A split-payment `destination` was attached to a subscription. | Remove `destination`. |
| `400` | field `interval_count` | Create | `interval` × `interval_count` exceeds one year (366 days · 52 weeks · 12 months · 1 year). | Shorten the cycle. |
| `400` | `card_recurring_not_enabled` | Create | `accept_card: true` while card recurring is not enabled on your affiliation. | Create a wallet subscription (omit `accept_card`) or contact your Flouci contact. |
| `400` | `card_recurring_not_implemented` | Create | Card recurring is enabled for you but not yet live. | Create a wallet subscription for now. |
| `400` | `invalid_subscription_id` | Get, Charges, Cancel | The `subscription_id` in the path is malformed. | Use the value returned by Create Subscription. |
| `403` | `merchant_not_allowed` | Create, List | Your merchant account does not have developer API access. | [Contact support](/essentials/debug-support). |
| `403` | `merchant_wallet_inactive` | Create | Your merchant wallet is inactive. | [Contact support](/essentials/debug-support). |
| `403` | `affiliation_inactive` | Create | Your card affiliation is inactive. | [Contact support](/essentials/debug-support). |
| `404` | `subscription_not_found` | Get, Charges, Cancel | No subscription with this id belongs to your merchant. | Check the id. Another merchant's id is never disclosed. |
| `409` | `duplicate_developer_tracking_id` | Create | A subscription with this `developer_tracking_id` already exists; its ids are in the body. | Treat as success and use the returned `subscription_id` and `link`. |
| `409` | `subscription_terminal` | Cancel | The subscription is already `canceled` or `incomplete_expired`. | Nothing to do. |
| `409` | `subscription_not_active` | Cancel | `at_period_end: true` on a subscription that is not `active` or `past_due`. | Cancel immediately instead. |
| `429` | — | Create | More than 60 creations per minute for this app. | Back off and retry. |
| `503` | `recurring_payments_disabled` | Create | Recurring payments are temporarily paused platform-wide. | Retry later; existing subscriptions are deferred, not failed. |

Two refusals happen on the customer's side, in the Flouci app, and never reach your API: `consent_required` (the app did not present the current consent text) and `subscription_not_payable` (the first charge is no longer payable, for example after you canceled). Both leave the subscription untouched.


# Go Live
Source: https://docs.flouci.com/essentials/production

Activate your production keys and start accepting real payments.

Once your KYB verification is approved, you can switch from sandbox to production.

<Note>
  If you haven't completed the merchant onboarding yet, follow the steps in [Create an Account](/getting-started/create-an-account) first.
</Note>

## Activation timelines

| Feature | Timeline |
| - | - |
| **Initial Review** | 1–2 business days |
| **Check Reservation** | Active upon initial review |
| **Wallet Acceptance** | 2-4 business days (external verification required) |
| **Card Acceptance** | 4-10 business days (external verification required) |

## Switch to production

<Steps>
  <Step title="Get your production credentials">
    Once approved, go to **Accepter en ligne > API** in your [business dashboard](https://app.flouci.com). Your production application will have a **Public Token** and **Private Token** ready to use.
  </Step>

  <Step title="Update your base URL">
    The sandbox base URL and production URL in your integration stay the same, only the intergation keys change:

    | Environment | Base URL |
    | - | - |
    | Sandbox | `https://developers.flouci.com` |
    | Production | `https://developers.flouci.com` |
  </Step>

  <Step title="Update your API credentials">
    Swap your test keys for the production **Public Token** and **Private Token** from your dashboard.

    <Warning>
      Keep your private token secret and only use it in backend code.
    </Warning>
  </Step>

  <Step title="Verify your integration">
    Run a small real transaction to confirm everything works end-to-end: generate a payment, complete it, and verify the status.

    <Check>
      You are now live and accepting real payments.
    </Check>
  </Step>
</Steps>


# Test Environment
Source: https://docs.flouci.com/essentials/testing

Learn how to use the test environment.

With each developer account, you will automatically have a test application called **TEST APP**. You can use the `PUBLIC_KEY` and `PRIVATE_KEY` of the test app during the integration of the payment on your site.

### Wallet Payments

Currently, there are no dedicated tests for wallet payments in the test environment. However, wallet payments will work automatically when you switch to production. For examples of wallet payment payloads and responses, please refer to the [Verify Payment](../api-reference/verify-transaction) endpoint documentation.

### Card Payments

| Card Type | Test Case | Card Number | Expiration Date | CVV |
| :- | :-: | -: | :-: | -: |
| Visa | Successful Payment | 4509 2111 1111 1119 | 12/26 | 748 |
| MasterCard | Successful Payment | 5440 2127 1111 1110 | 12/26 | 665 |
| MasterCard | Failed Payment | 5471 2511 1111 1116 | 11/23 | 858 |

### Transaction Verification

In the test environment, `verify_payment` keeps the transaction status information for 20 minutes. You can check the status of the transaction with the `payment_id` during this period to finalize the integration on your website.

In the test environment, the information is not visible in any dashboard, and is accessible via API only. Once you move to production keys, all transactions can be monitored in real-time via our web interface [https://app.flouci.com](https://app.flouci.com).


# Create an Account
Source: https://docs.flouci.com/getting-started/create-an-account

Sign up for Flouci Gateway and complete the merchant onboarding process.

Flouci Gateway is available for all types of registered businesses in Tunisia, including auto-entrepreneurs, sole proprietors, SUAL, SARL, and SA.

<Info>
  After you upload your RNE, you get instant access to the Flouci API sandbox so you can start testing and integrating right away — even before your KYB review is complete.
</Info>

<AccordionGroup>
  <Accordion title="Activation timelines">
    | Feature | Timeline |
    | - | - |
    | **Initial Review** | 1–2 business days |
    | **Check Reservation** | Active upon initial review |
    | **Wallet Acceptance** | 2-4 business days (external verification required) |
    | **Card Acceptance** | 4-10 business days (external verification required) |
  </Accordion>
</AccordionGroup>

## Merchant onboarding workflow

<Steps>
  <Step title="Create your business account">
    1. Go to [app.flouci.com](https://app.flouci.com) and sign in (or sign up with your phone number).
    2. Click your **username** in the top left corner.
    3. Select **"Ajouter un compte de travail"** (Add a work account).
    4. Click on your **merchant account** to access the business dashboard.
  </Step>

  <Step title="Start the onboarding checklist">
    Look for the banner titled **"Compléter la liste de vérification"** on your dashboard.

    <Warning>
      If you already have an active affiliation for a website, **do not resubmit**. Only submit a new request if you want to add a different affiliation (e.g., POS or a new e-commerce site).
    </Warning>

    Click **"Accepter les paiements"** to begin the verification workflow.

    <Note>
      You can also start onboarding from the sidebar: **Accepter en ligne > Compléter l'inscription** or **En magasin > Compléter l'inscription**.
    </Note>
  </Step>

  <Step title="Verify the legal representative">
    Answer the question: *"Are you the legal representative (gérant) listed in the RNE?"*

    <Tabs>
      <Tab title="Yes — I am the gérant">
        * Select **Oui** in the **Vérification du Représentant** section.
        * Scan your **CIN** (national ID) in the Flouci mobile app using the phone number linked to your gateway account.
      </Tab>

      <Tab title="No — I am not the gérant">
        * Select **Non** and enter the actual gérant's information.
        * If the gérant is **Tunisian**, they must complete CIN verification through the Flouci mobile app.
        * If the gérant is **foreign**, upload a copy of their **passport** and add the **company status document** (signed and stamped) under **Documents supplémentaires**.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Provide business details">
    Fill in your business public information:

    * **Business contact phone number**
    * **Business email**
    * **Estimated annual turnover**

    Then choose your **payment acceptance solutions** — you can select multiple:

    <CardGroup>
      <Card title="In-Store Terminal" icon="shop">
        Accept payments at your physical location. You will need to provide your **shop address**.
      </Card>

      <Card title="Pay-by-Link" icon="link">
        Send payment links via WhatsApp, Messenger, or email.
      </Card>

      <Card title="Website Integration" icon="code">
        Connect Flouci to your website or mobile app. You will need to provide the **website URL** or **app demo link**.
      </Card>

      <Card title="Online Catalog" icon="store">
        Sell online without a website using a hosted product page.
      </Card>
    </CardGroup>

    Finally, write a **business narrative** (minimum 100 characters) describing what you sell, who your customers are, and your expected payment flows. A clear description helps our team review your application faster.
  </Step>

  <Step title="Add your bank account">
    Provide your settlement bank account details:

    <ParamField type="string">
      Must start with **TN59** and contain 24 digits.
    </ParamField>

    <ParamField type="string">
      Must match the company name or legal representative name exactly.
    </ParamField>

    <Info>
      You do not need to be banked with one of Flouci's partner banks to accept payments.
    </Info>
  </Step>

  <Step title="Declare UBOs and Executives">
    This section has two parts:

    **Part A — Ultimate Beneficial Owners (UBOs)**

    * Declare all individuals owning **20% or more** of capital or voting rights.
    * Include anyone with **effective control**, even if their share is below 20%.
    * For corporate shareholders, trace through to the **natural persons** behind them.
    * If no individual exceeds 20%, declare the **company's legal representative**.

    **Part B — Executives**

    * Declare all **official executives** listed on the RNE.
    * Ensure names and roles are **accurate and up to date**.
  </Step>

  <Step title="Upload your tax document">
    Upload your **Patente** (company tax registration document).
  </Step>

  <Step title="Sign and submit the contract">
    1. Download the **generated contract**.
    2. **Sign and stamp** the contract physically — do not edit, type, or paste a digital signature.
    3. Upload the signed contract and submit your application.

    <Check>
      Once submitted, your application enters review. You will receive an email confirmation from **[noreply@flouci.com](mailto:noreply@flouci.com)**.
    </Check>
  </Step>
</Steps>

## Application status

After submitting, your dashboard banner updates to reflect your current status:

| Banner message | Meaning |
| - | - |
| **"Vérifier l'identité"** | Your individual account verification is pending. You will be redirected to the Flouci mobile app to complete it. |
| **"Action requise : Informations manquantes"** | The verification team needs additional information. Check your email from **[noreply@flouci.com](mailto:noreply@flouci.com)** for details. |
| **No banner** | Your account is fully verified and active. |

You can also invite team members to your company account to help with setup, integration, finances, and managing your Flouci Gateway together.


# Payment Steps
Source: https://docs.flouci.com/getting-started/payment-step

Learn about the payment step in the Flouci payment process.

The Flouci web payment solution is based on a redirection mechanism. The user is redirected to a payment page, where they can pay with one of the payment methods activated by the merchant (Flouci wallet, bank card/e-dinar, other wallet, etc.).

Based on the transaction outcome, the user is redirected to the merchant's site using the `success_link` or `fail_link` variables. Additionally, an optional `webhook` field enables the Flouci system to notify the partner server-to-server when a transaction is complete, ensuring reliability in cases of network issues and providing a more comprehensive payment handling system. Each webhook call is signed so you can check that it comes from Flouci: see [Payment Webhooks](/api-reference/payment-webhooks).

<Steps>
  <Step title="Initiate Payment">
    <p>To start a payment, the merchant must generate a payment request using the Flouci API. This involves specifying the amount, currency, and other transaction details.</p>
  </Step>

  <Step title="Redirect to Payment Page">
    <p>Once the payment request is generated, redirect the user to the Flouci payment page. The user can choose their preferred payment method and complete the transaction.</p>
  </Step>

  <Step title="Handle Transaction Outcome">
    <p>After the transaction, the user is redirected back to the merchant's site using the `success_link` or `fail_link`. Additionally, configure a `webhook` to receive server-to-server notifications for transaction completions.</p>
  </Step>
</Steps>


# How to Build Requests
Source: https://docs.flouci.com/getting-started/requests

How to build requests to the Flouci Payment API, including authentication with public and secret keys.

The Flouci Payment API is built on REST principles and requires all requests to be made over HTTPS (TLS 1.2 or higher). Any requests sent over plain HTTP will be rejected.

## Authentication

To authenticate your requests, you must include an `Authorization` header in every API call. The value of this header should be your `public_key` and `secret_key` joined by a colon, in the following format: `Bearer <PUBLIC_KEY>:<PRIVATE_KEY>`

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST '@IP/api/v2/generate_payment' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer <PUBLIC_KEY>:<PRIVATE_KEY>' \
  ```
</RequestExample>


# Introduction
Source: https://docs.flouci.com/introduction



Welcome to the Flouci Payment API documentation. Flouci is a comprehensive financial super-app, authorized by the Central Bank of Tunisia, designed for individuals, sole traders, and businesses. Our core banking services, launched in partnership with local banks, equip users with essential financial management tools.

<Info>
  As a licensed Payment Facilitator, we assist businesses of all sizes provide them with tools to facilitate smoother payment acceptance across a wide range of methods:

  * Flouci wallets
  * Other digital wallets licensed by the Central Bank of Tunisia
  * Bank cards
  * Post office cards
  * Checks
</Info>

### Payment Integration types

Merchants can choose from two main options for accepting payments:

1. **Basic Payment Links and Hosted Product Pages**:
   * Ideal for quick and easy transactions without the need for coding or self-hosting a platform.
   * Shareable via email, WhatsApp, and more.

2. **API-based Integrations**:
   * Perfect for businesses requiring customization and control.
   * Supports complex payment flows such as:
     * Generate QR codes for embedding in external systems
     * Pre-authorization payments
     * Webhooks
     * Payment orchestrations
     * Embedded wallet systems with one-click native payment integrations

These solutions provide merchants with complete flexibility over their payment acceptance processes, ensuring a seamless experience for both the business and its clients.

<Info>
  You do not need to be banked with one of Flouci's partner banks to accept payments using Flouci APIs.
</Info>


# Plugins
Source: https://docs.flouci.com/plugins/plugins



We offer powerful plugins for popular e-commerce platforms like WordPress (WooCommerce), PrestaShop, Magento and Shopify, designed to streamline your payment processing. Integrating Flouci into your online store is as simple as installing the appropriate plugin and configuring it with your account credentials.

Once set up, you can begin accepting transactions immediately, with no complex coding or development required. This allows you to focus on your business while we handle the secure and reliable payment flow.

You can download the plugins directly from your business dashboard at [app.flouci.com](https://app.flouci.com) under **Accepter en ligne > Plugins**.