Integración y widget de pagos

1. Consultar las instituciones del perfil

Use la credencial server-to-server de alta entropía autorizada para pagos:

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"

curl --request POST 'https://api.wealthreader.com/payments/?action=profile-institutions' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --data '{"profile":"cruz_roja_demo"}'

Respuesta abreviada de ejemplo:

{
  "success": true,
  "profile": {
    "code": "cruz_roja_demo",
    "version": "2026-09-04",
    "currency": "EUR",
    "min_amount_minor": 1,
    "max_amount_minor": 100,
    "reference": "Donativo desde la demo de Wealthreader.com",
    "beneficiary_name": "Cruz Roja Española",
    "payment_attestation": {
      "mode": "live",
      "provider_binding": "PROVIDER_BINDING"
    },
    "institutions": [
      {
        "code": "santander-es",
        "name": "Banco Santander",
        "country": "ES",
        "requires_debtor_iban": true
      }
    ]
  }
}

La lista es autoritativa para esa credencial y ese momento. No muestre ni acepte códigos que no estén en la respuesta. En sandbox se devuelve únicamente una institución simulada; si producción no está activada, no se devuelve una lista real utilizable.

2. Crear una intención de 0,01 EUR

El siguiente ejemplo usa santander-es solo si apareció en la consulta anterior:

: "${WR_API_KEY:?Defina WR_API_KEY en el entorno seguro de su backend}"
: "${WR_PAYMENT_IDEMPOTENCY_KEY:?Genere una clave nueva para este pago lógico}"

curl --request POST 'https://api.wealthreader.com/payments/?action=create' \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: ${WR_API_KEY}" \
  --header "Idempotency-Key: ${WR_PAYMENT_IDEMPOTENCY_KEY}" \
  --data '{
    "profile": "cruz_roja_demo",
    "institution_code": "santander-es",
    "amount_minor": 1,
    "customer_reference": "donativo-demo-0042",
    "allowed_origin": "https://comercio.example",
    "locale": "es",
    "expected_mode": "live"
  }'

Use expected_mode: "mock" únicamente contra el sandbox. Si el modo esperado no coincide con el modo autoritativo, la creación se rechaza. El servidor construye la moneda, el concepto, el beneficiario y la institución permitida.

Respuesta abreviada:

{
  "success": true,
  "payment": {
    "id": "11111111-1111-4111-8111-111111111111",
    "amount_minor": 1,
    "currency": "EUR",
    "state": "ready",
    "interaction_status": "not_started",
    "payment_status": "not_initiated",
    "payment_attestation": {
      "mode": "live",
      "provider_binding": "PROVIDER_BINDING",
      "allowed_institution_codes": ["santander-es"],
      "profile": "cruz_roja_demo",
      "profile_version": "2026-09-04"
    },
    "widget": {
      "url": "https://widget.wealthreader.com/payments/",
      "token": "SHORT_LIVED_WIDGET_TOKEN",
      "expires_at": "2026-09-04T15:30:00+00:00"
    }
  }
}

Antes de entregar el token al navegador, su backend debe comprobar modo, perfil, versión e institución permitida contra la consulta previa.

3. Montar el widget

<div id="wr-payment" data-wr-payment></div>

<script>
  document.querySelector('#wr-payment').addEventListener(
    'wealthreader:payment',
    (event) => {
      if (event.detail.type === 'payment_status') {
        console.log(event.detail.status);
      }

      if (event.detail.type === 'flow_closed') {
        // Terminó la interacción; consulte el estado desde su backend.
      }
    }
  );
</script>
<script
  src="https://widget.wealthreader.com/js/load-payments.js"
  data-target="#wr-payment"
  data-payment-intent-id="11111111-1111-4111-8111-111111111111"
  data-widget-token="SHORT_LIVED_WIDGET_TOKEN"
  data-locale="es">
</script>

El widget obtiene el modo y la institución del bootstrap autenticado. Si la institución exige una cuenta de origen, solicita el IBAN deudor en el momento de autorizar; no lo devuelve al comercio ni lo incluye en sus eventos. El navegador o la aplicación bancaria siguen siendo necesarios para completar SCA: una secuencia de curl no los sustituye.

Una autorización puede encadenar más de una redirección SCA o continuar de forma desacoplada en la aplicación bancaria. El widget reutiliza la ventana abierta por el gesto del usuario, conserva el mismo PaymentIntent y aplica sondeo acotado; nunca vuelve a crear ni iniciar la orden para continuar esos estados.

El cargador valida event.origin y event.source. Los eventos usan { source: "wealthreader-payments", version: "1.0", type: "..." } y no contienen datos bancarios ni detalles internos.

Eventos principales

Siguiente paso

Revise Intenciones e idempotencia.