> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corelink.dhi-cm.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

> Le payload PaymentOrder représente un ordre de paiement émis par le Payment Engine et transmis à la Banque pour exécution.

Il constitue **l’unité métier fondamentale** de l’intégration.

## Structure

```json theme={null}
{
  "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

| Champ          | Type              | Obligatoire | Description                                              |
| :------------- | :---------------- | :---------- | :------------------------------------------------------- |
| `reference`    | String            | Oui         | Identifiant métier unique de l’ordre côté Payment Engine |
| `total_amount` | Number            | Oui         | Montant total à débiter, en unité monétaire minimale     |
| `currency`     | String (ISO 4217) | Oui         | Devise de l’ordre (ex : `XAF`)                           |
| `type`         | Enum              | Oui         | Type d’opération bancaire                                |
| `initiated_at` | ISO-8601 UTC      | Oui         | Date et heure d’initiation 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`)

| Valeur         | Description                        |
| :------------- | :--------------------------------- |
| `DIRECT_DEBIT` | Prélèvement sur le compte débiteur |

> Toute valeur non reconnue entraîne une erreur `BUS_ORDER_REJECTED`.

## Débiteur (`debtor`)

Informations relatives au **compte débité**.

### 4.1 Structure

```json theme={null}
{
  "name": "John Doe",
  "iban": "CM21XXXXXXXXXXXXXXXXXXXXXXX"
}
```

### 4.2 Description des champs

| Champ  | Type   | Obligatoire | Description                         |
| :----- | :----- | :---------- | :---------------------------------- |
| `name` | String | Oui         | Nom du titulaire du compte débiteur |
| `iban` | String | Oui         | IBAN du compte débité               |

### 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`)

Liste des bénéficiaires du paiement.

### 5.1 Structure

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

### 5.2 Description des champs

| Champ       | Type   | Obligatoire | Description                        |
| :---------- | :----- | :---------- | :--------------------------------- |
| `name`      | String | Oui         | Nom du bénéficiaire                |
| `iban`      | String | Oui         | IBAN du bénéficiaire               |
| `bank_code` | String | Oui         | Code banque ou établissement       |
| `reason`    | String | Non         | Libellé spécifique au bénéficiaire |
| `amount`    | Number | Oui         | Montant attribué à ce bénéficiaire |

### 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`)

| Champ    | Type   | Obligatoire | Description                |
| :------- | :----- | :---------- | :------------------------- |
| `reason` | String | Non         | Libellé global du paiement |

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

## 7. Métadonnées (`metadata`)

Données **contextuel**, informant la banque sur le marchant, le mandat utilisé,

### 7.1 Structure

```json theme={null}
{
  "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.**