Skip to main content

​
Création d’un ordre de paiement

Le Connecteur transmet les ordres de paiement via une requête HTTP POST sécurisée.
Les informations de sécurité sont portées exclusivement par les en-têtes HTTP et font référence au corps JSON signé.
En-têteDescription
X-Client-IdIdentifiant technique du connecteur
X-Request-IdIdentifiant technique de la requete
X-TimestampHorodatage ISO 8601 UTC
X-NonceIdentifiant unique anti-rejeu
X-Idempotency-KeyClé d’idempotence métier
X-SignatureSignature cryptographique du corps
AuthorizationOAuth2 (Bearer / DPoP )
Content-Typeapplication/json
curl -X POST https://api.bank.example.com/payment-orders \
  -H "Content-Type: application/json" \
  -H "X-Client-Id: CONNECTOR_X" \
  -H "X-Timestamp: 2025-11-19T07:05:00Z" \
  -H "X-Nonce: 550e8400-e29b-41d4-a716-446655440000" \
  -H "X-Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6" \
  -H "X-Signature: eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXUyJ9..." \
  -H "Authorization: Bearer <access_token>" \
  -d @payload.json

​
Réponse attendue du service bancaire

Le service bancaire DOIT retourner une réponse HTTP conforme aux règles décrites ci-dessous.
Le code HTTP détermine explicitement la présence ou non d’un corps de réponse.
HTTP StatusSignificationCorps de réponse
200 OK (sync)Traitement en cours ou terminéOBLIGATOIRE
202 Accepted (async)Traitement accepté, résultat différéABSENT
4xx / 5xxErreurObjet d’erreur standard
Toute déviation à ces règles entraîne un rejet de l’intégration.

​
Cas 1 — HTTP 202 Accepted (traitement asynchrone)

​
Description

Le code 202 Accepted indique que :
  • l’ordre a été accepté techniquement,
  • le traitement bancaire est différé,
  • aucun statut métier final n’est encore disponible.

​
Règle obligatoire

  • Aucun corps de réponse ne doit être retourné
  • Le header Content-Length doit être égal à 0
  • Le statut final DEVRA être transmis ultérieurement via callback

​
Cas 2 — HTTP 200 OK (traitement synchrone)

​
Description

Le code 200 OK indique que :
  • l’ordre a été traité immédiatement,
  • un statut métier est disponible,
  • le résultat est définitif.

​
Règle obligatoire

  • Le corps de réponse est OBLIGATOIRE
  • Le corps DOIT respecter le format standard décrit ci-dessous

​
Format du corps de réponse (HTTP 200)

{
  "status": "PENDING | SUCCESS | FAILED",
  "reference": "string",
  "bank_reference": "string",
  "timestamp": "2025-11-19T07:06:30Z",
  "reason_code": "xxxx",
  "reason_message" : "yyyy"
}
ChampTypeObligatoireDescription
statusStringOuiStatut métier du paiement
referenceStringOuiRéférence initiale de l’ordre
bank_referenceStringOuiRéférence bancaire interne
reason_codeStringConditionnelObligatoire si status = FAILED
reason_messageStringConditionnelMessage lisible expliquant l’échec
timestampISO 8601 UTCOuiDate de traitement bancaire
Règles sur le champ status
ValeurSignification
PENDINGTraitement initié, finalisation différée
SUCCESSPaiement exécuté avec succès
FAILEDPaiement rejeté ou échoué

​
Contraintes

  • SUCCESS et FAILED sont des statuts finaux
  • PENDING implique obligatoirement un callback ultérieur
  • Un statut final ne peut jamais être modifié

​
Cas particulier — FAILED

Lorsque status = FAILED :
  • reasonCode est OBLIGATOIRE
  • reasonMessage est OBLIGATOIRE
  • Le code doit appartenir à la nomenclature des erreurs métier documentées
Example 
{
  "status": "FAILED",
  "reference": "PAY-2025-0001",
  "bank_reference": "BNK-778899",
  "reason_code": "BUS_INSUFFICIENT_FUNDS",
  "reason_message": "Insufficient balance on debtor account.",
  "timestamp": "2025-11-19T07:06:30Z"
}

​
Règles de cohérence (IMPORTANT)

  • Un HTTP 200 sans body est invalide
  • Un HTTP 202 avec body est invalide
  • Le reference DOIT correspondre exactement à la référence reçue
  • Le bank_reference est obligatoire pour toute traçabilité bancaire
  • Le timestamp DOIT être exprimé en UTC

​
Cas 3 — HTTP 4xx/5xx

Gestion d’erreur standard