Paiements

Paiements Fast Track

Si vous choisissez cette voie, vous n’avez pas besoin d’intégrer le widget ni de suivre les autres sections consacrées aux paiements. Un seul POST renvoie l’URL de paiement, et Wealthreader avertit votre serveur lorsque le résultat est OK ou KO. Par précaution, conservez le payment_intent_id de la réponse : il vous permet de consulter l’état si la notification n’arrive pas.

Le payeur ouvre cette URL et autorise le paiement auprès de sa banque. En arrière-plan, la même intention immuable que dans le reste de l’API est créée : le montant, le bénéficiaire et le libellé sont fixés avant d’atteindre le navigateur, et l’en-tête Idempotency-Key évite un second débit si l’appel est interrompu.

Créer le paiement

POST /payments/?action=fast-track

En-têtes obligatoires : Content-Type: application/json, X-API-Key et Idempotency-Key. La clé comporte de 16 à 128 caractères, commence par une lettre ou un chiffre et n’admet que des lettres, des chiffres et . _ : - ; un UUID v4 convient. Si elle est absente ou si sa longueur n’est pas valide, la réponse est 400 idempotency_key_required ; si elle contient d’autres caractères, 422 invalid_customer_reference. Cette clé est aussi la référence marchand : il n’est pas nécessaire de l’envoyer dans le corps. Si vous répétez la même clé avec le même corps, vous recevez de nouveau la même URL. Si vous la réutilisez avec d’autres données, la réponse est 409 idempotency_conflict.

Champ	Type	Description
`amount`	Chaîne	Montant en unités principales, sous forme de chaîne JSON. `"15.50"` correspond à 15,50. Un entier sans décimales (`"15"`) est également accepté. Deux décimales au maximum : `"15.5"` et `"15.50"` sont le même montant. Minimum `0.01`. Le maximum est limité au plafond que chaque client a configuré auprès de sa banque. En dehors de ces règles de format, `422 invalid_amount`.
`currency`	Chaîne	Devise ISO 4217. Dans cette version, `EUR`.
`beneficiary`	Objet	Bénéficiaire : `name` (de 1 à 140 caractères) et `iban` (sans espaces, avec chiffres de contrôle).
`reference`	Chaîne	Libellé figurant sur le relevé, jusqu’à 140 caractères.
`priority`	Chaîne	`normal` ou `instant`.
`notification_url`	Chaîne	URL `https` publique à laquelle le OK ou le KO est notifié.
`logo`	Chaîne	Facultatif. URL `https` publique du logo de votre commerce au format SVG : le chemin doit se terminer par `.svg` (les paramètres de requête sont admis), sans identifiants ni adresses privées, jusqu’à 2048 caractères ASCII. La page de paiement l’affiche au-dessus du récapitulatif, à côté du nom du bénéficiaire ; sans `logo`, il n’y a pas d’en-tête marchand. Wealthreader ne télécharge pas l’URL : c’est le navigateur du payeur qui la charge. Toute autre valeur renvoie `422 invalid_logo`.

Tous les champs sont obligatoires sauf logo. Le corps est une liste blanche. Un champ en trop, ou un champ obligatoire manquant, renvoie 422 invalid_request. logo fait partie du paiement : répéter la même Idempotency-Key avec un autre logo renvoie aussi 409 idempotency_conflict.

Un paiement instantané n’a pas de plafond propre dans cette API. La banque rejette celui qu’elle ne peut pas accepter, y compris en raison du montant, et ce rejet arrive sous forme de KO à la notification_url.

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere un UUID v4 para este pago}"

curl --request POST 'https://api.wealthreader.com/payments/?action=fast-track' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "amount": "15.50",
    "currency": "EUR",
    "beneficiary": {
      "name": "Comercio Online S.L.",
      "iban": "ES9121000418450200051332"
    },
    "reference": "Pedido 78901",
    "priority": "normal",
    "notification_url": "https://tienda.example.com/pagos/aviso",
    "logo": "https://tienda.example.com/marca/logo.svg"
  }'

La réponse, avec 201 la première fois et 200 si la clé existait déjà, contient l’URL et l’identifiant du paiement :

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

Redirigez le payeur vers l’URL. Le jeton se trouve dans le fragment, expire avec le widget (généralement 15 minutes) et ne doit pas être enregistré dans vos journaux. Conservez payment_intent_id avec votre commande.

Notification OK ou KO

Lorsque Wealthreader vérifie l’état du paiement et constate qu’il est dans un état final, il envoie un POST à notification_url avec Content-Type: application/json et User-Agent: WealthReader-Payments :

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111",
  "payment_intent_id": "22222222-2222-4222-8222-222222222222"
}

outcome vaut ok uniquement si la banque a réglé le paiement (settled). rejected, cancelled, expired et failed sont notifiés comme ko. Un résultat ambigu (reconciliation_required) n’est pas final et n’est pas notifié.
customer_reference est votre Idempotency-Key, et payment_intent_id l’identifiant renvoyé lors de la création du paiement.
Répondez 2xx pour que la notification soit considérée comme livrée. Wealthreader attend au maximum 3 secondes et ne suit pas les redirections.
La même notification peut arriver plusieurs fois : traitez customer_reference plus outcome comme idempotents.
Une URL qui n’est pas https publique est rejetée lors de la création du paiement et est revérifiée avant chaque envoi.

Quand elle arrive. L’état est vérifié tant que le payeur reste sur la page de paiement, qui l’interroge jusqu’au résultat final ou jusqu’à l’expiration de la session de paiement, et chaque fois que vous appelez POST /payments/?action=status. Il n’y a pas d’envoi programmé distinct : si le payeur ferme la page avant que la banque ait conclu, ou si votre serveur ne répond pas 2xx, la notification est envoyée lors de la vérification suivante. Par conséquent, si vous n’avez pas reçu la notification quelques minutes après avoir redirigé le payeur, consultez l’état avec le payment_intent_id ; cette consultation déclenche aussi la notification en attente. Voir États, interrogation périodique et rapprochement.

La notification n’est pas signée. Avant de livrer un bien ou un service de valeur, confirmez le résultat avec POST /payments/?action=status en utilisant votre X-API-Key et le payment_intent_id : seul payment_status: settled dans cette réponse constitue une confirmation financière.

Dernière mise à jour 2026-11-08