Autoservicio de facturación de Stripe para clientes con sesión iniciada

Si facturas a tus propios clientes con Stripe, tu agente puede responder a sus preguntas de facturación: muestra a un cliente con sesión iniciada sus facturas recientes y su suscripción, y le da un enlace al portal de clientes de Stripe, donde cambia de plan o de método de pago, o cancela. El agente nunca cambia nada en Stripe por sí mismo. Todos los cambios se hacen en el propio portal de Stripe.

Esto usa tu propia cuenta de Stripe, conectada con una clave restringida que creas tú. No tiene nada que ver con tu suscripción a intoCHAT.

Antes de empezar

Necesitas:

• La verificación de identidad configurada en tu web, con el secreto de identidad del agente en tu servidor.
• El portal de clientes configurado en Stripe: en tu Stripe Dashboard, abre Settings, Billing, Customer portal, elige qué pueden hacer allí los clientes (por ejemplo, actualizar métodos de pago, cambiar de plan o cancelar) y guarda. Hazlo en modo live y, si pruebas con una clave de prueba, también en modo de prueba.

Crear una clave restringida

Una clave restringida solo puede hacer lo que le permitas. intoCHAT rechaza una clave secreta completa (sk_…).

1. En tu Stripe Dashboard, abre Developers, API keys y haz clic en Create restricted key.
2. Ponle un nombre, por ejemplo «intoCHAT agent».
3. Define estos permisos y deja todo lo demás en None:

1. Opcional: pon también Products en Read. Así el agente nombra el plan por el nombre de su producto; sin ello, usa el apodo del precio, o ningún nombre.
2. Haz clic en Create key y cópiala. Empieza por rk_live_, o por rk_test_ en modo de prueba.

Customer portal: Write permite a intoCHAT abrir una sesión del portal para un cliente. No permite a intoCHAT cambiar por sí mismo suscripciones ni métodos de pago.

Conectar Stripe

1. Abre tu agente y ve a la pestaña Actions. La tarjeta Stripe billing está debajo de Orders.
2. Pega la clave en Restricted key y haz clic en Test and connect.

intoCHAT comprueba la clave leyendo el ID de un cliente, de una factura y de una suscripción, y comprueba si hay un portal de clientes configurado. No se muestra ningún dato de clientes. Si falta un permiso, la tarjeta lo nombra. Si el portal todavía no está configurado, la tarjeta se conecta y te avisa. Puedes comprobar claves hasta 10 veces en 10 minutos.

La clave se guarda cifrada y nunca se vuelve a mostrar. La tarjeta muestra sus cuatro últimos caracteres, si es una clave live o de prueba, y el nombre de tu cuenta de Stripe cuando la clave puede leerlo.

• Test connection hace la misma comprobación con la clave guardada.
• Replace key conecta con una clave nueva. Si la tarjeta dice que la clave guardada ya no se puede leer, el botón dice Reconnect.
• Disconnect borra la clave guardada de intoCHAT. Para revocar la propia clave, bórrala también en tu Stripe Dashboard.

Para conectar, comprobar y desconectar hace falta el rol Admin u Owner. Aparecen en el registro de auditoría como Integration connected e Integration disconnected. Transferir el agente a otra cuenta desconecta Stripe.

Decirle a intoCHAT qué cliente es un visitante

La verificación de identidad solo firma el ID de usuario del visitante. El correo y los metadatos que tu página pasa junto a él los podría cambiar un visitante con sesión iniciada en su propio navegador. Por eso, antes de mostrar ningún dato de facturación, intoCHAT necesita el cliente de Stripe, o el correo, firmado por tu servidor para ese ID de usuario, con el mismo secreto de identidad.

Pasa uno de estos en los metadata de IntoChat.identify:

intoCHAT encuentra el cliente así:

1. Con un stripe_customer_id y un stripe_customer_hash válidos, usa ese cliente, si existe y no está eliminado. No se prueba nada más.
2. Si no, con un email_hash válido, busca clientes de Stripe con exactamente ese correo (Stripe compara los correos tal como están escritos). Solo usa el cliente si coincide exactamente uno.
3. Si no, no encuentra nada. El agente dice al visitante que no ha encontrado una cuenta de facturación para su inicio de sesión y le pide que contacte contigo.

Pasar el ID de cliente es la opción fiable. El correo solo funciona mientras el correo de cada cliente sea único en tu cuenta de Stripe.

Node.js:

import { createHmac } from "node:crypto";

const secret = process.env.INTOCHAT_IDENTITY_SECRET;
const sign = (text) => createHmac("sha256", secret).update(text).digest("hex");

const userId = String(user.id);
const identity = {
  userId,
  userHash: sign(userId),
  email: user.email,
  metadata: {
    stripe_customer_id: user.stripeCustomerId,
    stripe_customer_hash: sign(`${userId}:${user.stripeCustomerId}`),
  },
};

PHP:

