Un contrat examinable par une équipe technique.
Construisez un parcours d’intention de paiement observable : créez la demande, consultez son état et comprenez reprises et erreurs.
Créer une intention de paiement
Le contrat POST sélectionné exige Content-Type application/json, une session vérifiée, l’autorité payment.create et une Idempotency-Key valide. La clé est limitée à l’organisation et à une opération incluant l’identité de l’appelant. La création retourne 201 et IntentView ; elle ne collecte pas de fonds.
{
"amount": { "amountMinor": "250000", "assetId": "synthetic_asset_placeholder" },
"orderReference": "evaluation-order-0001",
"description": "Synthetic evaluation order",
"expiresInMinutes": 30
}
// Shape example only. Placeholder IDs are not valid for execution.| Champ | Type / exigence | Sens |
|---|---|---|
| amount.amountMinor | Chaîne requise ; entier positif canonique. | Ni décimale, exposant, signe, zéro initial ou espace ; pas un flottant. |
| amount.assetId | Chaîne requise ; actif existant compatible avec l’environnement. | Les espèces physiques sont exclues des intentions de paiement. |
| orderReference | Chaîne non vide requise ; maximum 120 caractères avant suppression des espaces. | Référence marchande ; espaces périphériques supprimés. |
| description | Chaîne facultative ; maximum 500 caractères. | Une omission devient null dans la réponse. |
| expiresInMinutes | Entier facultatif 1–10080 ; omission ou null donne 30. | Expiration de l’intention, pas délai d’exécution fournisseur. |
Lire une liste ou un document
La liste utilise status, q, limit, from et to. Limite par défaut 50 ; maximum 200 sans période et 1000 avec période. Une période exige deux dates YYYY-MM-DD valides avec from ≤ to. q accepte au plus 120 caractères. Les créations récentes apparaissent d’abord. Aucun curseur ni export exhaustif n’est garanti par ce contrat.
Les dates sont des journées inclusives en America/Port-au-Prince. Le prédicat actuel inclut les documents créés avant la limite du dernier jour si création ou confirmation atteint la limite du premier jour. La confirmation n’a pas de borne supérieure distincte : un document antérieur confirmé après la fin demandée peut apparaître. Elle ne remplace pas le rapprochement, qui regroupe par jour de confirmation et preuves de relevé.
| Champs IntentView | Représentation |
|---|---|
| id, amount, orderReference | Identifiant, { amountMinor, assetId }, référence marchande. |
| description, providerConnectionId, confirmedAt | Champs pouvant être null ; dates ISO. |
| status, settlementStatus, environment | États distincts du paiement, du règlement et de l’environnement. |
| expiresAt, createdAt, createdBy | Dates ISO et identifiant du créateur. |
| attempts et receipt du détail | Historique des tentatives ; reçu ou null. La liste ajoute plutôt provider/providerLabel. |
Soumission ne signifie pas confirmation.
Une tentative exige providerConnectionId, payment.collect et sa propre clé d’idempotence. La réponse 201 contient attemptId et providerReference. Une tâche persistante soumet ensuite au fournisseur ; cette réponse ne prouve pas la réussite. L’annulation exige JSON, clé d’idempotence et payment.cancel. Une tentative non résolue bloque l’annulation.
- États : requires_payment, processing, requires_review, succeeded, failed, canceled, expired.
- Même clé/corps rejoue statut/corps et ajoute idempotent-replayed: true. Un corps différent avec la même clé retourne idempotency_conflict (409).
- Le wrapper JSON sélectionné retourne cache-control: no-store et x-request-id. Les erreurs métier contiennent error.code, error.message et error.requestId ; les erreurs inconnues retournent internal_error générique (500).
Choisir la reprise selon le code.
Ces correspondances sont celles du domaine, pas une garantie que chaque route produit tous les codes. Une erreur de transport ne prouve pas le rejet de l’opération.
| Code / HTTP | Action d’évaluation |
|---|---|
| invalid_request / 400 | Corriger champ ou type de contenu ; vérifier le contrat. |
| unauthenticated / 401 ; forbidden / 403 ; not_found / 404 | Vérifier session et périmètre. Un 404 limité ne prouve pas l’inexistence globale. |
| idempotency_conflict / 409 ; invalid_transition / 409 | Examiner demande initiale et état ; ne pas contourner par un nouveau débit. |
| asset_mismatch, environment_mismatch, capability_disabled, quote_expired / 422 | Résoudre prérequis actif/environnement/autorisation/cotation. |
| unbalanced_journal / 422 | Escalader l’erreur comptable ; ne pas inventer de mouvement correctif. |
| rate_limited / 429 ; provider_unavailable / 503 ; internal_error / 500 | Conserver l’identité ; utiliser consultation/reprise convenues et vérifier la soumission. |
Le contrat JSON sélectionné.
Schémas des entrées/sorties et opérations sélectionnées. Documentaire ; aucun appel ni identifiant.