Stripe Payments: Configuración y metadatos

Cuando configuras la integración con Stripe Payments sin redirigir al usuario a Stripe Checkout, la información de la que disponemos para hacer la factura es más limitada. En esta sección podrás conocer cómo configurar valores por defecto y cómo usar metadatos para personalizar impuestos y datos del destinatario en cada pago.

Configuración de valores por defecto

Al configurar la integración con Stripe Payments, debes establecer los valores que se aplicarán a los pagos procesados sin Stripe Checkout. Estos valores se usan como base cuando el pago no incluye campos de metadatos que los sobreescriban.

Stripe Payments sin Checkout configuracion

Impuesto a aplicar por defecto: Puesto que únicamente recibimos el importe total con impuestos incluidos, deberás seleccionar el impuesto a aplicar. Al hacer la factura, calcularemos la base imponible a partir de dicho impuesto.
Descripción por defecto: La descripción que aparece en la línea de la factura se obtiene del campo Description del PaymentIntent en Stripe. Si usas la API, es el parámetro description que pasas al crear el PaymentIntent. Si el campo está vacío o no se proporcionó, Finseed utiliza la descripción por defecto configurada aquí.

Configuración para emitir facturas completas

Por defecto, los pagos sin Checkout generan facturas simplificadas mientras no superen el límite de importe configurado. Si necesitas emitir facturas completas (por ejemplo, en ventas B2B donde el cliente proporciona su NIF), configura tu integración para ello:

Accede a los ajustes de tu integración de Stripe en Finseed.
Busca la sección Facturas simplificadas y completas.
En Emisión de factura completa o simplificada, selecciona Emitir factura completa cuando el destinatario aporta NIF, y simplificada en el resto de casos. Si quieres factura completa en todos los pagos, selecciona Siempre emitir factura completa, una opción disponible solo en integraciones de Stripe.
Proporciona los datos fiscales del destinatario en cada pago mediante metadatos en el PaymentIntent.

Si el pago necesita factura completa y no llegan los datos fiscales del destinatario, retenemos el pago y te avisamos.

Personalización con metadatos

Si necesitas que cada pago tenga un impuesto diferente al configurado por defecto, o si quieres emitir facturas completas con los datos fiscales del destinatario, puedes enviar esta información como metadatos del PaymentIntent de Stripe.

Campos de metadatos disponibles

Al crear un PaymentIntent desde tu backend, añade los campos necesarios en el objeto metadata:

Campo de metadatos	Descripción	Obligatorio
`ev_tax_rate`	Porcentaje del impuesto como texto (ej: `"21"`, `"10"`, `"4"`, `"0"`).	Sí, junto con `ev_tax_name`
`ev_tax_name`	Nombre del impuesto (ej: `"ES IVA 21%"`, `"ES IVA 10%"`).	Sí, junto con `ev_tax_rate`
`ev_recipient_name`	Nombre o razón social del destinatario.	No
`ev_recipient_tax_id`	NIF, CIF, NIE, número de IVA intracomunitario o el número de un documento extranjero, como un pasaporte.	No
`ev_recipient_tax_id_type`	Tipo del documento indicado en `ev_recipient_tax_id`. Uno de: `es_nif`, `eu_vat`, `passport`, `official_document`, `residence_certificate`, `other`, `not_registered`.	No, pero junto con `ev_recipient_tax_id_country`
`ev_recipient_tax_id_country`	País del documento, en código ISO de dos letras (ej: `FR`).	No, pero junto con `ev_recipient_tax_id_type`
`ev_recipient_country`	Código de país ISO (ej: `ES`, `FR`, `DE`).	No
`ev_recipient_address`	Dirección (línea 1).	No
`ev_recipient_address_line_2`	Dirección (línea 2).	No
`ev_recipient_city`	Ciudad.	No
`ev_recipient_postal_code`	Código postal.	No
`ev_recipient_email`	Email del destinatario.	No

Ejemplo combinando impuesto y datos del destinatario:

