Betalinger

Pagos Fast Track

Si elige esta vía, el resto de las secciones de pagos ya no son necesarias. Un solo POST devuelve la URL de pago, y Wealth Reader avisa a su servidor cuando el resultado es OK o KO.

El pagador abre esa URL y autoriza en su banco. Por debajo se crea la misma intención inmutable que el resto de la API: el importe, el destinatario y el concepto quedan fijados antes de llegar al navegador y la cabecera Idempotency-Key evita un segundo cargo si la llamada se corta.

Crear el pago

POST /payments/?action=fast-track

Cabeceras obligatorias: Content-Type: application/json, X-API-Key y Idempotency-Key (16 a 128 caracteres visibles, letras, números y . _ : -; un UUID v4 vale). Esa clave es también la referencia de comercio: no hace falta enviarla en el cuerpo. Si repite la misma clave con el mismo cuerpo, recibe otra vez la misma URL. Si la reutiliza con otros datos, la respuesta es 409 idempotency_conflict.

Campo	Tipo	Descripción
`amount`	Cadena	Importe en unidades mayores. `15.50` son 15,50. También se admite un entero sin decimales (`15`). Como máximo dos decimales.
`currency`	Cadena	Divisa ISO 4217. En esta versión, `EUR`.
`beneficiary`	Objeto	Destinatario: `name` (1 a 140 caracteres) e `iban` (sin espacios, con dígito de control).
`reference`	Cadena	Concepto del extracto, hasta 140 caracteres.
`priority`	Cadena	`normal` o `instant`.
`notification_url`	Cadena	URL `https` pública a la que se avisa el OK o el KO.

El cuerpo es una lista blanca. Un campo de más, o uno obligatorio que falte, responde 422 invalid_request.

Una inmediata no tiene un tope propio en esta API. El banco rechaza la que no puede aceptar, también por importe, y ese rechazo llega como KO al 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"
  }'

La respuesta, con 201 la primera vez y 200 si la clave ya existía, contiene solo la URL:

{
  "url": "https://widget.wealthreader.com/payments/pay/#payment_intent_id=…&widget_token=…&api_origin=https%3A%2F%2Fapi.wealthreader.com"
}

Redirija al pagador a esa URL. El token vive en el fragmento, caduca con el widget (habitualmente de 15 a 30 minutos) y no debe registrarse en sus logs.

Aviso de OK o KO

Cuando el pago llega a un estado final, Wealth Reader hace POST a notification_url con Content-Type: application/json:

{
  "outcome": "ok",
  "payment_status": "settled",
  "customer_reference": "11111111-1111-4111-8111-111111111111"
}

outcome es ok solo si el banco ha liquidado (settled). rejected, cancelled, expired y failed avisan ko. El mismo aviso puede repetirse: trate customer_reference más outcome como idempotentes. Responda 2xx para dar el aviso por entregado. Una URL que no sea https pública se rechaza al crear el pago.

Senest opdateret 2026-10-07