Saltar al contenido principal
Ingresos7 min de lectura

Cómo pasar los parámetros UTM y la visita a Stripe Checkout

Las etiquetas UTM no sobreviven a la redirección a checkout.stripe.com. Cómo llevar la fuente en client_reference_id y metadata, leerla en el webhook y por qué es más sencillo llevar la visita.

Vicente TorresFundador de Vero

Alguien llega a tu web desde un enlace de la newsletter con su utm_source, lee los precios y pulsa comprar. El navegador se va a checkout.stripe.com o a buy.stripe.com, el cliente paga y el pago que ves en Stripe no sabe que hubo una newsletter de por medio. Si quieres ingresos por fuente, la fuente tiene que cruzar esa redirección junto al cliente. Stripe te da dos campos para eso, client_reference_id y metadata, y un webhook que te los devuelve. Aquí verás cómo usar cada uno con una Checkout Session que creas tú y con un Payment Link, cómo leerlos en el webhook, renovaciones incluidas, y cómo el módulo checkout y el webhook de Vero hacen el mismo trabajo sin que escribas ese código.

¿Por qué se pierden los parámetros UTM en Stripe Checkout?

Los parámetros UTM viven en la URL de la página a la que llegó el visitante. No son algo del visitante. En cuanto abre otra página, las etiquetas desaparecen de la barra de direcciones, salvo que tu propio código las leyera y las guardara en algún sitio.

El checkout lo empeora. Stripe Checkout corre en el dominio de Stripe, así que la página de pago nunca ve tu URL de entrada, y el único referrer que recibe es tu propia página de precios. Stripe guarda lo que le envías al crear la sesión y nada más. Si no le mandas nada sobre la fuente, el pago llega sin ella.

Así que el trabajo tiene dos mitades. Conservar la fuente, o algo que apunte a ella, hasta que el cliente pulse comprar. Y después meterla en un campo que Stripe guarde con el pago y devuelva en el webhook.

Lleva la fuente en una Checkout Session creada por ti

Si tu servidor crea la Checkout Session, le pones dos campos. client_reference_id admite un texto, que Stripe describe como una referencia para cuadrar la sesión con tus propios sistemas, por ejemplo un id de cliente o de carrito. metadata admite pares clave-valor: hasta 50 claves, cada clave de hasta 40 caracteres y cada valor de hasta 500. Los dos aparecen en la referencia para crear una Checkout Session.

Para las etiquetas UTM, lo natural es metadata, con una clave por etiqueta: utm_source con el valor newsletter, utm_medium con email y utm_campaign con el nombre del envío. client_reference_id guarda un solo valor, así que encaja mejor con un id que con cinco etiquetas.

Si es una suscripción, pon también las mismas claves en subscription_data.metadata. Stripe no copia metadata entre objetos relacionados por su cuenta, así que la de la sesión se queda en la sesión. Lo que pongas en subscription_data.metadata se guarda en la suscripción, y cada factura que esta genera recibe una copia en parent.subscription_details.metadata. La guía de metadata de Stripe detalla qué objetos se copian a cuáles. Esa copia es la que permite que una renovación, seis meses después, siga diciendo de dónde vino el cliente.

Un Payment Link es una URL fija en buy.stripe.com. No hay ninguna llamada al servidor en la que puedas poner metadata para cada cliente, así que lo que puedes pasar son parámetros en la URL. Stripe documenta dos tipos en su página de parámetros de URL de los Payment Links.

El primero son los códigos UTM: utm_source, utm_medium, utm_campaign, utm_term y utm_content añadidos al enlace. Según Stripe, vuelven en tu URL de redirección cuando el cliente paga, si el enlace está configurado para redirigir al confirmar. Así tu página de gracias recibe las etiquetas. Pero no llegan al webhook con el que registrarías la venta.

El segundo es client_reference_id. Añádelo al enlace y Stripe lo envía en el webhook checkout.session.completed. El valor admite letras, números, guiones y guiones bajos, hasta 200 caracteres. Uno no válido se descarta sin ningún error, así que un valor mal formado falla sin avisar.

El problema es que un Payment Link es la misma URL para todo el mundo. Un client_reference_id escrito en el enlace es igual para todos los compradores, así que como mucho nombra una campaña, nunca una visita. Para llevar algo propio de cada visitante, un script tiene que reescribir el enlace en el momento del clic.

Lee la fuente en checkout.session.completed

Cuando termina el pago, Stripe envía checkout.session.completed a tu endpoint de webhook. El evento trae la Checkout Session con client_reference_id y metadata tal como los pusiste, además de los importes. Comprueba la cabecera stripe-signature con el secreto de firma de tu endpoint antes de fiarte de nada, y después registra la venta con su fuente.

