Pour les ingénieurs et intégrateurs

API unifiée TrustPayWay

Une API unique et sécurisée pour interagir avec plusieurs réseaux de paiement mobile (Orange, MTN, etc.) : génération de jetons, initiation de paiements et suivi des transactions en temps réel.

API REST JSON

OAuth-like Bearer token

PCI-DSS • GIMAC

Démarrage rapide

L’API TrustPayWay vous permet d’initier et de suivre des paiements mobile money via une interface unifiée. Le flux standard se déroule en trois étapes :

Obtenir un TPW Token (valable 2 heures).
Appeler Process Payment pour initier le paiement.
Consulter Check Payment Status pour suivre l’état de la transaction.

Variables d’environnement

base_url – URL de base de l’API
network – Réseau de paiement (mtn, orange)
secret_key – Clé secrète fournie lors de l’enregistrement
bearer_token – Jeton retourné par /api/login
auth_token – Jeton spécifique au réseau si nécessaire

POST /api/login

Obtenir le jeton TPW

Cette méthode renvoie un access_token (type Bearer) valable pendant deux heures. Ce jeton doit être utilisé dans l’en-tête Authorization pour tous les appels protégés.

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {secret_key}"
}

Corps de requête

{
  "applicationId": "38e1a762-cceb-4d71-9340-c76ad040b42a"
}

Réponse en cas de succès

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer"
}

Exemple d’erreur

{
  "error": "invalid_credentials",
  "message": "Invalid secret key provided"
}

POST /api/{network}/process-payment

Initier un paiement

Cette ressource permet d’initier un paiement mobile money sur le réseau choisi (par exemple mtn ou orange). Utilisez le bearer_token obtenu via /api/login.

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {bearer_token}"
}

Corps de requête

{
  "amount": "1",                 // Montant à payer
  "currency": "XAF",             // Code de devise
  "subscriberMsisdn": "237600000000", // Numéro de téléphone du payeur
  "description": "payment",      // Description facultative
  "orderId": "TPW12345",         // Identifiant unique de la transaction
  "verificationToken": "unique-token-123", // Jeton facultatif pour éviter les doublons
  "notifUrl": "https://yourapp.com/tpw/callback" // URL de notification (webhook)
}

Réponse en cas de succès

{
  "data": {
    "transaction_id": "74d96622-b36c-4993-964d-345decfcbb8d"
  },
  "message": "Payment request successful",
  "status_code": 202
}

Exemple d’erreur

{
  "error": "invalid_request",
  "message": "Invalid phone number format",
  "status_code": 400
}

Prévention des doublons : si verificationToken est fourni, une même combinaison merchant ID + orderId + verificationToken est rejetée comme doublon (hors transactions échouées ou annulées).

GET /api/{network}/get-status/{transaction_id}

Consulter le statut de paiement

Utilisez ce point de terminaison pour suivre l’évolution d’une transaction (statuts typiques : INITIATED, PENDING, FAILED, SUCCESSFUL).

Headers

{
  "Content-Type": "application/json",
  "Authorization": "Bearer {bearer_token}"
}

Réponse en cas de succès

{
  "amount": "1",
  "confirmationStatus": "payment started",
  "description": "COULD_NOT_PERFORM_TRANSACTION",
  "orderId": "TPWid017",
  "payerPhone": "237673444815",
  "status": "FAILED",
  "transactionId": "11972264171"
}

Exemple d’erreur

{
  "error": "not_found",
  "message": "Transaction not found",
  "status_code": 404
}