Idempotent par conception
La même clé avec le même corps renvoie le même lien : un appel répété ne crée jamais un second paiement.
Développeurs
FastTrackPay est un point d’accès de l’API de paiement de Wealthreader : HTTPS et JSON. Envoyez le paiement, redirigez votre client et recevez la notification avec votre référence.
Pour commencer, nous activons les paiements et votre profil de paiement sur votre clé d’API Wealthreader. Si vous utilisez déjà l’API, c’est la même clé.
Un POST avec votre clé d’API, une clé d’idempotence qui est aussi votre référence, et le corps du paiement : montant, devise, bénéficiaire, libellé, priorité et URL de notification.
# Créer le paiement
curl 'https://api.wealthreader.com/payments/?action=fast-track' \
-H "X-API-Key: $API_KEY" \
-H "Idempotency-Key: invoice-F-2026-104" \
-H "Content-Type: application/json" \
-d '{
"amount": "2450.00",
"currency": "EUR",
"beneficiary": {
"name": "Entreprise Exemple SARL",
"iban": "ES9121000418450200051332"
},
"reference": "Facture F-2026-104",
"priority": "instant",
"notification_url": "https://example.com/payments/notice"
}'
La réponse contient l’URL du paiement et son identifiant. Redirigez votre client vers l’URL : elle expire au bout de quelques minutes (15 par défaut), créez-la donc au moment où il va payer.
{
"url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
Lorsque le paiement atteint un statut final, nous envoyons un POST à votre notification_url avec outcome ok ou ko et votre référence dans customer_reference. Répondez avec un code 2xx.
La notification peut arriver plus d’une fois et n’est pas signée : avant de remettre quelque chose de valeur, confirmez le statut avec POST /payments/?action=status.
{
"outcome": "ok",
"payment_status": "settled",
"customer_reference": "invoice-F-2026-104",
"payment_intent_id": "22222222-2222-4222-8222-222222222222"
}
En-têtes, champs, statuts et erreurs de POST /payments/?action=fast-track. Le détail complet figure dans le guide.
| En-tête | Validation |
|---|---|
X-API-Key | Votre clé d’API Wealthreader, avec les paiements activés. |
Idempotency-Key | De 16 à 128 caractères : lettres, chiffres et . _ : -. C’est votre référence du paiement ; elle revient dans la notification sous customer_reference. |
| Champ | Validation | Obligatoire |
|---|---|---|
amount | Montant en euros sous forme de chaîne, avec jusqu’à deux décimales : "2450.00". Minimum 0.01. | Oui |
currency | EUR. | Oui |
beneficiary.name | Nom du bénéficiaire, de 1 à 140 caractères. | Oui |
beneficiary.iban | IBAN du bénéficiaire, sans espaces et avec des chiffres de contrôle valides. Il n’est pas nécessaire de l’enregistrer au préalable. | Oui |
reference | Libellé que verra votre client et qui figure sur le relevé, jusqu’à 140 caractères. | Oui |
priority | instant pour un virement instantané ou normal pour un virement standard. | Oui |
notification_url | URL https publique à laquelle nous envoyons la notification ok ou ko. | Oui |
logo | URL https publique du logo de votre entreprise au format SVG, que la page de paiement affiche à côté du bénéficiaire. | Non |
payment_status | Signification | outcome |
|---|---|---|
settled |
La banque a réglé le paiement. | ok |
rejected |
La banque a rejeté le paiement, y compris en raison du montant ou parce qu’elle n’accepte pas le virement instantané. | ko |
cancelled |
Il a été annulé avant d’aboutir. | ko |
expired |
La session de paiement a expiré sans aboutir. | ko |
failed |
Le paiement n’a pas pu aboutir. | ko |
pending |
En cours : ce n’est pas encore un statut final. | Pas encore de notification |
| HTTP | Code | Signification |
|---|---|---|
400 |
idempotency_key_required |
L’en-tête Idempotency-Key est absent ou sa longueur n’est pas valide. |
401 |
invalid_api_key |
Clé d’API non valide. |
403 |
payments_not_allowed, payment_profile_required |
Votre clé n’a pas les paiements activés ou il lui manque le profil de paiement. |
409 |
idempotency_conflict |
Vous avez réutilisé une Idempotency-Key avec d’autres données. |
422 |
invalid_request, invalid_amount, invalid_beneficiary, invalid_notification_url |
Corps non valide : un champ en trop ou manquant, ou un montant, un bénéficiaire ou une URL de notification incorrects. |
429 |
api_limit_reached |
Vous avez atteint la limite d’appels. |
503 |
payments_disabled |
Les paiements ne sont pas disponibles pour le moment. |
Les erreurs renvoient un JSON avec success à false et le code du tableau dans error.code.
La même clé avec le même corps renvoie le même lien : un appel répété ne crée jamais un second paiement.
Choisissez pour chaque paiement le virement instantané ou standard. Si la banque n’accepte pas le virement instantané, la notification arrive en ko.
Envoyez l’URL de votre logo au format SVG et la page de paiement l’affiche à côté du nom du bénéficiaire.
Votre client vérifie le montant, le bénéficiaire et le libellé, choisit sa banque et autorise. Pour l’instant, la page s’affiche en espagnol.
Ouvrir le guide Paiements Fast Track (s’ouvre dans un nouvel onglet) Ouvrir la référence de l’API (s’ouvre dans un nouvel onglet) Demander l’accès
Nous vous présentons FastTrackPay avec les encaissements de votre activité.