Hay dos detalles que pillan a mucha gente. Una sesión completada no siempre está pagada: con un método diferido como el adeudo SEPA, payment_status todavía no está en paid, y el cobro se confirma más tarde con checkout.session.async_payment_succeeded. La guía de cumplimiento de pedidos de Stripe cubre los dos eventos.

Y las renovaciones nunca pasan por el checkout. Llegan como invoice.paid, y la fuente solo está en parent.subscription_details.metadata de la factura si pusiste subscription_data.metadata al crear la suscripción. Sáltate ese paso y cada renovación te llegará sin fuente.

Lleva la visita, no las etiquetas

Todo lo anterior da por hecho que las etiquetas siguen a mano cuando el cliente pulsa comprar. Casi nunca es así: el visitante entró por un artículo del blog, leyó tres páginas y luego abrió los precios. Mantener vivas cinco etiquetas entre esas páginas obliga a escribirlas en el dispositivo, en una cookie o en localStorage, y eso te devuelve a la cuestión del consentimiento que querías evitar.

La alternativa es llevar un único id que señale la visita y dejar las etiquetas donde se registraron: en tu analítica, en el primer evento de esa visita. El checkout lleva el id, el webhook lo devuelve y el servidor consulta cómo empezó esa visita. Nada de la fuente tiene que sobrevivir en el navegador. Cómo atribuir ingresos sin cookies explica por qué la visita que se lleva el mérito es la que trajo al cliente y no la página de checkout.

Lo que el módulo checkout y el webhook de Vero hacen por ti

El módulo checkout del tracker se encarga de la parte del Payment Link. Al hacer clic en un enlace de buy.stripe.com añade client_reference_id con el id de sesión. El resto del enlace queda como estaba, nunca sustituye un valor que la página ya puso y no envía ningún evento. Suma 319 B con gzip a los 1,2 KB del núcleo.

Si tu servidor crea la Checkout Session, lee el id con window.vero.session() en la página, envíalo a tu servidor con la petición y ponlo como client_reference_id o como metadata.vero. Si hay prueba gratuita, ponlo también en subscription_data.metadata.vero, que lleva cada factura de esa suscripción. El módulo no reconoce un checkout en tu propio dominio, así que para ese caso el camino es este.

En Vero, pegas una URL de webhook en Stripe y eliges cuatro eventos: checkout.session.completed, checkout.session.async_payment_succeeded, invoice.paid y charge.refunded. Vero comprueba cada firma y rechaza la que se desvíe más de 5 minutos, lee la visita de client_reference_id, de metadata.vero o del metadata.vero de la suscripción, y guarda la venta sin impuestos bajo la fuente de esa visita. Un id solo cuenta si señala una visita de ese sitio. La página de la integración con Stripe tiene los cuatro pasos, y la documentación recoge cada campo que lee Vero.

Una renovación sin visita hereda la fuente del primer pago atribuido del cliente, y un reembolso se resta de la fuente de la venta que devuelve. Todos los planes guardan la venta y muestran el total. Qué fuente la trajo forma parte de la atribución de ingresos en Pro.

¿Cuándo se sigue perdiendo la fuente?

Una venta llega sin fuente cuando nada señaló una visita: un Payment Link pegado en un email o en un chat, donde el tracker nunca se ejecutó; una sesión que tu servidor creó sin el id; un comprador cuyo bloqueador de anuncios paró el script. La venta sigue contando en tus ingresos, fuera de cualquier fuente.

Si tu Payment Link ya lleva un client_reference_id tuyo, el módulo lo respeta, y esa venta no puede llevar la visita. En una sesión que creas tú, pon tu id en client_reference_id y la visita en metadata.vero para conservar los dos.

Una compra en modo de prueba se recibe y no se cuenta. Sirve para comprobar que la URL y el secreto funcionan sin sumar nada a tus ingresos. La guía paso a paso recorre una primera venta de principio a fin.

¿Un término que no conoces? Consulta el glosario

Vicente Torres
Vero lo construye una persona en España. Leo cada entrada de la lista y elijo yo las cuentas de la beta.
Vicente Torres, Fundador de Vero LinkedIn
Beta elegida a mano, lista abierta

Pide plaza en la beta.

Cualquiera puede apuntarse a la lista. Las cuentas que elegimos tienen Pro gratis durante toda la beta.

Al apuntarte aceptas recibir avisos del lanzamiento y nuestra Política de Privacidad.

Ver la demo