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

# Portefeuille

> Solde, part immobilisée, et lecture du relevé de mouvements.

Votre compte possède **un seul portefeuille**. Les encaissements le créditent, les transferts le débitent. Il n'y a pas de compte de collecte distinct d'un compte de décaissement : vous n'avez donc rien à provisionner en double, ni à virer d'un compte à l'autre.

```bash theme={null}
curl https://guichet.apidjonanko.tech/v1/merchants/me/wallet \
  -H "x-api-key: gk_live_…" -H "x-api-secret: gs_live_…"
```

```json theme={null}
{
  "wallet": {
    "currency": "XOF",
    "balance": 500000,
    "reserved": 20000,
    "available": 480000,
    "status": "ACTIVE",
    "totalCollected": 12450000,
    "totalDisbursed": 11800000,
    "totalFees": 150000,
    "updatedAt": "2026-10-01T11:04:02.000Z"
  }
}
```

## Les trois montants

| Champ | Ce qu'il représente |
| - | - |
| `balance` | Le solde total que vous détenez |
| `reserved` | La part immobilisée par vos transferts en cours |
| `available` | `balance − reserved` — ce que vous pouvez réellement engager |

<Warning>
  **C'est `available` qui détermine ce que vous pouvez engager, pas `balance`.** Un transfert dont le total dépasse `available` est refusé en `402 INSUFFICIENT_BALANCE`, même si `balance` paraît suffisant.
</Warning>

## L'immobilisation, étape par étape

Prenons un portefeuille à 100 000 XOF et un transfert de 25 000 XOF, soit 500 XOF de commission à 2 %.

<Steps>
  <Step title="Avant la demande">
    ```
    balance   100 000
    reserved        0
    available 100 000
    ```
  </Step>

  <Step title="Transfert accepté — le montant et la commission sont immobilisés">
    ```
    balance   100 000   ← inchangé : l'argent est encore là
    reserved   25 500   ← mais il est engagé
    available  74 500
    ```

    Deux écritures apparaissent au relevé : `CASHOUT_HOLD`.
  </Step>

  <Step title="Transfert exécuté — l'immobilisation devient un débit">
    ```
    balance    74 500
    reserved        0
    available  74 500
    ```

    Trois écritures : `CASHOUT_RELEASE`, `CASHOUT_DEBIT` (25 000), `CASHOUT_FEE` (500).
  </Step>

  <Step title="…ou transfert échoué — l'immobilisation est levée">
    ```
    balance   100 000
    reserved        0
    available 100 000   ← votre solde retrouve son niveau
    ```

    Une écriture : `CASHOUT_RELEASE`. Rien n'a été débité.
  </Step>
</Steps>

<Note>
  C'est ce mécanisme qui vous empêche d'engager deux fois le même solde. Sans lui, deux transferts lancés simultanément pour la totalité de votre solde seraient tous les deux acceptés.
</Note>

Sur un **encaissement**, il n'y a pas d'immobilisation : le crédit arrive d'un coup, à la confirmation.

```
balance   100 000  →  104 900   (CASHIN_CREDIT 5 000, CASHIN_FEE 100)
```

## Statut du portefeuille

| `status` | Effet |
| - | - |
| `ACTIVE` | Normal |
| `FROZEN` | Aucun transfert accepté. Les encaissements en cours sont tout de même crédités, et une immobilisation en cours peut toujours être levée. |
| `CLOSED` | Aucun mouvement |

Un portefeuille `FROZEN` renvoie `403 WALLET_FROZEN` sur les transferts. Contactez votre référent Djonanko.

## Relevé de mouvements

```bash theme={null}
curl "https://guichet.apidjonanko.tech/v1/merchants/me/wallet/statement?limit=100" \
  -H "x-api-key: gk_live_…" -H "x-api-secret: gs_live_…"
```

Le relevé est **en ajout seul** : une ligne posée n'est jamais modifiée. Une correction prend la forme d'une écriture inverse (`REVERSAL_CREDIT` ou `REVERSAL_DEBIT`), de sorte que l'historique reste lisible.

Chaque ligne porte `balanceAfter`, le solde juste après l'écriture : vous pouvez rapprocher ligne à ligne avec votre comptabilité, sans rejouer toute la série.

```json theme={null}
{
  "total": 1842, "limit": 100, "offset": 0,
  "items": [
    {
      "sequence": 1842,
      "direction": "DEBIT",
      "kind": "CASHOUT_FEE",
      "amount": 500,
      "balanceAfter": 474500,
      "reservedAfter": 0,
      "operationReference": "GUI-CO-20261001-4F7K2M9Q",
      "createdAt": "2026-10-01T11:04:02.000Z"
    }
  ]
}
```

<Tip>
  Triez sur **`sequence`**, pas sur `createdAt`. Plusieurs écritures d'un même mouvement partagent l'horodatage à la milliseconde près ; `sequence` est strictement croissant et donne l'ordre réel du relevé.
</Tip>

### Les natures d'écriture

| `kind` | `direction` | Quand |
| - | - | - |
| `CASHIN_CREDIT` | `CREDIT` | Encaissement confirmé |
| `CASHIN_FEE` | `DEBIT` | Commission sur encaissement |
| `CASHOUT_HOLD` | `HOLD` | Transfert accepté, fonds immobilisés |
| `CASHOUT_RELEASE` | `RELEASE` | Immobilisation levée (exécution ou échec) |
| `CASHOUT_DEBIT` | `DEBIT` | Transfert exécuté |
| `CASHOUT_FEE` | `DEBIT` | Commission sur transfert |
| `REVERSAL_CREDIT` / `REVERSAL_DEBIT` | `CREDIT` / `DEBIT` | Contre-passation d'une opération réglée à tort |
| `ADJUSTMENT_CREDIT` / `ADJUSTMENT_DEBIT` | `CREDIT` / `DEBIT` | Régularisation (approvisionnement, geste commercial, correction) |

