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.
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.
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)
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
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 |
Corps de la requête
{
"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)
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)
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"
}
]
}'
