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": "..."
}
}| Code | Quand |
|---|---|
| 422 | Montant 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 : attendeztransaction.successou vérifiez parGET /transactions/{uuid}. Les statuts possibles sontpending,success,failedetexpired. - 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
| Code | Quand |
|---|---|
| 401 | Clé API invalide, inactive, expirée, ou clé d'un autre environnement. |
| 422 | Montant 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, etphone_numberpour 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_namesi vous prévoyez des remboursements. - En test (
sk_test_), aucun argent ne bouge et le dénouement est simulé.