Desenvolupadors

Una crida. Un enllaç de pagament.

FastTrackPay és un punt de l'API de pagaments de Wealthreader: HTTPS i JSON. Enviï el pagament, redirigeixi el seu client i rebi l'avís amb la seva referència.

Per començar, activem els pagaments i el seu perfil de pagament a la seva clau d'API de Wealthreader. Si ja utilitza l'API, és la mateixa clau.

  1. Creï el pagament

    Un POST amb la seva clau d'API, una clau d'idempotència que també és la seva referència i el cos del pagament: import, divisa, beneficiari, concepte, prioritat i URL d'avís.

    # Crear el pagament
    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": "Empresa Exemple, S.L.",
          "iban": "ES9121000418450200051332"
        },
        "reference": "Factura F-2026-104",
        "priority": "instant",
        "notification_url": "https://example.com/payments/notice"
      }'
  2. Porti el seu client a l'enllaç

    La resposta porta l'URL del pagament i el seu identificador. Redirigeixi el seu client a l'URL: caduca al cap de pocs minuts (15 per defecte), així que creï'l quan vagi a pagar.

    {
      "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…",
      "payment_intent_id": "22222222-2222-4222-8222-222222222222"
    }
  3. Rebi l'avís

    Quan el pagament arriba a un estat final, enviem un POST al seu notification_url amb outcome ok o ko i la seva referència a customer_reference. Respongui amb un codi 2xx.

    L'avís pot arribar més d'una vegada i no va signat: abans de lliurar res de valor, confirmi l'estat amb POST /payments/?action=status.

    {
      "outcome": "ok",
      "payment_status": "settled",
      "customer_reference": "invoice-F-2026-104",
      "payment_intent_id": "22222222-2222-4222-8222-222222222222"
    }

Referència ràpida

Capçaleres, camps, estats i errors de POST /payments/?action=fast-track. El detall complet és a la guia.

Capçaleres de la petició
CapçaleraValidació
X-API-KeyLa seva clau d'API de Wealthreader, amb els pagaments actius.
Idempotency-KeyDe 16 a 128 caràcters: lletres, números i . _ : -. És la seva referència del pagament i torna a l'avís com a customer_reference.
Camps del cos
CampValidacióObligatori
amountImport en euros com a cadena, amb fins a dos decimals: "2450.00". Mínim 0.01.Sí
currencyEUR.Sí
beneficiary.nameNom del beneficiari, d'1 a 140 caràcters.Sí
beneficiary.ibanIBAN del beneficiari, sense espais i amb dígits de control vàlids. No cal donar-lo d'alta abans.Sí
referenceConcepte que veurà el seu client i que arriba a l'extracte, fins a 140 caràcters.Sí
priorityinstant per a transferència immediata o normal per a transferència estàndard.Sí
notification_urlURL https públic al qual enviem l'avís ok o ko.Sí
logoURL https públic del logotip de la seva empresa en SVG, que la pàgina de pagament mostra al costat del beneficiari.No
Estats del pagament i avís
payment_statusSignificatoutcome
settled El banc ha liquidat el pagament. ok
rejected El banc ha rebutjat el pagament, també per l'import o per no admetre la immediata. ko
cancelled S'ha cancel·lat abans de completar-se. ko
expired La sessió de pagament ha caducat sense completar-se. ko
failed El pagament no s'ha pogut completar. ko
pending En curs: encara no és un estat final. Encara sense avís
Codis d'error
HTTPCodiSignificat
400 idempotency_key_required Falta la capçalera Idempotency-Key o la seva longitud no és vàlida.
401 invalid_api_key Clau d'API no vàlida.
403 payments_not_allowed, payment_profile_required La seva clau no té els pagaments actius o li falta el perfil de pagament.
409 idempotency_conflict Ha reutilitzat una Idempotency-Key amb altres dades.
422 invalid_request, invalid_amount, invalid_beneficiary, invalid_notification_url Cos no vàlid: un camp de més o que falta, o un import, beneficiari o URL d'avís incorrectes.
429 api_limit_reached Ha arribat al límit de crides.
503 payments_disabled Els pagaments no estan disponibles en aquest moment.

Els errors responen amb un JSON amb success a false i el codi de la taula a error.code.

Detalls d'integració

Idempotent per disseny

La mateixa clau amb el mateix cos retorna el mateix enllaç: una crida repetida mai no crea un segon pagament.

Immediata o estàndard

Triï en cada pagament la transferència immediata o l'estàndard. Si el banc no accepta la immediata, l'avís arriba com a ko.

La seva marca al pagament

Enviï l'URL del seu logotip en SVG i la pàgina de pagament el mostra al costat del nom del beneficiari.

La pàgina de pagament

El seu client revisa l'import, el beneficiari i el concepte, tria el seu banc i autoritza. De moment, la pàgina es mostra en castellà.

No li demani una transferència al seu client: enviï-li el pagament preparat

Li mostrem FastTrackPay amb els cobraments del seu negoci.

Sol·licitar una demo