Référence API - Neka Paie

POST /payments/cashin POST /payments/cashout GET /payments/{id} POST /refunds GET /balances GET /transactions/export

POST /api/v1/payments/cashin

Initie un paiement entrant client → marchand via Orange Money.

Body JSON

Champ	Type	Requis	Description
`merchant_order_id`	string	oui	Identifiant unique de la commande (idempotency key).
`amount`	integer	oui	Montant en plus petite unité de la devise.
`currency`	string(3)	non	Code ISO 4217 (XOF, XAF). Déduit du pays si omis.
`customer_msisdn`	string	oui	Numéro client format E.164 (`+22376123456`).
`country_code`	string(2)	non	Code ISO pays. Détecté automatiquement sinon.
`return_url`	string	non	URL de redirection après paiement.
`notify_url`	string	non	URL de webhook (override du webhook configuré).
`metadata`	object	non	Données libres (jusqu'à 10 clés).

Exemple de requête

JSON{
  "merchant_order_id": "order_2026_0001",
  "amount": 50000,
  "currency": "XOF",
  "customer_msisdn": "+22376123456",
  "country_code": "ML",
  "return_url": "https://shop.example.com/checkout/success",
  "notify_url": "https://api.example.com/webhooks/nekapay",
  "metadata": {"customer_id": "12345", "cart_id": "abc-def"}
}

Réponse 202 Accepted

JSON{
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_order_id": "order_2026_0001",
    "type": "CASHIN",
    "status": "PENDING",
    "amount": 50000,
    "currency": "XOF",
    "country_code": "ML",
    "msisdn": "+223*****56",
    "payment_url": "https://webpayment.orange.ci/pay/abc123",
    "provider_tx_id": "OM_2026042900012345",
    "created_at": "2026-04-29T14:30:00Z",
    "updated_at": "2026-04-29T14:30:01Z"
  }
}

POST /api/v1/payments/cashout

Reverse des fonds depuis le solde marchand vers un wallet client.

Body JSON

Champ	Type	Requis	Description
`merchant_order_id`	string	oui	Idempotency key.
`amount`	integer	oui	Montant en plus petite unité.
`beneficiary_msisdn`	string	oui	Numéro du bénéficiaire E.164.
`currency`	string	non	Auto-déduit.
`reason`	string	non	Motif (remboursement, payout, gain...).
`notify_url`	string	non	URL webhook.

JSON{
  "merchant_order_id": "payout_2026_001",
  "amount": 100000,
  "beneficiary_msisdn": "+22377777777",
  "currency": "XOF",
  "reason": "Gain de jeu - tirage du 28/04"
}

Validation à deux yeux : les montants ≥ cashout_approval_threshold (défaut 1 000 000 XOF) déclenchent un workflow d'approbation côté back-office.

GET /api/v1/payments/{id}

Consulte le statut courant d'une transaction.

Paramètre URL

{id} : UUID de la transaction.

Réponse 200 OK

JSON{
  "data": {
    "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
    "merchant_order_id": "order_2026_0001",
    "type": "CASHIN",
    "status": "SUCCESS",
    "amount": 50000,
    "currency": "XOF",
    "country_code": "ML",
    "provider_tx_id": "OM_2026042900012345",
    "completed_at": "2026-04-29T14:32:18Z"
  }
}

Statuts possibles

`CREATED`	Enregistrée mais pas encore envoyée à Orange.
`INITIATED`	Envoyée à Orange, en attente de réponse synchrone.
`PENDING`	Acceptée par Orange, en attente du client.
`SUCCESS`	Confirmée (état terminal).
`FAILED`	Échec définitif (état terminal).
`EXPIRED`	Délai client expiré (~5 min).
`REVERSED`	Remboursement effectué.

POST /api/v1/refunds

Déclenche un remboursement total ou partiel d'un Cash-In réussi.

JSON{
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 50000,
  "reason": "Annulation commande"
}

Si amount est omis, le montant total de la transaction est remboursé.

GET /api/v1/balances

Renvoie le solde du compte marchand par filiale.

JSON{
  "data": [
    {
      "country_code": "ML",
      "country_name": "Mali",
      "currency": "XOF",
      "available_balance": 8750000,
      "pending_balance": 125000,
      "updated_at": "2026-04-29T14:25:00Z"
    }
  ]
}

D'autres filiales apparaîtront ici dès leur activation par l'équipe Neka Paie.

GET /api/v1/transactions/export

Export des transactions pour réconciliation.

Paramètres query

`date_from`	Date début (ISO 8601). Requis.
`date_to`	Date fin. Requis.
`country_code`	Filtrer par pays.
`format`	`json` (défaut) ou `csv`.

BASHGET /api/v1/transactions/export?date_from=2026-04-01&date_to=2026-04-30&format=csv