Credits verkaufen

Credits passen zu allem, was nach Nutzung verkauft wird: Tokens, Bilder, Minuten, Suchen. Der Käufer zahlt ein Paket in Krypto; Sie verbrauchen daraus bei jedem Aufruf; gehen die Credits aus, lädt er auf seiner eigenen Seite auf. Nichts wird automatisch abgebucht – der Käufer zahlt immer selbst –, und Perly nimmt nichts von einer Aufladung.

Einrichten

1. 1

   Produkt und Pakete anlegen

   Dashboard → Products → New, dann New price → Credit pack: etwa 1.000 Credits für $10, 5.000 für $40. Oder pay.prices.create({ product, model: "credit_pack", unit_amount: 1000, credits: 1000 }).

2. 2

   Wählen, wann der Käufer vom Stand erfährt

   Auf der Produktseite, unter Credits: eine Warnschwelle, eine E-Mail an den Käufer und Any amount – das N eines Pakets, damit ein Käufer auch $25 statt nur eines festen Pakets aufladen kann.

3. 3

   Jedem Käufer einen Kunden geben

   Legen Sie pro Nutzer einen mit Ihrer eigenen ID an: pay.customers.create({ email, external_id: user.id }). Danach nimmt das SDK diese ID an.

Verbrauchen, prüfen, aufladen

import { PerlyPay, InvalidRequestError } from "perly-pay";
const pay = new PerlyPay(process.env.PERLY_PAY_SECRET_KEY);

// Before the work: enough left?
const { balance, top_up_url } = await pay.credits.balance(user.id);

// After it: spend. The same idempotencyKey never spends twice.
try {
  await pay.credits.consume(user.id, 3, { action: "chat", idempotencyKey: request.id });
} catch (e) {
  if (e instanceof InvalidRequestError && e.code === "insufficient_credits") {
    return { error: "Out of credits", topUp: await pay.credits.topUpUrl(user.id) };
  }
  throw e;
}

• Ein Kunde ist eine ID cus_…, eine E-Mail oder Ihre eigene ID für ihn (external_id). Geben Sie product an, wenn Sie Credits für mehrere Produkte verkaufen.
• Ein Verbrauch ist atomar und geht nie unter null: Zwei gleichzeitige können nicht dieselben Credits nehmen. Ein Mangel ist insufficient_credits (409), und nichts wird verbraucht.
• Übergeben Sie die ID Ihrer Anfrage als Idempotenzschlüssel. Eine Wiederholung – nach einem Timeout, einem Absturz, sogar am nächsten Tag – liefert den ersten Verbrauch zurück, statt erneut zu verbrauchen.
• action ist Ihr eigenes Label (chat, image.hd, api/search). Die Produktseite summiert den Verbrauch nach Aktion und nach Kunde.

Die Aufladeseite

top_up_url ist die eigene Seite des Käufers, immer dieselbe: Sie zeigt den Stand und Ihre Pakete im Look Ihres Checkouts und öffnet eine normale Rechnung, wenn der Käufer ein Paket wählt. Sobald sie bezahlt ist, werden die Credits einmal gutgeschrieben. Zeigen Sie den Link in Ihrer App, in Ihrer Fehlermeldung „Credits aufgebraucht“ oder senden Sie ihn – im Käuferportal gibt es auch einen Button Aufladen.

Wenn die Credits knapp werden

Beide tragen den Kunden als data.object sowie data.product und data.balance. Ist eine Schwelle gesetzt und die E-Mail an, erhält der Käufer außerdem eine E-Mail mit seinem Aufladelink – höchstens einmal am Tag. Im Testmodus gehen E-Mails nur an Ihr Team.