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

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

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

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

For example, you can use scripts to create custom discount logic on new coupons, and then apply the coupons to Subscriptions and Invoices.

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

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

まず、サポートされているユースケースのカスタムロジックを作成します。
スクリプト作成の一環として、構成値を定義できます。これらは、スクリプトユーザがカスタムオブジェクトの作成時に渡すパラメータです。
レビューのためにスクリプトを送信した後、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オブジェクトやDiscountableLineItemオブジェクトなど、カスタマイズできない引数値を関数の実行時に提供します。具体的なオブジェクトは、関数インターフェイスによって異なります。必要なデータが不足している場合は、scripts-preview@stripe.comにお問い合わせください。

Stripe provided parameter example
/**
 * DiscountableLineItem data structure
 *
 * @typedef {Object} DiscountableLineItem
 * @property {MonetaryAmount} subtotal
 * @property {number | null} quantity
 * @property {TimeRange} period
 * @property {Price | null} price
 */
export interface DiscountableLineItem {
  subtotal: MonetaryAmount;
  quantity?: number | null;
  period: TimeRange;
  price?: Price | null;
}

関数ロジック

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

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

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

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

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

関数の戻り値

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

参照情報

スクリプトクーポン

注