Paiements avec Wealth Reader

L’architecture en deux étapes

L’intégration des paiements suit une stricte séparation des responsabilités en deux étapes :

sequenceDiagram
autonumber
actor Usuario as Utilisateur
participant Front as Frontend (Commerce)
participant Back as Backend (Commerce)
participant API as API Wealth Reader
participant Widget as Widget de paiement
participant Banco as Banque (SCA)
Note over Back,API: Étape précédente (profils gérés uniquement)
Back->>API: POST /payments/?action=profile-institutions
API-->>Back: Catalogue de profils (institution_code)
Note over Back,API: Étape 1 : Créer l’intention immuable (serveur à serveur)
Back->>API: POST /payments/?action=create (avec X-API-Key et Idempotency-Key)
API-->>Back: 201 avec payment.id + payment.widget.token éphémère
Note over Front,Widget: Étape 2 : Charger et autoriser dans le widget (navigateur)
Back->>Front: Livraison payment.id et payment.widget.token
Front->>Widget: WealthReaderPayments.mount(...) ou load-payments.js
Widget->>Usuario: Affiche une institution, un montant et un libellé immuables
Usuario->>Widget: Autoriser le paiement
Widget->>Banco: Rediriger / Application vers Application (SCA)
Banco->>API: Retour de la SCA à la callback de Wealth Reader
API-->>Widget: Confirmation technique de l’autorisation
Note over Back,API: Réconciliation financière et confirmation
loop Vers l’état terminal
Back->>API: POST /payments/?action=status
API-->>Back: payment_status: not_initiated | pending | settled | ...
end

1. Étape 1 (Backend sécurisé): Votre serveur crée un Intention de paiement (POST /payments/?action=create) avec ses X-API-Key, un Idempotency-Key et Content-Type: application/json. Dans cet appel, le montant (amount_minor, en cents), la devise (currency, aujourd’hui seulement EUR), le bénéficiaire (beneficiary.name et beneficiary.iban), le libellé du relevé (reference), sa référence interne (customer_reference) et l’origine web autorisée (allowed_origin) sont fixés de manière immuable. Ces six champs sont obligatoires, et le corps est une liste blanche stricte : tout champ non reconnu retourne 422 invalid_request.
2. Réponse: 201 avec {"success": true, "payment": {…}} — ou 200 s’il s’agit d’une répétition idempotente. L’identifiant d’intention entre en jeu payment.id et le jeton éphémère du widget dans payment.widget.token.
3. Étape 2 (Frontend du commerçant): Le navigateur monte le widget en utilisant le script officiel de load-payments.js ou la fonction WealthReaderPayments.mount(), fournissant ainsi seulement la payment.id et payment.widget.token. L’utilisateur sélectionne sa banque (si elle n’a pas été présélectionnée dans l’intention) et effectue l’authentification forte (SCA) dans l’interface bancaire.
4. Confirmation financière: Votre backend interroge l’état via POST /payments/?action=status, dont le corps est exactement {"payment_intent_id": "<id>"}. Pas de webhook : Il interroge jusqu’à atteindre un état terminal.

Deux modèles de paiement

Wealth Reader prend en charge deux modèles selon les besoins de l’entreprise :

1. Intégration standard pour les commerçants (Propre bénéficiaire):
   • Le marchand définit librement le nom et l’IBAN du bénéficiaire, le montant, la devise (EUR), le libellé et sa référence de commande.
   • Vous pouvez filtrer quelles banques rendre disponibles à l’utilisateur via allowed_institution_codes ou autoriser l’ensemble du catalogue.
2. Profils gérés (comme cruz_roja_demo):
   • Conçu pour les dons et les démonstrations publiques.
   • Le serveur configure les comptes officiels de destination pour garantir que les fonds ne puissent être dirigés qu’à l’association caritative (par exemple, la Croix-Rouge espagnole avec des montants compris entre 0,01 EUR et 1,00 EUR).

Annuaire unifié des entités bancaires

Wealth Reader fournit un catalogue unifié des entités européennes préparées à l’initiation des paiements via PSD2 via :

• GET https://api.wealthreader.com/payments/entities/?country=ES

Il permet d’obtenir la liste des banques avec leurs noms standardisés, logos, méthodes de transfert prises en charge et exigences techniques (comme la nécessité de demander l’IBAN du débiteur auprès du payeur). Il prend en charge les filtres country, search (alias q), code, payment_method, limit et offset.

Ce point final est Public : Aucune X-API-Key requise. L’envoyer n’apporte rien et consomme un appel de votre quota de votre clé d’accès.

Utilisez les codes exactement tels qu’ils sont retournés dans code. La création de l’intention valide le format de allowed_institution_codes, mais ne vérifie pas leur présence dans le catalogue : un code mal orthographié ne donne pas d’erreur lors de la création et apparaît plus tard comme un sélecteur de banque vide.

Séparation des responsabilités

• L’accréditation de paiement (X-API-Key) est utilisée Serveur à serveur uniquement. Il ne devrait jamais être inclus dans les dépôts frontend ou publics.
• Le navigateur ne reçoit que l’identifiant d’intention et un jeton éphémère de courte durée lié à l’origine HTTPS.
• Le widget ne peut pas modifier le montant, la devise, le bénéficiaire, le concept ou les institutions autorisées.
• Fermer le modal ou le widget ne remplace pas la requête de l’état financier en arrière-plan.
• Les paiements ne partagent pas les identifiants, jetons ou rappels avec le produit d’agrégation bancaire de Wealth Reader.

Clés d’accès et quota

Votre identifiant de paiement doit avoir le produit PAYMENTS activé ; sinon, l’API répond 403 payments_not_allowed. Un identifiant manquant ou mal formaté renvoie 401 invalid_api_key.

Étape suivante

Continuer avec Intégration et widget.