curl --request POST \
  --url https://guichet.apidjonanko.tech/v1/cashin \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --header 'x-api-secret: <api-key>' \
  --data '
{
  "amount": 5000,
  "country": "CI",
  "operator": "ORANGE",
  "payerPhone": "0701020304"
}
'

{
  "operation": {
    "reference": "GUI-CI-20261001-7K2M9QX4",
    "type": "CASHIN",
    "status": "CREATED",
    "amount": 5000,
    "fees": 100,
    "netAmount": 4900,
    "currency": "XOF",
    "country": "CI",
    "operator": "ORANGE",
    "counterparty": {
      "phoneNumber": "+2250701020304",
      "name": "Aya Koné"
    },
    "externalReference": "CMD-2026-00184",
    "description": "Commande 184",
    "payerActionUrl": "https://pay.example.com/s/abc123",
    "requiresPayerAction": true,
    "failure": {
      "code": "OPERATOR_INSUFFICIENT_FUNDS",
      "message": "Le solde du compte mobile money du payeur est insuffisant."
    },
    "metadata": {},
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z"
  }
}

Encaissement

Encaisser un paiement

Débite le compte mobile money du payeur et crédite votre portefeuille du montant net une fois l’encaissement confirmé.

Deux comportements selon l’opérateur :

Opérateurs	Statut renvoyé	Ce que vous avez à faire
MTN, Moov	`PENDING`	Rien. Le payeur reçoit une demande de validation sur son téléphone. Attendez la notification.
Orange, Wave, Djamo	`AWAITING_PAYER`	Envoyer votre client sur `payerActionUrl`. Sans cela l’encaissement n’aboutira jamais.

L’issue définitive arrive par notification (cashin.succeeded / cashin.failed). Une opération sans issue au bout de 30 minutes passe en EXPIRED.

POST

cashin

curl --request POST \
  --url https://guichet.apidjonanko.tech/v1/cashin \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --header 'x-api-secret: <api-key>' \
  --data '
{
  "amount": 5000,
  "country": "CI",
  "operator": "ORANGE",
  "payerPhone": "0701020304"
}
'

{
  "operation": {
    "reference": "GUI-CI-20261001-7K2M9QX4",
    "type": "CASHIN",
    "status": "CREATED",
    "amount": 5000,
    "fees": 100,
    "netAmount": 4900,
    "currency": "XOF",
    "country": "CI",
    "operator": "ORANGE",
    "counterparty": {
      "phoneNumber": "+2250701020304",
      "name": "Aya Koné"
    },
    "externalReference": "CMD-2026-00184",
    "description": "Commande 184",
    "payerActionUrl": "https://pay.example.com/s/abc123",
    "requiresPayerAction": true,
    "failure": {
      "code": "OPERATOR_INSUFFICIENT_FUNDS",
      "message": "Le solde du compte mobile money du payeur est insuffisant."
    },
    "metadata": {},
    "createdAt": "2023-11-07T05:31:56Z",
    "updatedAt": "2023-11-07T05:31:56Z",
    "completedAt": "2023-11-07T05:31:56Z",
    "expiresAt": "2023-11-07T05:31:56Z"
  }
}

Avec Orange, Wave et Djamo, la réponse porte requiresPayerAction: true et payerActionUrl : vous devez envoyer votre client sur cette URL, sinon l’encaissement n’aboutira jamais.Avec MTN et Moov, le statut est PENDING : votre client reçoit une demande de validation sur son téléphone, vous n’avez rien à afficher.Testez requiresPayerAction, ne codez pas la liste des opérateurs en dur.

L’en-tête Idempotency-Key est obligatoire. Dérivez-le de votre identifiant de commande, jamais une constante — voir Idempotence.

Authorizations

x-api-key

string

header

required

Votre clé publique, préfixée gk_live_ (ou gk_test_).

x-api-secret

string

header

required

Votre secret, préfixé gs_live_ (ou gs_test_). Affiché une seule fois, à l'émission de la clé. Il ne doit jamais quitter vos serveurs.

Headers

Idempotency-Key

string

required

Clé unique de votre côté, propre à cette intention d'opération. Un second appel portant la même clé et le même corps renvoie la réponse initiale sans rien réexécuter. 120 caractères maximum, conservée 24 heures.

Maximum string length: 120

Example:

"cmd-184-tentative-1"

x-request-id

string

Identifiant de corrélation de votre choix. Repris tel quel dans la réponse et dans nos journaux. À défaut, nous en générons un.

Maximum string length: 200

Body

application/json

amount

integer

required

Montant à encaisser, en unités entières. Aucune décimale.

Required range: x >= 1

Example:

5000

country

enum<string>

required

Pays, en ISO 3166-1 alpha-2.

Available options:

CI,

BF,

ML,

SN,

TG,

BJ,

NE,

CM,

GN

Example:

"CI"

operator

enum<string>

required

Opérateur mobile money. Tous ne sont pas disponibles dans tous les pays — voir le guide « Pays et opérateurs ».

Available options:

ORANGE,

MTN,

MOOV,

WAVE,

DJAMO

Example:

"ORANGE"

payerPhone

string

required

Numéro du payeur. Format national ou international, avec ou sans espaces — il est normalisé en E.164.

Maximum string length: 24

Example:

"0701020304"

payerName

string

Maximum string length: 160

Example:

"Aya Koné"

externalReference

string

Votre identifiant d'opération. Unique sur votre compte : une seconde opération portant la même valeur est refusée en 409. C'est votre garde-fou contre le double encaissement.

Maximum string length: 120

Example:

"CMD-2026-00184"

description

string

Maximum string length: 200

Example:

"Commande 184"

callbackUrl

string<uri>

URL de notification propre à cette opération. À défaut, celle de votre compte est utilisée. HTTPS obligatoire.

successUrl

string<uri>

Où renvoyer le payeur après un paiement réussi, quand une redirection est nécessaire.

errorUrl

string<uri>

Où renvoyer le payeur en cas d'échec.

metadata

object

Données libres, restituées telles quelles dans les notifications.

Example:

{ "cartId": "c_8891" }

Response

Rejeu idempotent : cette Idempotency-Key a déjà été traitée, la réponse initiale est renvoyée sans rien réexécuter.

operation

object

Représentation d'une opération. C'est la forme renvoyée par les endpoints de création, de consultation, et dans le corps des notifications.

Show child attributes

Premiers pas

Concepts

Encaissement

Transfert

Opérations

Portefeuille

Notifications

Sécurité — IPs autorisées

Compte & clés

Encaissement

Transfert

Opérations

Compte

Portefeuille

Sécurité

Notifications

Encaisser un paiement

Authorizations

Headers

Body

Response