Dónde añadir los metadatos en pagos directos
Al crear un pago directo, añade los campos al objetometadata del PaymentIntent. Los datos del impuesto (ev_tax_rate y ev_tax_name) y los del destinatario (ev_recipient_*) pueden enviarse juntos en la misma llamada a stripe.paymentIntents.create().
También puedes guardar el bloque de identificador fiscal en los metadatos del Customer de Stripe. Así, un comprador recurrente conserva sus datos cuando el pago está vinculado a ese Customer y el PaymentIntent no aporta otros valores.
La referencia de Checkout y Payment Links explica dónde colocar los mismos campos cuando sí existe una sesión.
Campos de metadatos disponibles
Stripe admite hasta 500 caracteres por valor y 50 claves de metadatos por objeto.
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. La referencia de Checkout describe qué factura genera y qué reglas se aplican. Todo eso vale igual aquí; en un pago directo solo cambia dónde escribes la clave. Añadeev_gift_card: 'true' al crear el PaymentIntent:
- Un pago marcado no necesita el impuesto predeterminado de la integración. La marca describe la operación por sí sola.
- Escribe la marca al crear el PaymentIntent, como el resto de metadatos.
- El PaymentIntent no debe declarar impuesto, gastos de envío ni propina en
amount_details. Si los declara, no procesamos el pago, igual que con una sesión de Checkout que cobra impuesto o envío.
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.
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 y utiliza el impuesto predeterminado. Ese error no retiene el pago por sí solo. Sin un impuesto predeterminado, Finseed no puede emitir la factura. Consulta impuestos en los pagos directos de Stripe.
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 según este orden: metadatos del PaymentIntent, datos de facturación del cobro y perfil del Customer. Puedes indicar ev_recipient_name y obtener el email del cobro o del Customer. Si la factura debe ser completa, los datos obligatorios deben llegar desde alguna de estas fuentes.
El identificador fiscal sigue un orden propio: ev_recipient_tax_id en los metadatos del PaymentIntent, el mismo campo en los metadatos del Customer, charge.billing_details.tax_id y, por último, los tax_ids del Customer. 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.