Modèle de données d’un ordre de paiement

​

Structure

{
  "reference": "string",
  "total_amount": 150000,
  "currency": "XAF",
  "type": "DIRECT_DEBIT",
  "initiated_at": "2025-01-10",
  "debtor": { 
    "name" : "John Doe",
    "iban" : "CM21 XXXXX XXXXXXXXXXXXXXXXXXXXX XX"
  },
  "creditors": [
    {
      "name": "Fournisseur 1",
      "iban": "CM98XXXXXXXXXXXXXXXXXXXXXXX",
      "bank_code": "YYY",
      "reason": "Paiement facture #4587",
      "amount": 100000
    }
  ],
  "reason": "Paiement fournisseur",
  "metadata" : {
	"account": "xxxx",
 	"merchant": "yyyy",
	"mandate": "zzzz",
	"mandateRef": "zzzzz-2"
  }
}

​

2. Description champ par champ (niveau ordre)

​

2.1 Identité et caractéristiques de l’ordre

​

2.2 Règles associées

• reference :
  • UNIQUE côté Payment Engine
  • Utilisé comme clé d’idempotence métier
• total_amount :
  • DOIT être égal à la somme des montants des bénéficiaires
• currency :
  • DOIT être supportée par la Banque
• initiated_at :
  • Sert de repère temporel contractuel
  • Utilisé dans les mécanismes de polling

​

3. Type d’ordre (type)

Toute valeur non reconnue entraîne une erreur BUS_ORDER_REJECTED.

​

Débiteur (debtor)

​

4.1 Structure

{
  "name": "John Doe",
  "iban": "CM21XXXXXXXXXXXXXXXXXXXXXXX"
}

​

4.2 Description des champs

​

4.3 Règles métier

• L’IBAN :
  • DOIT être valide (ISO 13616)
  • DOIT appartenir à la Banque exécutante
• Le compte débiteur :
  • ne doit pas être bloqué
  • doit disposer des autorisations nécessaires

​

5. Bénéficiaires (creditors)

​

5.1 Structure

[
  {
    "name": "Fournisseur 1",
    "iban": "CM98XXXXXXXXXXXXXXXXXXXXXXX",
    "bank_code": "YYY",
    "reason": "Paiement facture #4587",
    "amount": 100000
  }
]

​

5.2 Description des champs

​

5.3 Règles métier (CRITIQUES)

• La liste creditors :
  • NE PEUT PAS être vide
• La somme des amount :
  • **DOIT être égale à **total_amount
• Chaque bénéficiaire :
  • est traité de manière atomique au sein de l’ordre
• Si aucun bénéficiaire ne peut être traité :
  • l’ordre est rejeté (BUS_ORDER_REJECTED)

​

6. Libellé global (reason)

• Utilisé pour :
  • affichage bancaire
  • rapprochement comptable
• Peut être redondant avec les libellés bénéficiaires

​

7. Métadonnées (metadata)

​

7.1 Structure

{
  "account": "xxxx", // id du compte
  "merchant": "yyyy", // id du marchant
  "mandate": "zzzz", // reference du mandate utilisé pour autorisé le paiement
  "mandateRef": "zzzzz-2" // reference du mandat interne à la banque si disponible
}

​

7.2 Règles

• Les métadonnées :
  • sont optionnelles
  • sont transmises telles quelles
  • NE DOIVENT PAS impacter le traitement bancaire
• En cas d’incompréhension :
  • la Banque DOIT ignorer le champ

​

8. Contraintes métier globales (RÉCAPITULATIF)

• reference unique
• total_amount = somme des bénéficiaires
• Devise supportée
• IBAN valides
• Liste des bénéficiaires non vide
• Ordre idempotent

​

9. Principe contractuel clé

La Banque exécute un ordre,elle n’en déduit jamais la sémantique métier.