Transactions - Remita API

Authentification requise : tous ces endpoints nécessitent les headers apiKey, apiId et Authorization: Bearer <token>.

Opérateurs disponibles

Code	Opérateur	Pays	Indicatif
`OMCM`	Orange Money	Cameroun	+237
`MOMOCM`	MTN Mobile Money	Cameroun	+237
`CIWAVE`	Wave	Côte d’Ivoire	+225
`CIOM`	Orange Money	Côte d’Ivoire	+225
`SNWAVE`	Wave	Sénégal	+221
`SNOM`	Orange Money	Sénégal	+221
`SNFREE`	Free	Sénégal	+221
`BFOM`	Orange Money	Burkina Faso	+226
`MLMOOV`	Moov	Mali	+223
`BJMTN`	MTN	Bénin	+229
`BJMOOV`	Moov	Bénin	+229
`UGMTN`	MTN	Ouganda	+256
`UGAIRTEL`	Airtel	Ouganda	+256

Corps de requête commun

Les endpoints collect et deposit utilisent le même corps :

{
  "transferMethod": "OMCM",
  "customerName": "Jean Dupont",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "phoneNumber": "237690000000",
  "amount": 5000,
  "webhookUrl": "https://votre-serveur.com/callback",
  "countryName": "CAMEROON"
}

Champ	Type	Obligatoire	Description
`transferMethod`	String	Oui	Code opérateur (ex : `OMCM`, `MOMOCM`)
`customerName`	String	Oui	Nom complet du client
`externalId`	UUID	Oui	Identifiant unique côté votre système (UUID v4)
`phoneNumber`	String	Oui	Numéro en format international sans `+` (ex : `237690000000`)
`amount`	BigDecimal	Oui	Montant dans la devise locale (XAF, XOF, UGX…)
`webhookUrl`	String	Oui	URL de callback pour recevoir le résultat asynchrone
`countryName`	String	Oui	`CAMEROON`, `IVORY_COAST`, `SENEGAL`, `BURKINA_FASO`, `MALI`, `BENIN`, `UGANDA`

transferMethod et countryName doivent être cohérents. Ex : OMCM + CAMEROON. Toute combinaison invalide retourne 400 Bad Request.

POST /api/v1/transaction/collect

Initie une collecte — débite le compte mobile money du client vers votre compte.

curl -X POST https://api.remita.cm/api/v1/transaction/collect \
  -H "Content-Type: application/json" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "transferMethod": "OMCM",
    "customerName": "Jean Dupont",
    "externalId": "550e8400-e29b-41d4-a716-446655440000",
    "phoneNumber": "237690000000",
    "amount": 5000,
    "webhookUrl": "https://votre-serveur.com/callback",
    "countryName": "CAMEROON"
  }'

Réponse (200)

{
  "transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "transferMethod": "OMCM",
  "customerName": "Jean Dupont",
  "customerPhone": "237690000000",
  "payToken": "abc123xyz",
  "amount": 5000,
  "feesSystem": 50,
  "feesApp": 25,
  "transactionStatus": "PENDING"
}

POST /api/v1/transaction/deposit

Initie un dépôt — envoie de l’argent depuis votre compte vers le mobile money d’un bénéficiaire. Même corps de requête que /collect. Seul le sens du transfert change.

curl -X POST https://api.remita.cm/api/v1/transaction/deposit \
  -H "Content-Type: application/json" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "transferMethod": "MOMOCM",
    "customerName": "Marie Martin",
    "externalId": "660e9500-f30c-52e5-b827-557766551111",
    "phoneNumber": "237670000000",
    "amount": 10000,
    "webhookUrl": "https://votre-serveur.com/callback",
    "countryName": "CAMEROON"
  }'

Réponse identique à /collect avec transactionStatus: "PENDING".

POST /api/v1/transaction/depositMultiple

Initie plusieurs dépôts en une seule requête (batch).

Corps de la requête

[
  {
    "transferMethod": "MOMOCM",
    "customerName": "Alice",
    "externalId": "uuid-1",
    "phoneNumber": "237670000001",
    "amount": 5000,
    "webhookUrl": "https://votre-serveur.com/callback",
    "countryName": "CAMEROON"
  },
  {
    "transferMethod": "OMCM",
    "customerName": "Bob",
    "externalId": "uuid-2",
    "phoneNumber": "237690000002",
    "amount": 3000,
    "webhookUrl": "https://votre-serveur.com/callback",
    "countryName": "CAMEROON"
  }
]