const paymentIntent = await stripe.paymentIntents.create({
  amount: 12100, // 121 EUR
  currency: 'eur',
  metadata: {
    // Impuesto
    ev_tax_rate: '21',
    ev_tax_name: 'ES IVA 21%',
    // Destinatario
    ev_recipient_name: 'Acme S.L.',
    ev_recipient_tax_id: 'B12345678',
    ev_recipient_country: 'ES',
    ev_recipient_address: 'Calle Mayor 1',
    ev_recipient_city: 'Madrid',
    ev_recipient_postal_code: '28001',
    ev_recipient_email: 'billing@acme.es'
  }
})

Los campos de metadatos de Stripe tienen un límite de 500 caracteres por valor y un máximo de 50 claves por objeto.

Clientes extranjeros sin NIF ni NIE

Cuando el identificador no es un documento español, indica también su tipo y su país. El caso más habitual es un cliente extranjero sin NIF ni NIE, al que identificas en la factura con su pasaporte: ese número no sigue un formato que Finseed pueda reconocer automáticamente, así que hay que declararlo. Por ejemplo, para un cliente con dirección en España identificado con un pasaporte francés:

const paymentIntent = await stripe.paymentIntents.create({
  amount: 12100,
  currency: 'eur',
  metadata: {
    ev_tax_rate: '21',
    ev_tax_name: 'ES IVA 21%',
    ev_recipient_name: 'Jean Dupont',
    ev_recipient_tax_id: '18AB12345',
    ev_recipient_tax_id_type: 'passport',
    ev_recipient_tax_id_country: 'FR',
    ev_recipient_country: 'ES',
    ev_recipient_address: 'Calle Mayor 1',
    ev_recipient_city: 'Madrid',
    ev_recipient_postal_code: '28001'
  }
})

Si omites ev_recipient_tax_id_type y ev_recipient_tax_id_country, Finseed deduce el tipo y el país a partir del formato del identificador y del país del destinatario. Los valores de ev_recipient_tax_id_type no distinguen mayúsculas de minúsculas, y son los mismos que acepta la API de Finseed. Encontrarás la explicación completa de cada tipo en Identificador fiscal.

Nombre recomendado para el impuesto

Finseed identifica cada impuesto por la combinación exacta de nombre y porcentaje. Por ello, recomendamos usar el prefijo del país seguido del tipo de impuesto y el porcentaje: "ES IVA 21%", "ES IVA 10%", "ES IVA 4%". Esta convención tiene dos ventajas:

Coincide con los impuestos preconfigurados. Finseed crea por defecto los impuestos españoles con este formato (ES IVA 21%, ES IVA 10%, ES IVA 4%, ES IVA 0%). Si usas exactamente ese nombre, el impuesto se reconoce automáticamente y el pago se procesa sin intervención. Si usas un nombre diferente (por ejemplo, "IVA 21%"), el sistema lo tratará como un impuesto nuevo y el pedido quedará bloqueado hasta que lo clasifiques manualmente.
Evita colisiones entre países. Si en el futuro procesas pagos con impuestos de otros países al mismo porcentaje (por ejemplo, IVA francés al 20% e IVA español al 21%), el prefijo del país garantiza que cada uno se identifique y clasifique de forma independiente.

Clasificación del impuesto

La primera vez que recibamos un pago con un impuesto nuevo (una combinación de nombre y porcentaje que no hayamos visto antes), el pedido quedará bloqueado en tu panel de Finseed. Necesitarás clasificar el impuesto una única vez, indicando su tipo (IVA, exento, etc.). A partir de ese momento, todos los pagos futuros con el mismo impuesto se procesarán automáticamente. Como se indica arriba, puedes evitar este paso usando los nombres preconfigurados (ES IVA 21%, ES IVA 10%, etc.).

Comportamiento cuando la información está incompleta

Campos de impuesto

Los campos ev_tax_rate y ev_tax_name deben proporcionarse siempre juntos. Si falta uno de ellos, o el valor de ev_tax_rate no es un número válido (por ejemplo, texto, un número negativo, o un campo vacío), Finseed ignora ambos campos y utiliza el impuesto por defecto configurado en la integración. Dicho de otro modo: la personalización del impuesto solo se aplica cuando ambos campos están presentes y contienen valores válidos. En cualquier otro caso, el pago se procesa con normalidad usando el impuesto por defecto.

