5. Encaisser un client

Demande un paiement à un client : il reçoit une demande de confirmation sur son téléphone (code PIN Mobile Money). En-têtes : Authorization: Bearer sk_… et X-Application-ID: 1.

Encaisser un client

POST/transactionsClé API + X-Application-ID

Corps de la requête
{
  "type": "collection",
  "provider": "orange_money_cm",
  "amount": 5000,
  "currency": "XAF",
  "phone_number": "696246686",
  "idempotency_key": "commande-1234",
  "metadata": {
    "description": "Commande 1234",
    "customer_name": "Nom du client"
  }
}
Exemples d'appel (recette)
curl -X POST 'https://dev-aggregator-api.kratospay.com/api/v1/transactions' \
  -H 'Authorization: Bearer sk_test_VOTRE_CLE' \
  -H 'X-Application-ID: 1' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{"type":"collection","provider":"orange_money_cm","amount":5000,"currency":"XAF","phone_number":"696246686","idempotency_key":"commande-1234","metadata":{"description":"Commande 1234","customer_name":"Nom du client"}}'
Réponse 201
{
  "success": true,
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b3",
    "type": "collection",
    "provider": "orange_money",
    "status": "pending",
    "amount": "5000.00",
    "currency": "XAF",
    "reference": "MP240101.1234.A56789",
    "external_id": null,
    "phone_number": "696246686",
    "checkout_url": null,
    "metadata": {
      "description": "Commande 1234",
      "customer_name": "Nom du client"
    },
    "expires_at": null,
    "created_at": "2026-11-02T08:00:00Z",
    "updated_at": "2026-11-02T08:00:00Z"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Encaisser par carte bancaire

POST/transactionsClé API + X-Application-ID

Pour Mastercard comme pour Visa, utilisez provider: "mastercard". Les deux réseaux suivent ce même parcours : n'envoyez pas de numéro de téléphone ni de données de carte ; la réponse fournit checkout_url, à ouvrir pour que le client paie sur la page sécurisée. return_url est facultatif.

Corps de la requête
{
  "type": "collection",
  "provider": "mastercard",
  "amount": 25000,
  "currency": "XAF",
  "idempotency_key": "commande-5678",
  "return_url": "https://monsite.com/merci",
  "metadata": {
    "description": "Commande 5678"
  }
}
Réponse 201
{
  "success": true,
  "data": {
    "uuid": "018f1a2b-3c4d-7e5f-a6b7-c8d9e0f1a2b4",
    "type": "collection",
    "provider": "mastercard",
    "status": "pending",
    "amount": "25000.00",
    "currency": "XAF",
    "reference": "K7H2M9QXP4R8T1W5Z3NB",
    "phone_number": null,
    "checkout_url": "https://master.kratos-travel.com/?sessionId=SESSION0002..."
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}
CodeQuand
422Montant ou devise invalide, paiement par carte non activé sur le compte, ou passerelle momentanément indisponible.
  • Après paiement, le client revient sur return_url. Ne validez jamais la commande sur cette seule redirection : attendez transaction.success ou vérifiez par GET /transactions/{uuid}. Les statuts possibles sont pending, success, failed et expired.
  • La carte ne prend pas en charge les décaissements ni les remboursements par API pour le moment.

Réponses possibles en cas d'échec

CodeQuand
401Clé API invalide, inactive, expirée, ou clé d'un autre environnement.
422Montant invalide, réseau indisponible ou désactivé, numéro qui ne correspond pas au pays du réseau, idempotency_key déjà utilisée par une autre opération, ou paiement non initié (réessayer dans quelques instants).
  • Champs obligatoires : type, provider, amount, et phone_number pour une collecte. Autres types : disbursement (envoi), airtime, tv, internet.
  • Le statut initial est pending : ce n'est pas un échec. Attendez le webhook ou consultez la transaction.
  • Orange Money : renseignez metadata.customer_name si vous prévoyez des remboursements.
  • En test (sk_test_), aucun argent ne bouge et le dénouement est simulé.