> ## 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.

# Callback Push

> Le Callback Push permet à la Banque de notifier le Connecteur de l’évolution du statut métier d’un ou plusieurs ordres de paiement.

<Warning>
  **Ce mécanisme est OBLIGATOIRE lorsque le mode Polling est utilisé**, car le Connecteur ne peut pas déterminer seul l’issue du traitement bancaire.
</Warning>

## A. Principes généraux

* La Banque est **source de vérité** du statut final
* Le Callback Push est :
  * **synchrone au niveau HTTP**
  * **asynchrone au niveau métier**
* Deux modes sont supportés :
  * **Unitaire** (un ordre)
  * **Batch** (plusieurs ordres)

## B. Endpoints de réception (côté Connecteur)

### 1. Callback unitaire (ordre unique)

```bash theme={null}
curl -X POST /callbacks/orders/status
```

#### Cas d’usage

* Traitement en temps réel
* Ordres critiques
* Implémentation simple
* Faible volumétrie

### 2. Callback batch (plusieurs ordres)

#### Endpoint

```bash theme={null}
curl -X POST /callbacks/orders/status/batch
```

#### Cas d’usage

* Traitement par lot (batch bancaire)
* Forte volumétrie
* Fenêtres de compensation
* Optimisation réseau

## C. Sécurité et authentification (COMMUNS AUX DEUX ENDPOINTS)

Les deux endpoints **PARTAGENT EXACTEMENT les mêmes exigences de sécurité**.

### Exigences obligatoires

* **mTLS obligatoire**
* **Signature JWS de la Banque obligatoire**
* Protection anti-replay
* Idempotence stricte

En-têtes requis

| En-tête             | Obligatoire | Description                              |
| :------------------ | :---------- | :--------------------------------------- |
| `X-Client-Id`       | Oui         | Identifiant unique de la Banque          |
| `X-Timestamp`       | Oui         | Horodatage ISO-8601 UTC                  |
| `X-Nonce`           | Oui         | Valeur unique anti-replay                |
| `X-Idempotency-Key` | Oui         | Identifiant unique du batch              |
| `X-Signature`       | Oui         | Signature JWS couvrant headers + payload |
| `Content-Type`      | Oui         | `application/json`                       |

## D. Callback unitaire – Format JSON

### Corps de la requête

```json theme={null}
{
  "reference": "string",
  "bank_reference": "string",
  "status": "PENDING | SUCCESS | FAILED",
  "reasonCode": "BUS_INSUFFICIENT_FUNDS",
  "reasonMessage": "Insufficient balance on debtor account.",
  "processed_at": "ISO8601-timestamp"
}
```

### Règles spécifiques (unitaire)

* `X-Idempotency-Key` est **lié à l’ordre**
* Un ordre **NE PEUT PAS** changer de statut final
* `FAILED` ⇒ `reasonCode` + `reasonMessage` obligatoires

### Règles spécifiques (batch)

* Le batch est **traité de manière atomique**
* **Aucune acceptation partielle**
* La signature JWS couvre :
  * tous les headers
  * le `X-Idempotency-Key` du batch
  * le hash du payload complet

## F. Idempotence (CRITIQUE)

| Niveau         | Mécanisme                    |
| :------------- | :--------------------------- |
| Ordre          | `reference` / `orderId`      |
| Appel unitaire | `X-Idempotency-Key`          |
| Batch          | `X-Idempotency-Key` du batch |

> Le Connecteur **NE DOIT JAMAIS** appliquer deux fois un même statut final.

## H. Réponse du Connecteur (accusé de réception)

### Codes HTTP

| Code HTTP     | Signification         |
| :------------ | :-------------------- |
| **200 OK**    | Notification acceptée |
| **4xx / 5xx** | Rejet total           |

### Règle clé

> Le Connecteur **NE PEUT PAS accepter partiellement** un batch ou une notification.

## Exemple – Callback unitaire (cURL)

```bash theme={null}
curl -X POST "https://connector.example.com/callbacks/payment-status" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: BANK_X" \
  -H "X-Timestamp: 2025-11-19T07:10:00Z" \
  -H "X-Nonce: 8f14e45f" \
  -H "X-Idempotency-Key: PAY-2025-0001" \
  -H "X-Signature: <jws-signature>" \
  --data '{
    "reference": "PAY-2025-0001",
    "bank_reference": "BNK-778899",
    "status": "SUCCESS",
    "timestamp": "2025-11-19T07:09:30Z"
  }'
```

## Exemple – Callback batch (cURL)

```bash theme={null}
curl -X POST "https://connector.example.com/callbacks/batch-status" \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: BANK_X" \
  -H "X-Timestamp: 2025-11-19T07:15:00Z" \
  -H "X-Nonce: 9a1f3c" \
  -H "X-Idempotency-Key: batch-20251119-001" \
  -H "X-Signature: <jws-signature>" \
  --data '{
    "batch_id": "batch-20251119-001",
    "sent_at": "2025-11-19T07:15:00Z",
    "orders": [
      {
        "reference": "PAY-2025-0002",
        "bank_reference": "BNK-990011",
        "status": "FAILED",
        "reasonCode": "BUS_INSUFFICIENT_FUNDS",
        "reasonMessage": "Insufficient balance",
        "timestamp": "2025-11-19T07:14:30Z"
      }
    ]
  }'
```

***

##