Stripe-Abrechnung zum Selbermachen für angemeldete Kunden

Wenn du deinen eigenen Kunden über Stripe Rechnungen stellst, kann dein Agent ihre Fragen zur Abrechnung beantworten: Er zeigt einem angemeldeten Kunden seine letzten Rechnungen und sein Abo und gibt ihm einen Link zum Kundenportal von Stripe, wo er seinen Plan oder seine Zahlungsmethode ändert oder kündigt. Der Agent selbst ändert nie etwas in Stripe. Jede Änderung passiert im eigenen Portal von Stripe.

Dafür wird dein eigenes Stripe-Konto genutzt, verbunden über einen eingeschränkten Schlüssel, den du erstellst. Mit deinem intoCHAT-Abo hat das nichts zu tun.

Bevor du anfängst

Du brauchst:

• die Identitätsprüfung, eingerichtet auf deiner Website, mit dem Identity-Secret des Agenten auf deinem Server.
• das in Stripe eingerichtete Kundenportal: Öffne in deinem Stripe-Dashboard Settings, Billing, Customer portal, wähle, was Kunden dort tun dürfen (zum Beispiel Zahlungsmethoden aktualisieren, Pläne wechseln oder kündigen), und speichere. Mach das im Live-Modus und, wenn du mit einem Testschlüssel testest, auch im Testmodus.

Einen eingeschränkten Schlüssel erstellen

Ein eingeschränkter Schlüssel kann nur, was du ihm erlaubst. intoCHAT lehnt einen vollständigen geheimen Schlüssel (sk_…) ab.

1. Öffne in deinem Stripe-Dashboard Developers, API keys und klicke auf Create restricted key.
2. Gib ihm einen Namen, zum Beispiel „intoCHAT agent“.
3. Setze diese Berechtigungen und lass alles andere auf None:

1. Optional: Setze auch Products auf Read. Der Agent nennt den Plan dann mit seinem Produktnamen; ohne diese Berechtigung nutzt er den Spitznamen des Preises oder gar keinen Namen.
2. Klicke auf Create key und kopiere ihn. Er beginnt mit rk_live_, im Testmodus mit rk_test_.

Customer portal: Write erlaubt intoCHAT, eine Portal-Sitzung für einen Kunden zu öffnen. Abos oder Zahlungsmethoden selbst ändern kann intoCHAT damit nicht.

Stripe verbinden

1. Öffne deinen Agenten und wechsle zum Tab Actions. Die Karte Stripe billing steht unter Orders.
2. Füge den Schlüssel unter Restricted key ein und klicke auf Test and connect.

intoCHAT prüft den Schlüssel, indem es die ID eines Kunden, einer Rechnung und eines Abos liest, und prüft, ob ein Kundenportal eingerichtet ist. Es werden keine Kundendaten angezeigt. Fehlt eine Berechtigung, nennt die Karte sie. Ist das Portal noch nicht eingerichtet, verbindet die Karte trotzdem und warnt dich. Du kannst Schlüssel bis zu 10-mal in 10 Minuten prüfen.

Der Schlüssel wird verschlüsselt gespeichert und nie wieder angezeigt. Die Karte zeigt seine letzten vier Zeichen, ob es ein Live- oder ein Testschlüssel ist, und den Namen deines Stripe-Kontos, wenn der Schlüssel ihn lesen kann.

• Test connection führt dieselbe Prüfung mit dem gespeicherten Schlüssel aus.
• Replace key verbindet mit einem neuen Schlüssel. Meldet die Karte, dass der gespeicherte Schlüssel nicht mehr gelesen werden kann, heißt der Button Reconnect.
• Disconnect löscht den gespeicherten Schlüssel aus intoCHAT. Um den Schlüssel selbst zu widerrufen, lösch ihn auch in deinem Stripe-Dashboard.

Verbinden, Testen und Trennen erfordern die Rolle Admin oder Owner. Sie erscheinen im Audit-Log als Integration connected und Integration disconnected. Wird der Agent an ein anderes Konto übertragen, wird Stripe getrennt.

intoCHAT sagen, welcher Kunde ein Besucher ist

Die Identitätsprüfung signiert nur die User-ID des Besuchers. Die E-Mail-Adresse und die Metadaten, die deine Seite daneben übergibt, könnte ein angemeldeter Besucher in seinem eigenen Browser ändern. Bevor intoCHAT Abrechnungsdaten zeigt, braucht es deshalb den Stripe-Kunden oder die E-Mail-Adresse, von deinem Server für diese User-ID signiert, mit demselben Identity-Secret.

Übergib eines davon in den metadata von IntoChat.identify:

So findet intoCHAT den Kunden:

1. Mit gültiger stripe_customer_id und gültigem stripe_customer_hash nutzt es diesen Kunden, sofern er existiert und nicht gelöscht ist. Sonst wird nichts versucht.
2. Andernfalls sucht es mit einem gültigen email_hash nach Stripe-Kunden mit genau dieser E-Mail-Adresse (Stripe vergleicht E-Mail-Adressen so, wie sie geschrieben sind). Es nutzt den Kunden nur, wenn genau einer passt.
3. Andernfalls findet es nichts. Der Agent sagt dem Besucher, dass er zu seiner Anmeldung kein Abrechnungskonto finden konnte, und bittet ihn, sich bei dir zu melden.

Die Kunden-ID zu übergeben ist die zuverlässige Wahl. Die E-Mail-Adresse funktioniert nur, solange die E-Mail-Adresse jedes Kunden in deinem Stripe-Konto eindeutig ist.

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),
    ],
];

