Callback Push

​

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)

​

Exigences obligatoires

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

​

D. Callback unitaire – Format 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)

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

​

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

​

Codes HTTP

​

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"
      }
    ]
  }'

​