Paiements

Intentions de paiement et idempotence

Une intention de paiement fixe de manière immuable les conditions économiques de la transaction avant que l’utilisateur n’interagisse avec le widget. Cela empêche un client malveillant de manipuler le montant, le compte de destination ou le concept de transfert sur le frontend.

Paramètres de création (`POST /payments/?action=create`)

1. Modèle standard pour les commerçants (bénéficiaire propre)

Dans ce modèle, le commerçant définit toutes les données de recouvrement :

Champ	Type	Obligatoire	Description et règles
`amount_minor`	Entier	Oui	Quantité en unités plus petites (cents). Par exemple, `1500` représente `15,00 EUR`.
`currency`	Chaîne	Oui	Code de devise ISO 4217 à trois lettres. Actuellement `EUR`.
`beneficiary`	Objet	Oui	Données de compte de destination : `name` (détenteur, 1 à 140 caractères) et `iban` (IBAN valide sans espaces, avec vérification de la clé de contrôle). Ne supporte que ces deux clés.
`reference`	Chaîne	Oui	Concept visible sur le relevé bancaire (max. 140 caractères).
`customer_reference`	Chaîne	Oui	Identifiant interne de votre commande ou de votre client (1 à 128 caractères : lettres, chiffres, `.`, `_`, `:`, `-`; doit commencer par une lettre ou un chiffre).
`allowed_origin`	Chaîne	Oui	Origine HTTPS exacte qui va intégrer le widget (par exemple `https://tienda.example.com`), sans chemin.
`allowed_institution_codes`	Tableau	Non	Liste des codes d’entité autorisés (par exemple `["santander-es", "bbva-es"]`). Si elle est omise, toute entité dans le catalogue est autorisée.
`locale`	Chaîne	Non	Le langage de l’interface widget. Cette version accepte uniquement `es` ; toute autre valeur retourne `422 invalid_locale`.
`expected_mode`	Chaîne	Non	`mock` ou `live`. Vérifie que vous appelez l’environnement attendu ; ne change pas d’environnement. Si cela ne correspond pas, `409 payment_mode_mismatch`.

Le corps utilise une liste blanche stricte: Envoyer un champ qui ne figure pas dans cette table retourne 422 invalid_request, tout comme l’omission d’un champ requis. L’en-tête Content-Type: application/json est requis (415 json_required) et le corps est limité à 32 Ko.

2. Modèle avec profil géré (Donations/Démonstrations)

Pour les cas réglementés ou les démonstrations publiques telles que cruz_roja_demo, le serveur impose les règles financières et établit les comptes cibles officiels :

Champ	Type	Obligatoire	Description et règles
`profile`	Chaîne	Oui	Identifiant de profil (par exemple `cruz_roja_demo`).
`institution_code`	Chaîne	Oui	Code d’entité sélectionné par l’utilisateur (d’après `profile-institutions`).
`amount_minor`	Entier	Oui	Montant limité par les règles du profil (par exemple de 1 à 100 centimes).
`customer_reference`	Chaîne	Oui	La référence d’audit de votre propre système.
`allowed_origin`	Chaîne	Oui	Origine HTTPS du widget.
`locale`	Chaîne	Non	Langage des widgets (`es`).
`expected_mode`	Chaîne	Non	Mode attendu (`mock` ou `live`).

Lorsque profile est spécifié, le serveur attribue automatiquement le bénéficiaire officiel et le concept correspondant. N’envoyez pas beneficiary ni reference sur des demandes avec un profil géré.

Règle de `Idempotency-Key`

L’en-tête Idempotency-Key est requis dans chaque appel de création. Il doit contenir entre 16 et 128 caractères ASCII visibles, sans espaces (par exemple, un UUID v4). Son champ d’application est propre à l’entreprise authentifiée :

Même clé et même corps : Restitue l’intention initiale créée précédemment avec idempotent_replay: true. Aucun nouveau paiement n’est généré et l’ordre bancaire n’est pas dupliqué.
Même clé et corps différent : Répondez immédiatement par HTTP 409 Conflict.
Même clé dans une autre entreprise : appartient à un autre espace complètement isolé d’idempotence.

Si un appel de création subit une panne réseau ou un délai d’expiration, Réessayez avec exactement le même en-tête Idempotency-Key et le même corps. Ne générez pas de nouvelle clé en cas d’erreur transitoire.

Persistance et cycle de vie

Persistance précédente : L’intention est enregistrée dans la base de données avant de retourner la réponse ou d’interagir avec un connecteur bancaire.
Jeton éphémère du widget : Le jeton de réponse (payment.widget.token) a une validité de courte durée (généralement 15 à 30 minutes) et ne peut être utilisé qu’à partir de la allowed_origin déclarée.
Verrouillage de concurrence : Le système met en œuvre un contrôle optimiste et Baux pour empêcher que deux appels simultanés n’autorisent ou modifient la même intention.

Codes d’erreur courants

HTTP	Code	Cause	Action recommandée
`400`	`idempotency_key_required`	L’en-tête `Idempotency-Key` est manquant ou mal formaté.	Générez une clé valide de 16 à 128 caractères ASCII visibles, sans espaces.
`409`	`idempotency_conflict`	La clé a été réutilisée avec différents détails de paiement.	Générez une nouvelle clé pour d’autres paiements ou réutilisez le même corps.
`409`	`payment_mode_mismatch`	`expected_mode` ne correspond pas au mode de l’environnement que vous appelez.	Vérifiez si vous visez le bac à sable ou la production ; le mode est défini par le déploiement, pas par l’appel.
`401`	`invalid_api_key`	L’en-tête `X-API-Key`est manquant, son format est invalide, ou l’identifiant n’existe pas ou est inactif.	Vérifiez la clé d’accès. Ne l’incluez jamais dans le front-end.
`403`	`payments_not_allowed`	La clé API n’a pas activé le produit `PAYMENTS` .	Contactez le support Wealth Reader pour activer les paiements sur votre compte.
`403`	`payment_profile_not_allowed`	Le profil géré n’est pas activé pour votre entreprise.	Demandez l’enregistrement du profil à Wealth Reader.
`429`	`api_limit_reached`	Votre clé d’accès a épuisé le compteur d’appels cumulé.	Ce problème ne se résout pas en réessayant ou en attendant: Il n’y a pas de fenêtre ni de réinitialisation automatique. Demande d’extension de la limite.
`415`	`json_required`	L’en-tête `Content-Type: application/json` manque.	Envoyez le corps en JSON.
`422`	`invalid_request`	Un champ requis manque ou un champ non reconnu a été soumis.	Vérifie la table des paramètres : le corps est une liste blanche stricte.
`422`	`invalid_institution`	L’entité sélectionnée est indisponible ou invalide.	Voir `GET /payments/entities/` pour les codes valides.
`422`	`invalid_amount`	Le montant est inférieur au minimum (0,01 €) ou n’est pas un entier.	Vérifiez que vous envoyez un entier en cents (`amount_minor`).

Étape suivante

Continuer avec États, interrogation périodique et rapprochement.

Dernière mise à jour 2026-09-10

Paramètres de création (POST /payments/?action=create)