Übergib das Ergebnis auf der Seite an IntoChat.identify, wie unter Identitätsprüfung beschrieben. Die Metadaten zählen auf die Limits von identify, 20 Schlüssel und 2 KB.

Was Besucher tun können

Ein angemeldeter Besucher kann den Agenten fragen:

• Nach seinen Rechnungen. Der Agent sieht bis zu 10 aktuelle Rechnungen, die neueste zuerst, und kann für jede Datum, Nummer, Betrag und Währung, Status sowie Links zur Rechnungsseite und zu ihrem PDF nennen. Rechnungsentwürfe werden nicht gezeigt.
• Nach seinem Abo. Der Agent sieht für jedes aktuelle Abo den Namen des Plans, den Status, das Ende des aktuellen Zeitraums (das Verlängerungsdatum oder, wenn es zur Kündigung vorgemerkt ist, das Enddatum) und ob es zum Ende des Zeitraums gekündigt wird.
• Etwas zu ändern oder zu kündigen. Der Agent öffnet für ihn das Kundenportal von Stripe: Unter seiner Antwort erscheint ein Button Manage billing. Der Link funktioniert nur kurze Zeit; läuft er ab, kann der Besucher erneut fragen. Im Portal kann er tun, was du in deinen Portal-Einstellungen erlaubt hast, etwa seinen Plan oder seine Zahlungsmethode ändern, Rechnungsangaben aktualisieren oder kündigen. Ist er fertig, bringt ihn der Rücklink des Portals zurück zur Website, auf der der Chat läuft (ihre Adresse ohne Pfad), sofern sie https:// nutzt und, falls du welche festgelegt hast, zu deinen erlaubten Domains gehört. Andernfalls nutzt Stripe den Standard-Rücklink aus deinen Portal-Einstellungen, falls du einen festgelegt hast.

Ein Besucher, der nicht angemeldet ist, bekommt eine kurze Nachricht in der Sprache des Chats, die ihn bittet, sich zuerst auf deiner Website anzumelden. Der Agent fragt ihn nicht nach einer E-Mail-Adresse, einer Kundennummer oder Kartendaten.

Der Agent kann ein Abo nicht selbst kündigen, keinen Plan ändern, keine Zahlung erstatten und keine Zahlungsmethode ändern. Für all das öffnet er das Kundenportal.

Abfragen zur Abrechnung brauchen ein gespeichertes Gespräch, deshalb werden sie in einem temporären Chat nicht angeboten. Im Playground funktioniert eine Testidentität wie eine echte, sie braucht also ebenfalls die oben beschriebenen signierten Metadaten; Abfragen dort sind echte Abfragen in deinem Stripe-Konto.

Was der Agent sieht

Von Stripe bekommt der Agent nur die Felder, die unter Was Besucher tun können aufgeführt sind. Er bekommt nie die Kunden-ID, die E-Mail-Adresse, Name, Adresse oder Telefonnummer des Kunden, Karten- oder Bankdaten, Steuernummern oder Rechnungspositionen. intoCHAT kopiert die Felder, die es weitergibt, einzeln, sodass nichts anderes beim Agenten ankommt.

Unter „Why this answer“ im Gespräch erscheint eine Abfrage als Billing: invoices, Billing: subscription oder Billing: customer portal.

Zugriffsprotokoll

intoCHAT protokolliert jede Abfrage zur Abrechnung und bewahrt das Protokoll 90 Tage auf. Öffne Recent billing lookups in der Karte Stripe billing, um die letzten 25 Einträge zu sehen, oder klicke auf Export CSV für alle. Jeder in deinem Team kann es sehen.

Jeder Eintrag zeigt die Zeit, was gelesen wurde (Rechnungen, das Abo, ein Kundenportal-Link oder ein Verbindungstest), die Stripe-Kunden-ID und ob sie über die signierte Kunden-ID oder die signierte E-Mail-Adresse gefunden wurde, das Ergebnis und wer: Visitor oder die Person in deinem Konto, die Stripe getestet oder verbunden hat. Das Protokoll enthält nie Rechnungsinhalte, Beträge, E-Mail-Adressen oder Kartendaten.

Die Ergebnisse helfen dir, deine Einrichtung zu prüfen:

• No signed customer ID or email: Der Besucher war angemeldet, aber deine Seite hat keinen gültigen stripe_customer_hash oder email_hash übergeben.
• No customer found: Die Signatur war gültig, aber der Kunde existiert nicht, wurde gelöscht, oder kein Kunde hat diese E-Mail-Adresse.
• Several customers with this email: Mehr als ein Stripe-Kunde hat diese E-Mail-Adresse, deshalb wurde nichts gezeigt. Übergib stattdessen die Kunden-ID.
• Stripe unavailable: Stripe war nicht erreichbar, oder der Schlüssel funktioniert nicht mehr. Führe Test connection aus.

Grenzen

• Ein Stripe-Konto pro Agent.
• Der Agent liest nur Abrechnungsdaten und öffnet das Kundenportal. Was ein Kunde dort ändern kann, bestimmen deine Portal-Einstellungen in Stripe.
• Bis zu 10 Rechnungen und 3 aktuelle Abos pro Abfrage.
• Nach einem Downgrade unter Pro bleibt der Schlüssel gespeichert, aber der Agent nutzt ihn nicht mehr, bis du wieder upgradest.

Wie es weitergeht

• Deine Besucher anmelden: Identitätsprüfung.
• Auch Fragen zu Bestellungen aus deinem Shop beantworten: Bestellstatus und Rücksendungen.