El valor "0" es válido para ev_tax_rate y permite crear pagos exentos de impuesto.

Datos del destinatario

Todos los campos ev_recipient_* son individualmente opcionales. Se combinan con la información que ya existe en Stripe siguiendo este orden de prioridad:

Metadatos del PaymentIntent (prioridad máxima)
Datos de facturación del cargo (datos proporcionados por el cliente en el formulario de pago)
Datos del cliente en Stripe (si existe un cliente asociado al pago)

Cada campo se resuelve de forma independiente: si proporcionas ev_recipient_name en los metadatos pero no ev_recipient_email, se usará el nombre de los metadatos y el email del cargo o del cliente. Los campos de dirección y los del identificador fiscal son las dos excepciones, y se explican más abajo. El identificador fiscal (ev_recipient_tax_id) admite además una fuente adicional: el metadato ev_recipient_tax_id del cliente de Stripe. Para el identificador fiscal, el orden de prioridad es:

Metadato ev_recipient_tax_id del PaymentIntent (prioridad máxima)
Metadato ev_recipient_tax_id del cliente de Stripe
Identificador fiscal de los datos de facturación del cargo
Identificador fiscal del cliente en Stripe

Definir ev_recipient_tax_id en los metadatos del cliente es útil para pagos recurrentes: lo configuras una vez en el cliente y se aplica a todos los pagos que genere, sin tener que incluirlo en cada PaymentIntent. El resto de campos ev_recipient_* (nombre, dirección, email, etc.) mantienen el orden de prioridad descrito arriba y no se leen de los metadatos del cliente.

Excepción para los campos de dirección: los campos de dirección (ev_recipient_address, ev_recipient_city, ev_recipient_postal_code, ev_recipient_country y ev_recipient_address_line_2) se tratan como un bloque. Si proporcionas cualquier campo de dirección en los metadatos, todos los campos de dirección se toman exclusivamente de los metadatos. Los valores de dirección del cargo o del cliente no se combinan. Si necesitas sobreescribir la dirección, asegúrate de incluir todos los campos de dirección relevantes.

Excepción para el identificador fiscal: ev_recipient_tax_id, ev_recipient_tax_id_type y ev_recipient_tax_id_country se tratan como un bloque. Solo leemos el tipo y el país del mismo objeto metadata que aporta ev_recipient_tax_id, ya sea el del PaymentIntent o el del cliente. Un tipo o país declarado sin ev_recipient_tax_id a su lado se ignora, y cuando el identificador procede del cargo o del cliente, el tipo y el país se deducen automáticamente.Además, el tipo y el país se indican juntos o se omiten los dos. Si solo indicas uno, el pedido queda bloqueado en tu panel de Finseed con un mensaje que explica el problema, antes de emitir ninguna factura. Si ev_recipient_tax_id_type contiene un valor no reconocido, lo tratamos como si no estuviera presente.

Datos insuficientes para factura completa

Cuando el criterio de emisión de tu integración determina que se debe emitir una factura completa (por ejemplo, se detectó un identificador fiscal), pero faltan datos obligatorios como el nombre, la dirección o el código postal del destinatario, el pedido quedará bloqueado en tu panel de Finseed con un error descriptivo. Podrás completar los datos faltantes manualmente o corregir los metadatos en futuros pagos.

​Configuración de valores por defecto

​Configuración para emitir facturas completas

​Personalización con metadatos

​Campos de metadatos disponibles

​Clientes extranjeros sin NIF ni NIE

​Nombre recomendado para el impuesto

​Clasificación del impuesto

​Comportamiento cuando la información está incompleta

​Campos de impuesto

​Datos del destinatario

​Datos insuficientes para factura completa

Configuración de valores por defecto

Configuración para emitir facturas completas

Personalización con metadatos

Campos de metadatos disponibles

Clientes extranjeros sin NIF ni NIE

Nombre recomendado para el impuesto

Clasificación del impuesto

Comportamiento cuando la información está incompleta

Campos de impuesto

Datos del destinatario

Datos insuficientes para factura completa