Portefeuille

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.

curl https://guichet.apidjonanko.tech/v1/merchants/me/wallet \
  -H "x-api-key: gk_live_…" -H "x-api-secret: gs_live_…"

{
  "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

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.

L’immobilisation, étape par étape

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

Avant la demande

balance   100 000
reserved        0
available 100 000

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.

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).

…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é.

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.

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

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.

{
  "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"
    }
  ]
}

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é.

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

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 :

Encaissement
Transfert

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).

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.

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).

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 vous donne totalToDebit sans rien engager.

La commission est figée à la création

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.

Consulter votre barème

curl https://guichet.apidjonanko.tech/v1/merchants/me \
  -H "x-api-key: gk_live_…" -H "x-api-secret: gs_live_…"

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

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.

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. Pour le détail, filtrez le relevé :

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_…"

Premiers pas

Concepts

Encaissement

Transfert

Opérations

Notifications

Sécurité — IPs autorisées

Compte & clés

Encaissement

Transfert

Opérations

Compte

Portefeuille

Sécurité

Notifications

Portefeuille

Les trois montants

L’immobilisation, étape par étape

Statut du portefeuille

Relevé de mouvements

Les natures d’écriture

Isoler les mouvements d’une opération

Commission

Barème par défaut

Où elle s’applique

La commission est figée à la création

Consulter votre barème

Suivre ce que vous avez payé

​Les trois montants

​L’immobilisation, étape par étape

​Statut du portefeuille

​Relevé de mouvements

​Les natures d’écriture

​Isoler les mouvements d’une opération

​Commission

​Barème par défaut

​Où elle s’applique

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

​Consulter votre barème

​Suivre ce que vous avez payé

Les trois montants

L’immobilisation, étape par étape

Statut du portefeuille

Relevé de mouvements

Les natures d’écriture

Isoler les mouvements d’une opération

Commission

Barème par défaut

Où elle s’applique

La commission est figée à la création

Consulter votre barème

Suivre ce que vous avez payé