Desarrolladores

Una llamada. Un enlace de pago.

FastTrackPay es un punto de la API de pagos de Wealthreader: HTTPS y JSON. Envíe el pago, redirija a su cliente y reciba el aviso con su referencia.

Para empezar, activamos los pagos y su perfil de pago en su clave de API de Wealthreader. Si ya usa la API, es la misma clave.

  1. Cree el pago

    Un POST con su clave de API, una clave de idempotencia que también es su referencia y el cuerpo del pago: importe, divisa, beneficiario, concepto, prioridad y URL de aviso.

    # Crear el pago
    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 de Ejemplo S.L.",
          "iban": "ES9121000418450200051332"
        },
        "reference": "Factura F-2026-104",
        "priority": "instant",
        "notification_url": "https://example.com/payments/notice"
      }'
  2. Lleve a su cliente al enlace

    La respuesta trae la URL del pago y su identificador. Redirija a su cliente a la URL: caduca a los pocos minutos (15 por defecto), así que créela cuando vaya a pagar.

    {
      "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…",
      "payment_intent_id": "22222222-2222-4222-8222-222222222222"
    }
  3. Reciba el aviso

    Cuando el pago llega a un estado final, enviamos un POST a su notification_url con outcome ok o ko y su referencia en customer_reference. Responda con un código 2xx.

    El aviso puede llegar más de una vez y no va firmado: antes de entregar algo valioso, confirme el estado con POST /payments/?action=status.

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

Referencia rápida

Cabeceras, campos, estados y errores de POST /payments/?action=fast-track. El detalle completo está en la guía.

Cabeceras de la petición
CabeceraValidación
X-API-KeySu clave de API de Wealthreader, con los pagos activos.
Idempotency-KeyDe 16 a 128 caracteres: letras, números y . _ : -. Es su referencia del pago y vuelve en el aviso como customer_reference.
Campos del cuerpo
CampoValidaciónObligatorio
amountImporte en euros como cadena, con hasta dos decimales: "2450.00". Mínimo 0.01.Sí
currencyEUR.Sí
beneficiary.nameNombre del beneficiario, de 1 a 140 caracteres.Sí
beneficiary.ibanIBAN del beneficiario, sin espacios y con dígitos de control válidos. No hay que darlo de alta antes.Sí
referenceConcepto que verá su cliente y que llega al extracto, hasta 140 caracteres.Sí
priorityinstant para transferencia inmediata o normal para transferencia estándar.Sí
notification_urlURL https pública a la que enviamos el aviso ok o ko.Sí
logoURL https pública del logotipo de su empresa en SVG, que la página de pago muestra junto al beneficiario.No
Estados del pago y aviso
payment_statusSignificadooutcome
settled El banco ha liquidado el pago. ok
rejected El banco ha rechazado el pago, también por importe o por no admitir la inmediata. ko
cancelled Se ha cancelado antes de completarse. ko
expired La sesión de pago ha caducado sin completarse. ko
failed El pago no se ha podido completar. ko
pending En curso: aún no es un estado final. Sin aviso aún
Códigos de error
HTTPCódigoSignificado
400 idempotency_key_required Falta la cabecera Idempotency-Key o su longitud no es válida.
401 invalid_api_key Clave de API no válida.
403 payments_not_allowed, payment_profile_required Su clave no tiene los pagos activos o le falta el perfil de pago.
409 idempotency_conflict Ha reutilizado una Idempotency-Key con otros datos.
422 invalid_request, invalid_amount, invalid_beneficiary, invalid_notification_url Cuerpo no válido: un campo de más o que falta, o un importe, beneficiario o URL de aviso incorrectos.
429 api_limit_reached Ha alcanzado el límite de llamadas.
503 payments_disabled Los pagos no están disponibles en este momento.

Los errores responden con un JSON con success a false y el código de la tabla en error.code.

Detalles de integración

Idempotente por diseño

La misma clave con el mismo cuerpo devuelve el mismo enlace: una llamada repetida nunca crea un segundo pago.

Inmediata o estándar

Elija en cada pago la transferencia inmediata o la estándar. Si el banco no acepta la inmediata, el aviso llega como ko.

Su marca en el pago

Envíe la URL de su logotipo en SVG y la página de pago lo muestra junto al nombre del beneficiario.

La página de pago

Su cliente revisa el importe, el beneficiario y el concepto, elige su banco y autoriza. Por ahora, la página se muestra en español.

No le pida a su cliente una transferencia: envíele el pago preparado

Le mostramos FastTrackPay con los cobros de su negocio.

Solicitar una demo