Dónde añadir los metadatos en Checkout
Añade los campos de impuesto (ev_tax_rate y ev_tax_name) al objeto metadata de la sesión de Checkout. Si la sesión no contiene ninguna de esas claves, Finseed puede leer el par de los metadatos del PaymentIntent.
Cuando añades los campos del destinatario (ev_recipient_*) al crear una sesión, colócalos en el PaymentIntent, dentro de payment_intent_data.metadata. No los añadas a los metadatos de la sesión. La referencia de pagos directos de Stripe explica cómo utilizar los mismos campos cuando no existe una sesión.
Campos de metadatos disponibles
Stripe admite hasta 500 caracteres por valor y 50 claves de metadatos por objeto.
Cliente extranjero sin identificador español
Cuando el documento no es español, recomendamos indicar también su tipo y su país. Es habitual identificar mediante el pasaporte a un cliente extranjero sin NIF ni NIE. Así evitas depender de que Finseed pueda deducir el tipo a partir del número y del país del destinatario. Este ejemplo corresponde a un cliente con dirección en España y pasaporte francés:ev_recipient_tax_id_type y ev_recipient_tax_id_country, Finseed intenta deducirlos 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 coinciden con los de la API de Finseed. La guía sobre el identificador fiscal en Stripe Billing explica cada tipo.
Marcar un pago como venta de tarjeta regalo o recarga de saldo
Esta marca indica a Finseed que el pago es la emisión de un bono polivalente. Tú decides qué pagos la llevan. Añadeev_gift_card: 'true' a los metadatos de la sesión para que Finseed emita el pago como una emisión de bono:
Si más tarde devuelves 10€, la rectificativa queda así:
Ten en cuenta estas reglas:
- Los valores admitidos son
'true'y'false'. Envía'false'para indicar de forma explícita que el pago no es una tarjeta regalo. Cualquier otro valor se ignora y facturamos el pago como una venta ordinaria. - La marca afecta a todo el pago. Emitimos todas las líneas de la sesión como emisión de bono. No mezcles una recarga de saldo con productos ordinarios en la misma sesión.
- Stripe no debe cobrar impuesto en el pago. Configura el producto de la recarga como no sujeto en Stripe Tax. Si Stripe cobra impuesto en alguna línea de un pago marcado, no procesamos el pago y te lo indicamos en el registro, en lugar de ocultar ese impuesto en una factura no sujeta.
- La sesión no debe cobrar gastos de envío. El envío es una prestación aparte y no forma parte del bono. Si la sesión cobra envío, no procesamos el pago. Cóbralo en un pago separado.
ev_tax_rateyev_tax_namese ignoran. La marca describe la operación por sí sola.
Cómo nombrar un impuesto que Finseed reconozca
Finseed identifica un impuesto mediante la combinación exacta de su nombre y su porcentaje. Utiliza primero el país, después el tipo y por último el porcentaje:ES IVA 21%, ES IVA 10% o ES IVA 4%.
Los entornos de Finseed para empresas españolas incluyen esos impuestos, además de ES IVA 0%. Si el nombre y el porcentaje coinciden, Finseed los reconoce sin pedir ninguna configuración. El prefijo del país también distingue impuestos con porcentajes parecidos, como el IVA francés al 20 % y el español al 21 %.
Finseed intenta clasificar automáticamente cualquier combinación nueva mediante el nombre, el porcentaje y el destino de la venta. Si no puede determinar su tratamiento fiscal, pausa la primera factura y te pide que lo clasifiques. Utiliza nombres como ES IVA 21% para que la configuración sea explícita y fácil de reconocer.
Cómo valida Finseed los metadatos
Campos del impuesto
ev_tax_rate y ev_tax_name deben aparecer juntos. ev_tax_rate utiliza un punto como separador decimal, admite un máximo de dos decimales y no puede superar 100. Cerca de los tipos españoles del 21 %, 10 % o 4 %, solo aceptamos el valor exacto. Un valor situado a 0,1 puntos o menos se ignora si no coincide exactamente con el tipo oficial. Así evitamos que la factura combine un tipo legal con importes calculados mediante otro porcentaje.
Si falta uno de los campos o el porcentaje contiene texto, una coma decimal, un número negativo o un valor vacío, Finseed ignora el par. El pago continúa con la siguiente fuente descrita en cómo determina Finseed el impuesto.
El valor '0' es un porcentaje válido. La clasificación del impuesto indica después si la operación está exenta o no sujeta.
Datos del destinatario
El envío de camposev_recipient_* mediante metadatos es opcional. Finseed combina el nombre y el email con la información de Stripe. El email y la dirección siguen este orden: metadatos del PaymentIntent, datos de facturación del cobro y perfil del Customer. El nombre sitúa el Checkout por delante del cobro: metadatos del PaymentIntent, nombre que el comprador escribe en Checkout, nombre del titular de la tarjeta y perfil del Customer. Puedes indicar ev_recipient_name y obtener el email del cobro o del Customer. Ten en cuenta que ev_recipient_name sustituye a la razón social que el comprador escribe en Checkout: la factura se emite a nombre del valor que envías. Si la factura debe ser completa, los datos obligatorios deben llegar desde alguna de estas fuentes.
El identificador fiscal sigue un orden propio, descrito en de dónde toma Finseed el identificador fiscal y el nombre. Guardarlo en los metadatos del Customer resulta útil para pagos recurrentes, porque se aplica sin repetirlo en cada PaymentIntent.
Los campos de dirección funcionan como un bloque. Si añades a los metadatos cualquiera de los campos ev_recipient_address, ev_recipient_city, ev_recipient_postal_code, ev_recipient_country o ev_recipient_address_line_2, Finseed obtiene de los metadatos toda la dirección. No completa los campos que falten con datos del cobro o del Customer. Incluye en los metadatos todos los campos de la dirección que quieras conservar.
Los campos del identificador fiscal también funcionan como un bloque. Finseed solo lee ev_recipient_tax_id_type y ev_recipient_tax_id_country del mismo objeto de metadatos que contiene ev_recipient_tax_id. Si ese objeto no contiene el identificador, el tipo y el país se ignoran. Cuando el identificador procede del cobro o de los tax_ids del Customer, deducimos el tipo y el país.
Cuando el mismo objeto contiene ev_recipient_tax_id, la opción más segura es indicar el tipo y el país juntos. Si omites ambos, Finseed intenta deducirlos y retiene el pedido si no puede hacerlo. Si indicas el país sin el tipo, Finseed retiene el pedido antes de emitir la factura. Si indicas solo el tipo, Finseed puede deducir el país para un NIF español, not_registered o un NIF-IVA europeo con prefijo; los demás tipos necesitan el país. Un valor de ev_recipient_tax_id_type que no reconocemos se trata como ausente.
Si la configuración exige una factura completa y faltan el nombre, la dirección o el código postal, Finseed retiene el pedido con un mensaje descriptivo. Consulta facturas simplificadas y completas.