スクリプトを使用してビジネスロジックを Stripe 上で直接プログラミングする非公開プレビュー

TypeScript を使用してカスタムロジックを作成し、Stripe の機能を拡張します。

Typescript のサブセットを使用すると、Stripe でカスタムロジックを記述して送信できます。スクリプトを使用して、次のことが可能になります。

特定の Stripe オブジェクトに対して独自のロジックを定義する
特定のビジネスニーズに合わせて Stripe アカウントをカスタマイズする
Stripe を標準機能を超えて拡張する

たとえば、スクリプトを使用して新しいクーポンにカスタム割引ロジックを作成して、そのクーポンをサブスクリプションと請求書に適用できます。

スクリプトのライフサイクル

スクリプトの使用方法については、次のスクリプトのライフサイクルを参照してください。

まず、サポートされているユースケースのカスタムロジックを作成します。
スクリプト作成の一環として、構成値を定義できます。これらは、スクリプトユーザがカスタムオブジェクトの作成時に渡すパラメータです。
レビューのためにスクリプトを送信した後、Stripe はそのスクリプトをスクリプトサービスに登録します。
その後、Coupon オブジェクトや Subscription オブジェクトなどのオブジェクトを作成するときにスクリプトを呼び出すことができます。

関数の引数

関数の引数は、次の 2 つのカテゴリーに分類できます。

作成者が定義した値

作成者が定義した値は、次の 2 つを対象としている考えることができます。

スクリプト作成者: スクリプト作成者は、関数 (つまり、実際のロジック) と関数への入力値を定義します。たとえば、スクリプト作成者が 2 つの入力値 (percent と maximum) を定義する “percent-up-to-a-maximum” スクリプトを作成できます。
スクリプトユーザー: スクリプト作成者が値を定義した後、スクリプトユーザーはダッシュボードまたは API を使用して 2 つの入力値を定義できます (たとえば、最大 100 USD を 10% オフにするなど)。

スクリプト作成者は、スクリプトのどの部分をスクリプトユーザー向けにカスタマイズ可能にするかを決定します。その後、スクリプトユーザーは、スクリプトのカスタマイズ可能な部分に独自の値を適用します。

script configuration-1
export type scriptConfiguration = {
  max_discount_amount: {
    amount: number;
    currency: string;
  },
  discount_percent: number;
};

SDK には、構成定義の一部として使用できる組み込み型が用意されています。これらの組み込み型は、ダッシュボードの関連する入力フィールド UI でレンダリングされます。新しい組み込み型に関する提案がありましたら、scripts-preview@stripe.com またはサポートチームまでご連絡ください。

script configuration-2
import type {PositiveMonetaryAmount, Percent} from '@stripe/scripts';

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

構成値には、スクリプトユーザーが値を設定しようとしたときのデフォルトのスキーマ検証があります。さらに、スキーマ検証を参照してカスタム検証を定義できます。検証のユースケースをサポートできない場合は、検証チェックを関数定義に組み込んで、scripts-preview@stripe.com に問い合わせることをお勧めします。

Stripe 定義の値

Stripe は引数値を提供しますが、カスタマイズすることはできません。関数の実行時に値が提供されます。値には通常、Customer オブジェクトや Line Item オブジェクトなどの Stripe オブジェクトが含まれます。具体的なオブジェクトは、関数インターフェイスによって異なります。必要なデータが見つからない場合は、scripts-preview@stripe.com までお問い合わせください。

Stripe provided parameter example
/**
 * 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;
}

関数ロジック

スクリプト作成者は、スクリプト関数ロジックで使用されるカスタマイズを定義します。すべての引数は「値渡し」であり、関数内で引数値を変更しても、関数外の元の値には影響しません。

実行時エラーを適切に処理する

ほとんどの場合、エラーをキャッチし、フォールバック動作を行います。まれに、例外をスローすることがあります。例外をスローすると、スクリプトに関連付けられているコードの実行全体が停止するため、他のオプションが存在しない場合にのみ例外をスローします。

サンドボックスに対するテストを記述する

スクリプト関数で自動テストスイートを使用することは必須ではありませんが、Stripe では推奨されています。サンドボックス環境に対してテストを記述できますが、レガシーのテストモード環境ではスクリプトはサポートされていません。ガイダンスが必要な場合は、scripts-preview@stripe.com までお問い合わせください。

関数の戻り値

関数の戻り値は、カスタマイズによって異なるインターフェイスに従う必要があります。特定のインターフェイス定義については SDK を参照し、関数がインターフェイスに準拠していることを確認します。

参照情報

スクリプトクーポン