Fatturazione Stripe self-service per i clienti che hanno effettuato l'accesso

Se fatturi ai tuoi clienti con Stripe, il tuo agente può rispondere alle loro domande sulla fatturazione: mostra a un cliente che ha effettuato l'accesso le sue fatture recenti e il suo abbonamento, e gli dà un link al portale clienti di Stripe, dove può cambiare piano o metodo di pagamento, oppure disdire. L'agente non modifica mai nulla in Stripe da solo. Ogni modifica avviene nel portale di Stripe.

Questa funzione usa il tuo account Stripe, collegato con una chiave limitata che crei tu. Non ha nulla a che fare con il tuo abbonamento a intoCHAT.

Prima di iniziare

Ti servono:

• La verifica dell'identità configurata sul tuo sito, con il segreto di identità dell'agente sul tuo server.
• Il portale clienti configurato in Stripe: nella tua Stripe Dashboard, apri Settings, Billing, Customer portal, scegli che cosa possono fare lì i clienti (per esempio aggiornare i metodi di pagamento, cambiare piano o disdire) e salva. Fallo in modalità live e, se fai prove con una chiave di test, anche in modalità test.

Creare una chiave limitata

Una chiave limitata può fare solo ciò che le permetti. intoCHAT rifiuta una chiave segreta completa (sk_…).

1. Nella tua Stripe Dashboard, apri Developers, API keys e fai clic su Create restricted key.
2. Dalle un nome, per esempio "intoCHAT agent".
3. Imposta questi permessi e lascia tutto il resto su None:

1. Facoltativo: imposta anche Products su Read. L'agente indica allora il piano con il nome del prodotto; senza, usa il nickname del prezzo, oppure nessun nome.
2. Fai clic su Create key e copiala. Inizia con rk_live_, oppure con rk_test_ in modalità test.

Customer portal: Write permette a intoCHAT di aprire una sessione del portale per un cliente. Non permette a intoCHAT di modificare da solo abbonamenti o metodi di pagamento.

Collegare Stripe

1. Apri il tuo agente e vai alla scheda Actions. Il riquadro Stripe billing si trova sotto Orders.
2. Incolla la chiave in Restricted key e fai clic su Test and connect.

intoCHAT controlla la chiave leggendo l'ID di un cliente, di una fattura e di un abbonamento, e controlla se è configurato un portale clienti. Non viene mostrato nessun dato dei clienti. Se manca un permesso, il riquadro lo indica. Se il portale non è ancora configurato, il riquadro si collega e ti avvisa. Puoi controllare le chiavi fino a 10 volte in 10 minuti.

La chiave viene salvata in forma cifrata e non viene mai più mostrata. Il riquadro mostra i suoi ultimi quattro caratteri, se è una chiave live o di test, e il nome del tuo account Stripe quando la chiave può leggerlo.

• Test connection esegue lo stesso controllo con la chiave salvata.
• Replace key si collega con una nuova chiave. Se il riquadro dice che la chiave salvata non si può più leggere, il pulsante diventa Reconnect.
• Disconnect elimina la chiave salvata da intoCHAT. Per revocare la chiave stessa, eliminala anche nella tua Stripe Dashboard.

Collegare, controllare e scollegare richiede il ruolo Admin o Owner. Queste operazioni compaiono nel registro di audit come Integration connected e Integration disconnected. Trasferire l'agente a un altro account scollega Stripe.

Dire a intoCHAT chi è un visitatore

La verifica dell'identità firma solo l'ID utente del visitatore. L'email e i metadati che la tua pagina passa insieme potrebbero essere modificati da un visitatore che ha effettuato l'accesso, nel proprio browser. Quindi, prima di mostrare qualsiasi dato di fatturazione, intoCHAT ha bisogno del cliente Stripe, o dell'email, firmati dal tuo server per quell'ID utente, con lo stesso segreto di identità.

Passa uno di questi nei metadata di IntoChat.identify:

intoCHAT trova il cliente così:

1. Con stripe_customer_id e stripe_customer_hash validi, usa quel cliente, se esiste e non è stato eliminato. Non prova nient'altro.
2. Altrimenti, con un email_hash valido, cerca i clienti Stripe con esattamente quell'email (Stripe confronta le email così come sono scritte). Usa il cliente solo se ne corrisponde esattamente uno.
3. Altrimenti, non trova nulla. L'agente dice al visitatore che non ha trovato un account di fatturazione per il suo accesso e gli chiede di contattarti.

Passare l'ID cliente è la scelta affidabile. L'email funziona solo finché l'email di ogni cliente è unica nel tuo account 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),
    ],
];

