États, interrogation périodique et rapprochement

Requête depuis le backend

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"

curl --request POST 'https://api.wealthreader.com/payments/?action=status' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --data '{
    "payment_intent_id": "11111111-1111-4111-8111-111111111111",
    "refresh": true
  }'

refresh est optionnel et true par défaut. Wealth Reader limite les requêtes externes selon l’intention ; appliquer le backoff aussi dans votre backend et ne pas créer d’autre intention tant que le résultat reste ambigu.

Trois dimensions différentes

La seule confirmation positive est payment_status: settled, dérivée d’un relevé bancaire explicite de règlement. Un résultat technique DONE, interaction_status: completed ou payment_status: pending ne constitue jamais un règlement.

Résultat ambigu

Une coupure réseau, un délai d’attente ou une réponse non reconnue après l’envoi de l’initiation fait passer l’intention à reconciliation_required et expose payment_status: unknown. Le démarrage ne se répète pas automatiquement.

Le fournisseur actuel n’offre pas de requête qui reconstruit une initiation dont la réponse a été perdue : sa requête d’état nécessite le contexte opaque retourné par cette même initiation. Par conséquent, ce cas nécessite une réconciliation manuelle ; il ne peut pas être récupéré par une requête automatique ou en recherchant l’identifiant de rappel.

Dans ce cas :

1. conserver la clé d’idempotence et l’identifiant ;
2. ne crée pas une autre intention ni n’autorise à nouveau ;
3. Consultez le statut authentifié de Wealth Reader et conservez votre référence de rapprochement sécurisée ;
4. Contactez le support ; ne continuez pas le sondage lorsque automatic_recovery est false.

Pour une intention nécessitant une réconciliation manuelle, la requête serveur-à-serveur peut inclure :

{
  "payment_status": "unknown",
  "reconciliation_required": true,
  "reconciliation": {
    "automatic_recovery": false,
    "reference": "wrp_recon_0123456789abcdef0123",
    "request_id": "11111111-1111-4111-8111-111111111111",
    "correlation_id": "22222222-2222-4222-8222-222222222222",
    "reason": "initiation_rejected"
  }
}

Ces identifiants sont des références expurgées destinées au support. Ils ne sont pas livrés au widget et ne permettent pas au client de rechercher ou de reconstruire l’état interne du fournisseur.

reason est un code Wealth Reader, jamais le texte du fournisseur. initiation_rejected indique que le prestataire a répondu par un rejet définitif de l’initiation ; initiation_response_unavailable, qu’il n’y a pas eu de réponse reconnaissable. Dans les deux cas, l’initiation a déjà été transmise, donc elle n’est pas répétée : conservez la référence et contactez le support.

Rappel et rediffusion

Le retour SCA arrive en rappel exclusivement pour les paiements. Wealth Reader valide la corrélation, transmet les paramètres de la banque au fournisseur tels quels (des noms imprévus sont enregistrés, ils ne rejettent jamais un retour déjà autorisé), consomme le retour une seule fois et préserve l’état sensible chiffré. Une répétition ne répond qu’à HTTP 409; ne dépendez pas d’un code interne dans le corps.

L’authentification peut nécessiter plusieurs redirections. Chaque REDIRECT validé continue dans la même fenêtre de SCA et ouvre un nouveau point de contrôle de rappel ; elle ne crée pas une autre initiation. Un résultat DECOUPLED maintient l’intention en processing pour que le widget vérifie le statut. Un RETRY explicite ne répète que la complétion déjà préparée, avec une attente et un nombre limités de tentatives. ERROR, PASSWORD, MORE_INFO, SELECT_OPTION, un résultat inconnu ou l’épuisement de ces limites se terminent par une réconciliation, jamais par une nouvelle initiation.

Le commerçant n’a pas besoin de publier ou de traiter ce callback. Cette version n’envoie pas de webhooks au commerçant : le contrat public de confirmation repose sur des requêtes périodiques serveur-à-serveur.

Fermeture du widget

flow_closed communique que l’interaction visible a pris fin. Le frontend peut fermer le modal, mais il ne doit pas être affiché « payé » pour cet événement. Le backend conserve la responsabilité de confirmer ou de rapprocher le paiement.

Étape suivante

Complétez la liste des Sécurité et tests.