curl -X POST https://api.remita.cm/api/v1/transaction/depositMultiple \
  -H "Content-Type: application/json" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '[{...}, {...}]'

POST /api/v1/transaction/transaction-status

Vérifie le statut d’une transaction par son transactionId.

Paramètres query

Paramètre	Type	Obligatoire	Description
`id`	UUID	Oui	`transactionId` retourné par collect / deposit

curl -X POST "https://api.remita.cm/api/v1/transaction/transaction-status?id=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Réponse (200)

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "externalId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 5000,
  "feesSystem": 50,
  "feesApp": 25,
  "phoneReceiver": "237690000000",
  "receiverName": "Jean Dupont",
  "status": "SUCCESS",
  "transferMethod": "OMCM",
  "transactionType": "COLLECT",
  "countryName": "CAMEROON",
  "payToken": "abc123xyz"
}

Statuts possibles

Statut	Description
`PENDING`	Transaction initiée, en attente opérateur
`PENDING_APPROVAL`	En attente d’approbation interne
`SUCCESS`	Transaction réussie
`FAILED`	Transaction échouée

POST /api/v1/transaction/chekTransactionStatus

Vérifie et synchronise le statut d’une transaction en interrogeant directement l’opérateur. Utile si le webhook n’a pas été reçu et que transaction-status retourne encore PENDING.

Paramètres query

Paramètre	Type	Obligatoire	Description
`transactionId`	UUID	Oui	Identifiant de la transaction

curl -X POST "https://api.remita.cm/api/v1/transaction/chekTransactionStatus?transactionId=3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/v1/transaction/validateTransaction

Valide et approuve une transaction en attente (PENDING_APPROVAL).

Paramètres query

Paramètre	Type	Obligatoire	Description
`checkerId`	UUID	Oui	Identifiant du validateur
`transactionId`	UUID	Oui	Identifiant de la transaction
`payeeNote`	String	Oui	Note de validation

curl -X POST "https://api.remita.cm/api/v1/transaction/validateTransaction?checkerId=<uuid>&transactionId=<uuid>&payeeNote=Approuv%C3%A9" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

POST /api/v1/transaction/rejectTransaction

Rejette une transaction en attente.

Paramètres query

Paramètre	Type	Obligatoire	Description
`checkerId`	UUID	Oui	Identifiant du validateur
`transactionId`	UUID	Oui	Identifiant de la transaction
`reason`	String	Oui	Motif du rejet

curl -X POST "https://api.remita.cm/api/v1/transaction/rejectTransaction?checkerId=<uuid>&transactionId=<uuid>&reason=Fraude+suspect%C3%A9e" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/v1/transaction/getByApplicationProduct

Liste toutes les transactions de votre application avec pagination.

Paramètres query

Paramètre	Type	Obligatoire	Description
`page`	Integer	Oui	Numéro de page (0-indexé)
`size`	Integer	Oui	Nombre d’éléments par page

curl -X GET "https://api.remita.cm/api/v1/transaction/getByApplicationProduct?page=0&size=20" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Réponse (200)

{
  "content": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "externalId": "550e8400-e29b-41d4-a716-446655440000",
      "amount": 5000,
      "feesSystem": 50,
      "feesApp": 25,
      "phoneReceiver": "237690000000",
      "receiverName": "Jean Dupont",
      "status": "SUCCESS",
      "transferMethod": "OMCM",
      "transactionType": "COLLECT",
      "countryName": "CAMEROON"
    }
  ],
  "totalElements": 150,
  "totalPages": 8,
  "size": 20,
  "number": 0
}

GET /api/v1/transaction/getByApplicationProductAndPhoneReceiver

Filtre les transactions par numéro de téléphone du bénéficiaire.

Paramètre	Type	Obligatoire	Description
`phoneNumber`	String	Oui	Numéro en format international
`page`	Integer	Oui	Numéro de page (0-indexé)
`size`	Integer	Oui	Nombre d’éléments par page

GET /api/v1/transaction/getByApplicationProductAndStatus

Filtre les transactions par statut.

Paramètre	Type	Obligatoire	Description
`transactionStatus`	String	Oui	`PENDING`, `PENDING_APPROVAL`, `SUCCESS`, `FAILED`
`page`	Integer	Oui	Numéro de page
`size`	Integer	Oui	Taille de la page

