> ## 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 Polling Inverse

> (Connecteur → Banque) Le Polling Inverse est un mécanisme optionnel et dégradé par lequel le Connecteur interroge périodiquement la Banque afin d’obtenir le statut le plus récent d’un ordre de paiement.

<Note>
  Ce mode est **utilisé exclusivement** lorsque la Banque est **techniquement incapable d’émettre des appels sortants** (Callback Push).
</Note>

## A. Principe général

* Le Connecteur **initie les requêtes**
* La Banque reste **source de vérité** du statut
* Le Polling Inverse :
  * **NE REMPLACE PAS** le Callback Push
  * **N’EST UTILISÉ QUE** comme mécanisme de secours
* Le Polling Inverse s’applique \*\*uniquement aux ordres en statut \*\*`PENDING ou push async`

## B. Endpoint de requête de statut (côté Banque)

### Endpoint

```bash theme={null}
curl -X GET /payment-orders/{orderId}/status
```

### Authentification et sécurité

La requête **DOIT** être protégée par :

* **mTLS obligatoire**
* **Authentification applicative obligatoire** :
  * OAuth 2.0 (Bearer ou DPoP)
  * ou API Key selon le contrat

### En-têtes requis

| En-tête         | Obligatoire | Description                             |
| :-------------- | :---------- | :-------------------------------------- |
| `X-Timestamp`   | Oui         | Horodatage ISO-8601 UTC                 |
| `X-Nonce`       | Oui         | Protection anti-replay                  |
| `X-Signature`   | Oui         | Signature cryptographique du Connecteur |
| `Authorization` | Oui         | Bearer / DPoP / X-API-Key               |
| `X-Client-Id`   | Oui         | Identifiant du Connecteur               |

### Paramètre de chemin

| Paramètre | Type   | Description                          |
| :-------- | :----- | :----------------------------------- |
| `orderId` | String | Identifiant métier unique de l’ordre |

### Exemple

```bash theme={null}
curl -X GET /payment-orders/PAY-2025-0001/status
```

## C. Comportement attendu du Connecteur (client)

### Fréquence de polling

Le Connecteur **DOIT implémenter une stratégie de polling adaptative** :

* fréquence initiale courte (ex : 30s – 1min)
* intervalle progressif (backoff exponentiel)
* plafond maximal configurable (ex : 10–15 minutes)

### Règles de sécurité

* Chaque requête **DOIT** être signée via `X-Signature`
* La signature **DOIT** couvrir :
  * la méthode HTTP
  * l’URI
  * les paramètres
  * les en-têtes critiques

### Condition d’arrêt (CRITIQUE)

> **Le polling inverse s’arrête uniquement lorsque la Banque retourne un statut final.**

Statuts finaux :

* `SUCCESS`
* `FAILED`

## D. Format JSON de la réponse (côté Banque)

La Banque retourne **une enveloppe JSON standard** contenant **un seul objet de mise à jour de statut**.

### Réponse – 200 OK

```json theme={null}
{
  "reference": "PAY-2025-0001",
  "bank_reference": "BNK-778899",
  "status": "PENDING | SUCCESS | FAILED",
  "reasonCode": "BUS_INSUFFICIENT_FUNDS",
  "reasonMessage": "Insufficient balance on debtor account.",
  "processed_at": "2025-11-19T07:30:00Z"
}
```

### Règles associées

* `reference` DOIT correspondre à l’ordre interrogé
* `reasonCode` et `reasonMessage` sont :
  * \*\*OBLIGATOIRES si \*\*`status = FAILED`
* `processed_at` est la date de traitement bancaire

## E. Codes HTTP et comportements

| Code HTTP                 | Signification     | Action du Connecteur        |
| :------------------------ | :---------------- | :-------------------------- |
| **200 OK**                | Statut disponible | Mettre à jour l’état local  |
| **404 Not Found**         | Ordre inconnu     | Arrêter le polling + alerte |
| **429 Too Many Requests** | Limite atteinte   | Appliquer backoff           |
| **4xx / 5xx**             | Erreur technique  | Retry selon stratégie       |

## F. Exemple de requête – Polling inverse (Mintlify)

### cURL

```bash theme={null}
curl -X GET "https://bank.example.com/payment-orders/PAY-2025-0001/status" \
  -H "Authorization: Bearer <access_token>" \
  -H "X-Client-Id: CONNECTOR_X" \
  -H "X-Timestamp: 2025-11-19T07:30:00Z" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Signature: <signature>"
```