Programmieren Sie Ihre Geschäftslogik mit Skripts direkt in StripePrivate Vorschau

Mit einer Teilmenge von Typescript können Sie nutzerdefinierte Logik in Stripe erstellen und übermitteln. Mit Skripts können Sie Folgendes tun:

• Ihre eigene Logik für bestimmte Stripe-Objekte definieren
• Ihr Stripe-Konto an Ihre spezifischen Geschäftsanforderungen anpassen
• Stripe über die Standardfunktionalität hinaus erweitern

Beispielsweise können Sie Skripts verwenden, um eine nutzerdefinierte Rabattlogik für neue Gutscheine zu erstellen und diese Gutscheine dann auf Abonnements und Rechnungen anzuwenden.

Lebenszyklus eines Skripts

Sehen Sie sich den folgenden Lebenszyklus eines Skripts an, um die Verwendung von Skripts zu verstehen:

• Erstellen Sie zunächst benutzerdefinierte Logik für ein unterstütztes Anwendungsszenario.
• Im Rahmen der Skripterstellung können Sie Konfigurationswerte definieren. Dies sind Parameter, die ein/e Skriptnutzer/in beim Erstellen eines benutzerdefinierten Objekts übergibt.
• Stripe registriert Ihr Skript beim Skriptdienst, nachdem Sie es zur Überprüfung übermittelt haben.
• Anschließend können Sie das Skript beim Erstellen von Objekten wie Coupon- oder Subscription-Objekten aufrufen.

Funktionsargumente

Sie können die Argumente der Funktionen in zwei Kategorien einteilen:

Durch Autor/in definierte Werte

Sie können sich vorstellen, dass die von dem/der Autor/in definierten Werte zwei Zielgruppen haben:

• Autor/in des Skripts: Der/die Autor/in des Skripts definiert die Funktion (d. h. die eigentliche Logik) und die Eingabewerte für die Funktion. Sie können z. B. ein „percent-up-to-a-maximum“-Skript schreiben, bei dem der/die Autor/in zwei Eingaben (percent und maximum) definiert.

• Skriptnutzer/in: Nachdem der/die Skriptautor/in die Werte definiert hat, kann der/die Skriptnutzer/in die Werte für die beiden Eingaben über das Dashboard oder die API definieren (zum Beispiel 10 % Rabatt bei einem Maximum von 100 USD).

Der Autor des Skripts entscheidet, welche Teile des Skripts für den/die Nutzer/in angepasst werden sollen. Der/Die Skriptnutzer/in wendet dann seine/ihre eigenen Werte auf die anpassbaren Teile des Skripts an.

export type scriptConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};

Das SDK enthält integrierte Typen, die Sie als Teil Ihrer Konfigurationsdefinition verwenden können. Diese integrierten Typen werden mit einer entsprechenden Eingabefeld-Nutzeroberfläche im Dashboard gerendert. Wenn Sie Vorschläge für neue integrierte Typen haben, kontaktieren Sie scripts-preview@stripe.com oder unser Support-Team.

import type {PositiveMonetaryAmount, Percent} from '@stripe/scripts';

export type scriptConfiguration = {
  max_discount_amount: PositiveMonetaryAmount;
  discount_percent: Percent;
};

Konfigurationswerte verfügen über standardmäßige Schemaüberprüfungen, wenn der Skriptbenutzer versucht, die Werte festzulegen. Darüber hinaus können Sie eine nutzerdefinierte Validierung definieren, indem Sie auf die Schemavalidierungen verweisen. Wenn wir Ihr Anwendungsszenario für die Validierung nicht unterstützen, empfehlen wir, die Validierungsprüfung in Ihre Funktionsdefinition zu integrieren und scripts-preview@stripe.com zu kontaktieren.

Von Stripe definierte Werte

Stripe stellt Argumentwerte bereit, die Sie nicht anpassen können. Wir stellen die Werte zur Laufzeit der Funktion bereit. Dazu gehören in der Regel Stripe-Objekte wie die Customer- oder Line Item-Objekte. Die spezifischen Objekte variieren je nach Funktionsschnittstelle. Wenn Ihnen benötigte Daten fehlen, kontaktieren Sie scripts-preview@stripe.com.

/**
 * DiscountableLineItem data structure
 *
 * @typedef {Object} DiscountableLineItem
 * @property {MonetaryAmount} subtotal
 * @property {string | null} price_id
 * @property {number | null} quantity
 * @property {MonetaryAmount | null} unit_amount
 * @property {TimeRange} period
 * @property {Price | null} price
 */
export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  price_id?: string | null;
  quantity?: number | null;
  unit_amount?: MonetaryAmount | null;
  period: TimeRange;
  price?: Price | null;
}

Funktionslogik

Der Skriptautor definiert die Anpassung, die von der Skriptfunktionslogik verwendet wird. Alle Argumente werden „nach Wert übergeben“, d. h. Änderungen, die an den Argumentwerten innerhalb der Funktion vorgenommen werden, wirken sich nicht auf den ursprünglichen Wert außerhalb der Funktion aus.

Angemessener Umgang mit Laufzeitfehlern

In den meisten Fällen sollten Sie den Fehler abfangen und ein Ausweichverhalten festlegen. In seltenen Fällen kann es sinnvoll sein, eine Ausnahme auszulösen. Durch das Auslösen einer Ausnahme wird die gesamte Codeausführung angehalten, die dem Skript zugeordnet ist. Lösen Sie daher nur dann eine Ausnahme aus, wenn keine andere Option besteht.

Tests für Ihre Sandbox schreiben

Obwohl die Verwendung einer automatisierten Test-Suite mit Ihrer Skriptfunktion nicht vorgeschrieben ist, wird dies dennoch empfohlen. Sie können Tests für Ihre Sandbox-Umgebung schreiben, aber die veraltete Test-Modus-Umgebung unterstützt keine Skripts. Wenn Sie Hilfe benötigen, wenden Sie sich an scripts-preview@stripe.com.

Rückgabewert der Funktion

Der Rückgabewert der Funktion muss sich an die Schnittstelle halten, die je nach Anpassung variiert. Im SDK finden Sie die spezifische Schnittstellendefinition. Stellen Sie sicher, dass Ihre Funktion der Schnittstelle entspricht.