GET /api/v1/transaction/getTotalAmountByApplicationProductAndDateRange

Calcule le montant total des transactions sur une plage de dates.

Paramètre	Type	Obligatoire	Description
`startDate`	String	Oui	Date début ISO 8601 (ex : `2026-01-01`)
`endDate`	String	Oui	Date fin ISO 8601 (ex : `2026-03-31`)
`status`	String	Oui	Statut à filtrer

Réponse

75000.00

GET /api/v1/transaction/getTotalAmountByApplicationProduct

Retourne le montant total de toutes les transactions de votre application.

curl -X GET "https://api.remita.cm/api/v1/transaction/getTotalAmountByApplicationProduct" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

GET /api/v1/transaction/getByApplicationProductBalances

Retourne les soldes disponibles de votre application par opérateur et type (collect / deposit).

curl -X GET "https://api.remita.cm/api/v1/transaction/getByApplicationProductBalances" \
  -H "apiKey: YOUR_API_KEY" \
  -H "apiId: YOUR_API_ID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Réponse (200)

[
  {
    "serviceType": "OMCM",
    "balanceCollect": 250000.00,
    "balanceDeposit": 120000.00
  },
  {
    "serviceType": "MOMOCM",
    "balanceCollect": 180000.00,
    "balanceDeposit": 95000.00
  }
]

Flux recommandé

1. POST /collect  ou  /deposit
         ↓
2. Recevoir transactionId + statut initial (PENDING)
         ↓
3. Attendre le callback webhook (asynchrone)
       OU
   POST /transaction-status  (polling)
       OU
   POST /chekTransactionStatus  (force sync opérateur)
         ↓
4. Traiter le statut final (SUCCESS / FAILED)

Utilisez toujours un externalId unique (UUID v4) par transaction. En cas de retry sur timeout réseau, réutilisez le même externalId — Remita détectera le doublon et retournera la transaction existante.

import uuid

def idempotent_external_id(order_id: str) -> str:
    """UUID déterministe à partir de votre ID de commande."""
    return str(uuid.uuid5(uuid.NAMESPACE_DNS, f"order:{order_id}"))

​Opérateurs disponibles

​Corps de requête commun

​POST /api/v1/transaction/collect

​Réponse (200)

​POST /api/v1/transaction/deposit

​POST /api/v1/transaction/depositMultiple

​Corps de la requête

​POST /api/v1/transaction/transaction-status

​Paramètres query

​Réponse (200)

​Statuts possibles

​POST /api/v1/transaction/chekTransactionStatus

​Paramètres query

​POST /api/v1/transaction/validateTransaction

​Paramètres query

​POST /api/v1/transaction/rejectTransaction

​Paramètres query

​GET /api/v1/transaction/getByApplicationProduct

​Paramètres query

​Réponse (200)

​GET /api/v1/transaction/getByApplicationProductAndPhoneReceiver

​GET /api/v1/transaction/getByApplicationProductAndStatus

​GET /api/v1/transaction/getTotalAmountByApplicationProductAndDateRange

​Réponse

​GET /api/v1/transaction/getTotalAmountByApplicationProduct

​GET /api/v1/transaction/getByApplicationProductBalances

​Réponse (200)

​Flux recommandé

Opérateurs disponibles

Corps de requête commun

POST /api/v1/transaction/collect

Réponse (200)

POST /api/v1/transaction/deposit

POST /api/v1/transaction/depositMultiple

Corps de la requête

POST /api/v1/transaction/transaction-status

Paramètres query

Réponse (200)

Statuts possibles

POST /api/v1/transaction/chekTransactionStatus

Paramètres query

POST /api/v1/transaction/validateTransaction

Paramètres query

POST /api/v1/transaction/rejectTransaction

Paramètres query

GET /api/v1/transaction/getByApplicationProduct

Paramètres query

Réponse (200)

GET /api/v1/transaction/getByApplicationProductAndPhoneReceiver

GET /api/v1/transaction/getByApplicationProductAndStatus

GET /api/v1/transaction/getTotalAmountByApplicationProductAndDateRange

Réponse

GET /api/v1/transaction/getTotalAmountByApplicationProduct

GET /api/v1/transaction/getByApplicationProductBalances

Réponse (200)

Flux recommandé