Transférer vers un compte mobile money

curl --request POST \
  --url https://guichet.apidjonanko.tech/v1/cashout \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --header 'x-api-secret: <api-key>' \
  --data '
{
  "amount": 25000,
  "country": "CI",
  "operator": "WAVE",
  "beneficiaryPhone": "0501020304",
  "beneficiaryName": "Koffi Yao"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'x-api-secret': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 25000,
    country: 'CI',
    operator: 'WAVE',
    beneficiaryPhone: '0501020304',
    beneficiaryName: 'Koffi Yao'
  })
};

fetch('https://guichet.apidjonanko.tech/v1/cashout', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://guichet.apidjonanko.tech/v1/cashout"

payload = {
    "amount": 25000,
    "country": "CI",
    "operator": "WAVE",
    "beneficiaryPhone": "0501020304",
    "beneficiaryName": "Koffi Yao"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "x-api-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://guichet.apidjonanko.tech/v1/cashout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 25000,
    'country' => 'CI',
    'operator' => 'WAVE',
    'beneficiaryPhone' => '0501020304',
    'beneficiaryName' => 'Koffi Yao'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>",
    "x-api-secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

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

{
  "operation": {
    "reference": "GUI-CO-20261001-4F7K2M9Q",
    "type": "CASHOUT",
    "status": "PENDING",
    "amount": 25000,
    "fees": 500,
    "netAmount": 25500,
    "currency": "XOF",
    "country": "CI",
    "operator": "WAVE",
    "counterparty": {
      "phoneNumber": "+2250501020304",
      "name": "Koffi Yao"
    },
    "externalReference": "PAIE-2026-03-0042",
    "description": "Salaire mars 2026",
    "payerActionUrl": null,
    "requiresPayerAction": false,
    "failure": null,
    "metadata": null,
    "createdAt": "2026-10-01T11:01:50.000Z",
    "updatedAt": "2026-10-01T11:01:52.000Z",
    "completedAt": null,
    "expiresAt": "2026-10-01T17:01:50.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La requête est invalide.",
    "details": {
      "fields": [
        "amount must be an integer number"
      ]
    }
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2026-10-01T10:12:04.000Z"
}

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Identifiants API invalides."
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2026-10-01T10:12:04.000Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {
      "available": 12000,
      "required": 25500,
      "currency": "XOF"
    }
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2026-10-01T10:12:04.000Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

Transfert

Transférer vers un compte mobile money

Verse le montant au bénéficiaire et prélève votre portefeuille du montant plus la commission.

Immobilisation

Dès l’acceptation, le montant et la commission sont immobilisés : ils quittent votre solde disponible sans encore être débités.

transfert exécuté → ils sont débités, balance diminue ;
transfert échoué → l’immobilisation est levée, votre solde retrouve son niveau.

C’est ce mécanisme qui vous empêche d’engager deux fois le même solde pendant qu’un transfert est en cours.

L’issue définitive arrive par notification (cashout.succeeded / cashout.failed). Un transfert sans issue au bout de 6 heures passe en EXPIRED et l’immobilisation est levée.

Cet endpoint exige une clé de production (gk_live_). Une clé de test est refusée.

POST

cashout

Transférer vers un compte mobile money

curl --request POST \
  --url https://guichet.apidjonanko.tech/v1/cashout \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --header 'x-api-secret: <api-key>' \
  --data '
{
  "amount": 25000,
  "country": "CI",
  "operator": "WAVE",
  "beneficiaryPhone": "0501020304",
  "beneficiaryName": "Koffi Yao"
}
'

const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '<idempotency-key>',
    'x-api-key': '<api-key>',
    'x-api-secret': '<api-key>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 25000,
    country: 'CI',
    operator: 'WAVE',
    beneficiaryPhone: '0501020304',
    beneficiaryName: 'Koffi Yao'
  })
};

fetch('https://guichet.apidjonanko.tech/v1/cashout', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://guichet.apidjonanko.tech/v1/cashout"

payload = {
    "amount": 25000,
    "country": "CI",
    "operator": "WAVE",
    "beneficiaryPhone": "0501020304",
    "beneficiaryName": "Koffi Yao"
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "x-api-key": "<api-key>",
    "x-api-secret": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://guichet.apidjonanko.tech/v1/cashout",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 25000,
    'country' => 'CI',
    'operator' => 'WAVE',
    'beneficiaryPhone' => '0501020304',
    'beneficiaryName' => 'Koffi Yao'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>",
    "x-api-key: <api-key>",
    "x-api-secret: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

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

{
  "operation": {
    "reference": "GUI-CO-20261001-4F7K2M9Q",
    "type": "CASHOUT",
    "status": "PENDING",
    "amount": 25000,
    "fees": 500,
    "netAmount": 25500,
    "currency": "XOF",
    "country": "CI",
    "operator": "WAVE",
    "counterparty": {
      "phoneNumber": "+2250501020304",
      "name": "Koffi Yao"
    },
    "externalReference": "PAIE-2026-03-0042",
    "description": "Salaire mars 2026",
    "payerActionUrl": null,
    "requiresPayerAction": false,
    "failure": null,
    "metadata": null,
    "createdAt": "2026-10-01T11:01:50.000Z",
    "updatedAt": "2026-10-01T11:01:52.000Z",
    "completedAt": null,
    "expiresAt": "2026-10-01T17:01:50.000Z"
  }
}

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "La requête est invalide.",
    "details": {
      "fields": [
        "amount must be an integer number"
      ]
    }
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2026-10-01T10:12:04.000Z"
}

{
  "success": false,
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Identifiants API invalides."
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2026-10-01T10:12:04.000Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {
      "available": 12000,
      "required": 25500,
      "currency": "XOF"
    }
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2026-10-01T10:12:04.000Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Le solde disponible de votre portefeuille est insuffisant.",
    "details": {}
  },
  "requestId": "9f1c2b7e-4a5d-4c8f-b0a1-e2d3c4b5a697",
  "timestamp": "2023-11-07T05:31:56Z"
}

Le montant et la commission sont immobilisés dès l’acceptation : ils quittent available sans encore être débités de balance. À l’exécution ils sont débités ; en cas d’échec l’immobilisation est levée. Détail des mouvements : Portefeuille.Cet endpoint exige une clé de production (gk_live_) et l’en-tête Idempotency-Key.

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 à verser au bénéficiaire, en unités entières.

Required range: x >= 1

Example:

25000

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"

beneficiaryPhone

string

required

Numéro mobile money du bénéficiaire.

Maximum string length: 24

Example:

"0501020304"

beneficiaryName

string

required

Nom du bénéficiaire. Exigé par les opérateurs et repris sur votre relevé.

Maximum string length: 160

Example:

"Koffi Yao"

externalReference

string

Votre identifiant d'opération. Unique sur votre compte : c'est votre garde-fou contre le double décaissement.

Maximum string length: 120

Example:

"PAIE-2026-03-0042"

description

string

Maximum string length: 200

Example:

"Salaire mars 2026"

callbackUrl

string<uri>

URL de notification propre à cette opération. HTTPS obligatoire.

metadata

object

Response

Rejeu idempotent — la réponse initiale est renvoyée.

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

Transférer vers un compte mobile money

Immobilisation

Authorizations

Headers

Body

Response