Verifactu para Stripe: facturas con Checkout y Billing

Respuesta rápida

Stripe y Verifactu resuelven capas distintas: Stripe registra un cobro o una factura de su plataforma; el SIF debe decidir cuándo expedir la factura española y generar su registro de facturación. Checkout, PaymentIntent, Invoice y Refund son objetos/eventos distintos. Stripe recomienda verificar la firma con el cuerpo sin modificar, responder rápido y no depender del orden de entrega; los eventos pueden reintentarse. Consulta la documentación oficial de webhooks de Stripe y la lista de tipos de evento.

VeriFactu Fácil está en prelanzamiento. Esta guía describe un contrato técnico previsto y no anuncia una app de Stripe ni una cuenta disponible para conectar.

No confundas la Invoice de Stripe con la factura fiscal

Una Invoice de Stripe es un objeto de facturación de Stripe y puede producir un PDF, email o página alojada. La obligación española de un SIF añade un registro estructurado con datos definidos por la AEAT. El documento de Stripe puede ser una entrada o representación útil, pero no sustituye automáticamente el registro ni decide la modalidad del SIF.

La AEAT explica qué contiene el registro de alta. La documentación de Stripe sobre facturas también recomienda que sus facturas incluyan la información exigida por la región; eso no convierte una Invoice en el registro AEAT.

Elegir el evento de alta

Flujo Stripe	Evento que puede observarse	Pregunta fiscal pendiente
Checkout puntual	checkout.session.completed	¿La sesión representa pago confirmado y datos completos?
PaymentIntent	payment_intent.succeeded	¿Se factura al éxito o hay captura posterior?
Billing	invoice.paid	¿La factura recurrente de Stripe es la factura fiscal del negocio?
Devolución	refund.created o charge.refunded	¿Qué importe y líneas deben rectificarse?

La referencia de eventos de Stripe define los eventos y sus objetos. No escuches todos para crear facturas: escoge uno por flujo, documenta por qué y usa los demás para reconciliar.

Firma, cuerpo y reintentos

Stripe exige el cuerpo sin modificar para verificar la firma del encabezado Stripe-Signature. Su documentación indica que el endpoint debe devolver un 2xx rápidamente antes de ejecutar lógica compleja. También documenta reintentos automáticos durante hasta tres días en live mode, varios intentos en sandbox y que el orden de eventos no está garantizado.

Un receptor robusto hace esto:

1. lee el cuerpo original;
2. verifica firma, timestamp y endpoint secreto;
3. comprueba livemode y cuenta cuando se usa Connect;
4. guarda el event ID y la versión de API;
5. responde 2xx cuando la entrega está aceptada;
6. procesa en una cola idempotente;
7. consulta la API si falta un objeto o llega un evento posterior antes.

Un reintento de Stripe no debe crear una segunda factura ni consumir otra numeración. La guía API existente explica la clave idempotente del evento externo.

Datos fiscales de Checkout

Stripe Checkout puede recoger tax IDs de clientes cuando se habilita esa función. La guía oficial de Stripe explica que el tax ID puede aparecer en el objeto de Checkout y guardarse en Customer. Ese dato es útil para preparar la factura, pero la selección de F1/F2 depende de la factura que se emite y de la normativa, como explica la guía F1/F2.

Valida antes de generar el registro:

• razón social o nombre;
• tax ID, país y estado de validación cuando aplique;
• dirección de facturación;
• líneas, precios y descuentos;
• tipo de IVA y moneda;
• serie y fecha de expedición;
• relación con el Customer o sesión de origen.

Stripe permite campos personalizados y tax IDs en sus facturas, pero un campo libre “NIF: …” no es una validación fiscal suficiente.

Billing y suscripciones

En una suscripción, invoice.paid puede llegar después de otros eventos y Stripe no garantiza el orden. La integración debe tratar cada invoice como una unidad idempotente y resolver qué ocurre si se paga fuera de plazo, se reintenta el cobro o se marca como incobrable.

No factures al crear la suscripción si la política exige facturar al pago. Tampoco ignores una factura recurrente porque el pedido inicial ya tuvo factura. Guarda la relación entre subscription, invoice, PaymentIntent y documento fiscal, pero asigna una sola numeración por operación que deba expedirse.

Refunds y rectificativas

La documentación de refunds de Stripe recomienda escuchar refund.created y explica que un reembolso puede estar pendiente o fallar. Para la capa fiscal:

1. identifica el PaymentIntent o charge original;
2. verifica que la factura fiscal existe;
3. calcula si es devolución total o parcial;
4. conserva líneas, impuestos y portes rectificados;
5. crea una rectificativa idempotente;
6. genera y remite el registro que corresponda;
7. procesa refund.failed o estado pendiente sin emitir una rectificativa inexistente.

Un charge.refunded no es una orden automática de anulación. La guía de anulaciones distingue operación inexistente, corrección de datos y devolución.

Connect y varias cuentas

En Stripe Connect hay que decidir qué cuenta es el obligado que expide. Los webhooks de Connect llevan la cuenta conectada y las llamadas posteriores deben hacerse en el contexto correcto. La documentación de Connect webhooks recomienda endpoint específico y separar eventos de la plataforma y de cuentas conectadas.

Un diseño multi-tenant debe fijar:

• NIF y series por cuenta que expide;
• certificado y secreto por entorno y tenant;
• cuenta Stripe asociada al registro;
• política de reembolsos y permisos;
• reconciliación cuando una cuenta se desconecta.

No uses el API key de la plataforma como sustituto de la identidad fiscal del obligado.

Pruebas mínimas

• Checkout con y sin tax ID;
• PaymentIntent fallido y luego succeeded;
• suscripción con invoice.paid retrasado;
• refund parcial y refund.failed;
• webhook repetido con firma nueva;
• eventos fuera de orden;
• test mode y live mode separados;
• cuenta conectada que deja de autorizarse;
• timeout después de reservar número fiscal.

Estado de la integración

La página pública de Stripe y la página de integraciones están en prelanzamiento. No hay una app pública o un conector de VeriFactu Fácil que este artículo pueda presentar como disponible. Las versiones de API, eventos admitidos y permisos se validarán antes de abrir la integración.