### Isoler les mouvements d'une opération

```bash theme={null}
curl "https://guichet.apidjonanko.tech/v1/merchants/me/wallet/statement?operationReference=GUI-CO-20261001-4F7K2M9Q" \
  -H "x-api-key: gk_live_…" -H "x-api-secret: gs_live_…"
```

Pratique pour un litige : vous obtenez les trois ou quatre écritures d'un transfert, dans l'ordre, avec les soldes intermédiaires.

## Commission

La commission Djonanko se calcule ainsi :

```
commission = arrondi(montant × bps / 10 000) + flat
```

* **`bps`** : taux en points de base. `200` vaut 2 %, `150` vaut 1,5 %.
* **`flat`** : part fixe, en unités entières de la devise. `0` par défaut.
* L'arrondi est **au plus proche**, sur l'entier.

### Barème par défaut

Sans tarif négocié, le barème est de **2 % dans les deux sens** :

| Sens | Taux | Part fixe |
| - | - | - |
| Encaissement (`cash-in`) | 2 % (`200` bps) | 0 |
| Transfert (`cash-out`) | 2 % (`200` bps) | 0 |

### Où elle s'applique

La commission ne s'applique pas du même côté selon le sens de l'opération :

<Tabs>
  <Tab title="Encaissement">
    La commission est **retenue sur le montant encaissé**. Votre client paie le montant plein, vous êtes crédité du net.

    Pour un encaissement de **5 000 XOF** :

    ```
    commission  =  arrondi(5 000 × 200 / 10 000)  =  100
    amount      =  5 000     ← ce que votre client paie
    fees        =    100
    netAmount   =  4 900     ← ce dont votre portefeuille est crédité
    ```

    Deux écritures au relevé : `CASHIN_CREDIT` (5 000) puis `CASHIN_FEE` (100).

    <Tip>
      Si vous voulez encaisser un montant net précis, calculez le montant brut à demander : pour recevoir 5 000 XOF nets à 2 %, demandez `arrondi(5 000 / 0,98)` = **5 102 XOF**.
    </Tip>
  </Tab>

  <Tab title="Transfert">
    La commission **s'ajoute au montant** : le bénéficiaire reçoit le montant plein, et votre portefeuille est prélevé du montant plus la commission.

    Pour un transfert de **25 000 XOF** :

    ```
    commission    =  arrondi(25 000 × 200 / 10 000)  =  500
    amount        =  25 000   ← ce que reçoit le bénéficiaire
    fees          =    500
    netAmount     =  25 500   ← ce qui est prélevé de votre portefeuille
    totalToDebit  =  25 500   ← et donc ce qu'il faut avoir en `available`
    ```

    Trois écritures au relevé : `CASHOUT_RELEASE`, `CASHOUT_DEBIT` (25 000), `CASHOUT_FEE` (500).

    <Warning>
      Prévoyez `available ≥ montant + commission`, pas seulement `available ≥ montant`. Un transfert de 25 000 XOF avec 24 800 XOF disponibles est refusé en `402 INSUFFICIENT_BALANCE`.

      [`GET /cashout/quote`](/guichet/api/cashout-quote) vous donne `totalToDebit` sans rien engager.
    </Warning>
  </Tab>
</Tabs>

### La commission est figée à la création

<Note>
  `operation.fees` est calculé une fois, à la création de l'opération, et **stocké sur celle-ci**. Une renégociation tarifaire ne modifie donc jamais la commission d'opérations déjà passées : vos relevés déjà émis restent exacts, et un rapprochement comptable sur un exercice clos reste reproductible.
</Note>

### Consulter votre barème

```bash theme={null}
curl https://guichet.apidjonanko.tech/v1/merchants/me \
  -H "x-api-key: gk_live_…" -H "x-api-secret: gs_live_…"
```

```json theme={null}
{
  "merchant": {
    "pricing": {
      "cashinFeeBps": 200, "cashinFeeFlat": 0,
      "cashoutFeeBps": 200, "cashoutFeeFlat": 0
    },
    "limits": {
      "minCashinAmount": 100, "maxCashinAmount": 2000000,
      "minCashoutAmount": 100, "maxCashoutAmount": 2000000,
      "dailyCashoutLimit": 0
    }
  }
}
```

<Tip>
  Lisez votre barème depuis cet endpoint plutôt que de le coder en dur. Si un taux négocié vous est appliqué, votre calcul reste juste sans redéploiement.
</Tip>

Le barème et les plafonds ne sont **pas modifiables par l'API** : ils sont contractuels. Leur évolution se demande à votre référent Djonanko. `dailyCashoutLimit` à `0` signifie qu'aucun plafond glissant sur 24 h n'est appliqué.

### Suivre ce que vous avez payé

Le cumul des commissions est dans `totalFees` sur [`GET /merchants/me/wallet`](/guichet/api/wallet). Pour le détail, filtrez le relevé :

```bash theme={null}
curl "https://guichet.apidjonanko.tech/v1/merchants/me/wallet/statement?kind=CASHIN_FEE&limit=200" \
  -H "x-api-key: gk_live_…" -H "x-api-secret: gs_live_…"
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.