Passa il risultato a IntoChat.identify nella pagina, come descritto in Verifica dell'identità. I metadati contano sui limiti di identify di 20 chiavi e 2 KB.

Che cosa possono fare i visitatori

Un visitatore che ha effettuato l'accesso può chiedere all'agente:

• Delle sue fatture. L'agente vede fino a 10 fatture recenti, dalla più recente, e può comunicare per ognuna la data, il numero, l'importo e la valuta, lo stato e i link alla pagina della fattura e al suo PDF. Le fatture in bozza non vengono mostrate.
• Del suo abbonamento. L'agente vede, per ogni abbonamento in corso, il nome del piano, lo stato, la fine del periodo attuale (la data di rinnovo, oppure la data di fine se è impostato per essere disdetto) e se viene disdetto alla fine del periodo.
• Di cambiare o disdire qualcosa. L'agente gli apre il portale clienti di Stripe: sotto la sua risposta compare un pulsante Manage billing (in italiano "Gestisci fatturazione"). Il link funziona per poco tempo; se scade, il visitatore può chiederlo di nuovo. Nel portale può fare ciò che hai consentito nelle impostazioni del portale, come cambiare piano o metodo di pagamento, aggiornare i dati di fatturazione o disdire. Quando ha finito, il link di ritorno del portale lo riporta al sito web su cui si trova la chat (il suo indirizzo senza il percorso), se usa https:// ed è uno dei tuoi domini consentiti, quando ne hai impostati. Altrimenti Stripe usa il link di ritorno predefinito delle impostazioni del portale, se ne hai impostato uno.

Un visitatore che non ha effettuato l'accesso riceve un breve messaggio che gli chiede di accedere prima al tuo sito web, nella lingua della chat. L'agente non gli chiede un'email, un numero cliente o i dati della carta.

L'agente non può disdire un abbonamento, cambiare un piano, rimborsare un pagamento o cambiare un metodo di pagamento da solo. Per tutte queste cose, apre il portale clienti.

Le ricerche di fatturazione richiedono una conversazione salvata, quindi non vengono proposte in una chat temporanea. Nel Playground, un'identità di prova funziona come una reale, quindi richiede anch'essa i metadati firmati descritti sopra; lì le ricerche sono ricerche reali nel tuo account Stripe.

Che cosa vede l'agente

Da Stripe, l'agente riceve solo i campi elencati in Che cosa possono fare i visitatori. Non riceve mai l'ID cliente, l'indirizzo email, il nome, l'indirizzo o il numero di telefono del cliente, i dati della carta o bancari, i codici fiscali o le righe delle fatture. intoCHAT copia uno per uno i campi che trasmette, quindi all'agente non arriva nient'altro.

Nel "Why this answer" della conversazione, una ricerca compare come Billing: invoices, Billing: subscription o Billing: customer portal.

Registro degli accessi

intoCHAT registra ogni ricerca di fatturazione e conserva il registro per 90 giorni. Apri Recent billing lookups nel riquadro Stripe billing per vedere le ultime 25 voci, oppure fai clic su Export CSV per averle tutte. Tutti nel tuo team possono vederlo.

Ogni voce mostra l'ora, che cosa è stato letto (le fatture, l'abbonamento, un link al portale clienti o un test della connessione), l'ID cliente Stripe e se è stato trovato tramite l'ID cliente firmato o l'email firmata, l'esito e chi: Visitor, oppure la persona del tuo account che ha testato o collegato Stripe. Il registro non contiene mai il contenuto delle fatture, importi, email o dati della carta.

Gli esiti ti aiutano a controllare la configurazione:

• No signed customer ID or email: il visitatore aveva effettuato l'accesso, ma la tua pagina non ha passato uno stripe_customer_hash o un email_hash valido.
• No customer found: la firma era valida, ma il cliente non esiste, è stato eliminato, oppure nessun cliente ha quell'email.
• Several customers with this email: più di un cliente Stripe ha quell'email, quindi non è stato mostrato nulla. Passa invece l'ID cliente.
• Stripe unavailable: non è stato possibile raggiungere Stripe, oppure la chiave ha smesso di funzionare. Esegui Test connection.

Limiti

• Un account Stripe per agente.
• L'agente legge solo i dati di fatturazione e apre il portale clienti. Che cosa un cliente può cambiare lì lo decidono le impostazioni del portale in Stripe.
• Fino a 10 fatture e 3 abbonamenti in corso per ricerca.
• Dopo un downgrade sotto Pro, la chiave resta salvata ma l'agente smette di usarla finché non passi di nuovo a un piano superiore.

Passi successivi

• Fai accedere i tuoi visitatori: Verifica dell'identità.
• Rispondi anche alle domande sugli ordini del tuo negozio: Stato degli ordini e resi.