Développeurs

Un appel. Un lien de paiement.

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é.

  1. Créez le paiement

    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"
      }'
  2. Envoyez votre client vers le lien

    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"
    }
  3. Recevez la notification

    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"
    }

Référence rapide

En-têtes, champs, statuts et erreurs de POST /payments/?action=fast-track. Le détail complet figure dans le guide.

En-têtes de la requête
En-têteValidation
X-API-KeyVotre clé d’API Wealthreader, avec les paiements activés.
Idempotency-KeyDe 16 à 128 caractères : lettres, chiffres et . _ : -. C’est votre référence du paiement ; elle revient dans la notification sous customer_reference.
Champs du corps
ChampValidationObligatoire
amountMontant en euros sous forme de chaîne, avec jusqu’à deux décimales : "2450.00". Minimum 0.01.Oui
currencyEUR.Oui
beneficiary.nameNom du bénéficiaire, de 1 à 140 caractères.Oui
beneficiary.ibanIBAN 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
referenceLibellé que verra votre client et qui figure sur le relevé, jusqu’à 140 caractères.Oui
priorityinstant pour un virement instantané ou normal pour un virement standard.Oui
notification_urlURL https publique à laquelle nous envoyons la notification ok ou ko.Oui
logoURL https publique du logo de votre entreprise au format SVG, que la page de paiement affiche à côté du bénéficiaire.Non
Statuts du paiement et notification
payment_statusSignificationoutcome
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
Codes d’erreur
HTTPCodeSignification
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.

Détails d’intégration

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.

Instantané ou standard

Choisissez pour chaque paiement le virement instantané ou standard. Si la banque n’accepte pas le virement instantané, la notification arrive en ko.

Votre marque sur le paiement

Envoyez l’URL de votre logo au format SVG et la page de paiement l’affiche à côté du nom du bénéficiaire.

La page de paiement

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.

Ne demandez pas de virement à votre client : envoyez-lui le paiement prêt à régler

Nous vous présentons FastTrackPay avec les encaissements de votre activité.

Demander une démo