<?php
$secret = getenv('INTOCHAT_IDENTITY_SECRET');
$userId = (string) $user->id;
$identity = [
    'userId' => $userId,
    'userHash' => hash_hmac('sha256', $userId, $secret),
    'metadata' => [
        'stripe_customer_id' => $user->stripe_customer_id,
        'stripe_customer_hash' => hash_hmac('sha256', $userId . ':' . $user->stripe_customer_id, $secret),
    ],
];

Pasa el resultado a IntoChat.identify en la página, como se explica en Verificación de identidad. Los metadatos cuentan para los límites de identify de 20 claves y 2 KB.

Qué pueden hacer los visitantes

Un visitante con sesión iniciada puede preguntar al agente:

• Por sus facturas. El agente ve hasta 10 facturas recientes, de la más reciente a la más antigua, y puede compartir de cada una la fecha, el número, el importe y la moneda, el estado, y los enlaces a la página de la factura y a su PDF. Las facturas en borrador no se muestran.
• Por su suscripción. El agente ve de cada suscripción actual el nombre del plan, el estado, el final del periodo actual (la fecha de renovación, o la fecha de fin si está configurada para cancelarse) y si se cancela al final del periodo.
• Para cambiar o cancelar algo. El agente le abre el portal de clientes de Stripe: aparece un botón Manage billing bajo su respuesta. El enlace funciona durante poco tiempo; si caduca, el visitante puede volver a pedirlo. En el portal puede hacer lo que permitiste en los ajustes de tu portal, como cambiar de plan o de método de pago, actualizar los datos de facturación o cancelar. Cuando termina, el enlace de vuelta del portal le lleva a la web en la que está el chat (su dirección sin la ruta), si usa https:// y es uno de tus dominios permitidos cuando has definido alguno. Si no, Stripe usa el enlace de vuelta por defecto de los ajustes de tu portal, si definiste uno.

Un visitante que no ha iniciado sesión recibe un mensaje breve que le pide que inicie sesión primero en tu web, en el idioma del chat. El agente no le pide un correo, un número de cliente ni datos de tarjeta.

El agente no puede cancelar una suscripción, cambiar un plan, reembolsar un pago ni cambiar un método de pago por sí mismo. Para cualquiera de estas cosas, abre el portal de clientes.

Las consultas de facturación necesitan una conversación guardada, así que no se ofrecen en un chat temporal. En el Playground, una identidad de prueba funciona como una real, así que también necesita los metadatos firmados de arriba; las consultas que se hacen allí son consultas reales en tu cuenta de Stripe.

Qué ve el agente

De Stripe, el agente solo recibe los campos que se indican en Qué pueden hacer los visitantes. Nunca recibe el ID de cliente, la dirección de correo, el nombre, la dirección postal ni el teléfono del cliente, los datos de tarjeta o bancarios, los números de identificación fiscal ni las líneas de las facturas. intoCHAT copia uno a uno los campos que pasa, así que nada más llega al agente.

En «Why this answer» de la conversación, una consulta aparece como Billing: invoices, Billing: subscription o Billing: customer portal.

Registro de accesos

intoCHAT registra cada consulta de facturación y conserva el registro durante 90 días. Abre Recent billing lookups en la tarjeta Stripe billing para ver las 25 últimas entradas, o haz clic en Export CSV para todas. Todo tu equipo puede verlo.

Cada entrada muestra la hora, qué se leyó (facturas, la suscripción, un enlace al portal de clientes o una prueba de conexión), el ID de cliente de Stripe y si se encontró por el ID de cliente firmado o por el correo firmado, el resultado y quién: Visitor, o la persona de tu cuenta que probó o conectó Stripe. El registro nunca contiene el contenido de las facturas, importes, correos ni datos de tarjeta.

Los resultados te ayudan a comprobar tu configuración:

• No signed customer ID or email: el visitante tenía la sesión iniciada, pero tu página no pasó un stripe_customer_hash o un email_hash válido.
• No customer found: la firma era válida, pero el cliente no existe, se eliminó o ningún cliente tiene ese correo.
• Several customers with this email: más de un cliente de Stripe tiene ese correo, así que no se mostró nada. Pasa el ID de cliente en su lugar.
• Stripe unavailable: no se pudo contactar con Stripe, o la clave dejó de funcionar. Usa Test connection.

Límites

• Una cuenta de Stripe por agente.
• El agente solo lee datos de facturación y abre el portal de clientes. Lo que un cliente puede cambiar allí lo deciden los ajustes de tu portal en Stripe.
• Hasta 10 facturas y 3 suscripciones actuales por consulta.
• Después de bajar a un plan inferior a Pro, la clave sigue guardada, pero el agente deja de usarla hasta que vuelvas a mejorar de plan.

Siguientes pasos

• Inicia la sesión de tus visitantes: Verificación de identidad.
• Responde también a preguntas sobre pedidos de tu tienda: Estado de pedidos y devoluciones.