JavaScript API リファレンス

API メソッド

• StripeTerminal.create()
• discoverReaders()
• connectReader()
• disconnectReader()
• getConnectionStatus()
• getPaymentStatus()
• clearCachedCredentials()
• collectPaymentMethod()
• cancelCollectPaymentMethod()
• processPayment()
• cancelProcessPayment()
• collectSetupIntentPaymentMethod()
• cancelCollectSetupIntentPaymentMethod()
• confirmSetupIntent()
• cancelConfirmSetupIntent()
• readReusableCard()
• cancelReadReusableCard()
• setReaderDisplay()
• clearReaderDisplay()
• setSimulatorConfiguration()
• getSimulatorConfiguration()
• collectRefundPaymentMethod()
• cancelCollectRefundPaymentMethod()
• processRefund()
• cancelProcessRefund()
• collectInputs()
• cancelCollectInputs()

StripeTerminal.create([options])

指定のオプションを使用して、StripeTerminal のインスタンスを作成します。

リーダーの動作設定

現在、動作設定のオプションは、以下の 1 つのみです。

discoverReaders([options])

指定のオプションを使用して、リーダーの検出を開始します。

以下のフィールドを持つオブジェクトで解決される、Promiseを返します。

• discoveredReaders: 検出された Reader (リーダー) オブジェクトのリスト (コマンドが成功した場合)。
• error: エラー (コマンドが失敗した場合)。

connectReader(reader, connectOptions)

指定されたオプションを使用して、指定されたリーダーへの接続を試みます。

以下のフィールドを持つオブジェクトで解決される、Promiseを返します。

• reader: 接続された Reader (リーダー) (コマンドが成功した場合)。
• error: エラー (コマンドが失敗した場合)。

disconnectReader()

接続されたリーダーから切断します。

getConnectionStatus()

現在の接続ステータスを返します。

ConnectionStatus の値には、connecting、connected、not_connected があります。

getPaymentStatus()

リーダーの支払いステータスを返します。

PaymentStatus の値には、not_ready、ready、waiting_for_input、processing があります。

clearCachedCredentials()

現在の ConnectionToken と、その他のキャッシュされた認証情報をクリアします。

このメソッドを使用して、アプリケーションのアカウントを切り替えます (バックエンドで本番環境とテスト環境の Stripe API キーを切り替えるなど)。アカウントを切り替えるには、以下の手順に従います。

1. リーダーが接続されたら、disconnectReader を呼び出します。
2. 新しいアカウントの接続トークンが返されるように onFetchConnectionToken ハンドラーを設定します。
3. clearCachedCredentials を呼び出します。
4. リーダーに再接続します。SDK は、onFetchConnectionToken ハンドラーからの新しい接続トークンをリクエストします。

collectPaymentMethod(request, options)

PaymentIntent の支払い方法の収集を開始します。このメソッドでは、必須パラメーター request を使用します。

• request: バックエンドで作成された PaymentIntent オブジェクトの clientSecret フィールド。詳細については、PaymentIntent を作成し、その client secret を渡す方法をご確認ください。
• options: 追加の支払いパラメーターを含むオブジェクト。

{
  update_payment_intent: boolean,
  payment_intent_id: string,
  enable_customer_cancellation: boolean,
  skip_tipping: boolean,
  tipping: object,
  allow_redisplay: string,
  moto: boolean,
}

tipping オブジェクトでは、以下のオプションを使用できます。

{
  eligible_amount: number,
}

以下のフィールドを持つオブジェクトで解決される、Promiseを返します。

• paymentIntent: 更新された PaymentIntent (支払いインテント) オブジェクト (コマンドが成功した場合)。
• error: エラー (コマンドが失敗した場合)。

支払いの回収について、詳細は支払いの回収ガイドをご覧ください。

cancelCollectPaymentMethod()

未処理の collectPaymentMethod コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する Promise が返されます。キャンセルに失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

processPayment(paymentIntent, options)

支払い方法が収集されたら、支払いを処理します。

このメソッドでは、paymentIntent という 1 つの必須パラメーターを使用します。

• paymentIntent: collectPaymentMethod が正常に呼び出されると取得される PaymentIntent オブジェクト。
• options: 追加の支払いパラメーターを含むオブジェクト。

{
  return_url: string,
}

以下のフィールドを持つオブジェクトで解決される、Promiseを返します。

• paymentIntent: 確定済みの PaymentIntent (支払いインテント) オブジェクト (コマンドが成功した場合)。
• error: エラー (コマンドが失敗した場合)。詳細については、処理の失敗に対処するをご覧ください。

cancelProcessPayment()

未処理の processPayment コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する Promise が返されます。キャンセルに失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

collectSetupIntentPaymentMethod(clientSecret, allowRedisplay, config)

オンラインで再利用するための決済手段を収集して、SetupIntent で使用します。

このメソッドでは、2 つの必須パラメーターを使用します。

• clientSecret: バックエンドで作成された SetupIntent オブジェクトの clientSecret フィールド。

• allowRedisplay: 今後の決済フローでこの決済手段を顧客に表示できるかどうかを示す列挙値。

• config: 回収の設定を含むオプションのオブジェクト。

以下のフィールドを持つオブジェクトで解決される、Promiseを返します。

• setupIntent: 更新済みの SetupIntent (支払い方法設定インテント) オブジェクト (コマンドが成功した場合)。
• error: エラー (コマンドが失敗した場合)。

決済手段の保存についての詳細は、オンライン決済での決済情報の保存ガイドをご覧ください。

cancelCollectSetupIntentPaymentMethod()

未処理の collectSetupIntentPaymentMethod コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する Promise が返されます。キャンセルに失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

confirmSetupIntent(setupIntent)

決済手段が回収された後に SetupIntent を確定します。

このメソッドでは、collectSetupIntentPaymentMethod が正常に呼び出されると取得される SetupIntent オブジェクトを単一のパラメーターとして使用します。

以下のフィールドを持つオブジェクトで解決される、Promiseを返します。

• setupIntent: 確定済みの SetupIntent (支払い方法設定インテント) オブジェクト (コマンドが成功した場合)。
• error: エラー (コマンドが失敗した場合)。

cancelConfirmSetupIntent()

未処理の confirmSetupIntent コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する Promise が返されます。キャンセルに失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

readReusableCard()

オンラインで再利用するカードを読み取ります。

Terminal から開始したオンライン決済の場合、標準的な Terminal の支払いを対象とした低料金およびライアビリティシフトの特典は「受けられません」。ほとんどの構築済みのシステムでは readReusableCard を使用する必要は「ありません」。顧客から対面支払いのみを受けるには、標準フローを使用します。

以下のフィールドを持つオブジェクトで解決される、Promiseを返します。

• payment_method: PaymentMethod (支払い方法) オブジェクト (コマンドが成功した場合)。
• error: エラー (コマンドが失敗した場合)。

cancelReadReusableCard()

未処理の readReusableCard コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する Promise が返されます。キャンセルに失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

setReaderDisplay(displayInfo)

カートの詳細でリーダーの表示を更新します。

このメソッドでは、DisplayInfo オブジェクトを入力として使用します。

{
  type: 'cart',
  cart: {
    line_items: [
      {
        description: string,
        amount: number,
        quantity: number,
      },
    ],
    tax: number,
    total: number,
    currency: string,
  }
}

コマンドが成功した場合、空のオブジェクトに解決される Promise が返されます。コマンドが失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

clearReaderDisplay()

setReaderDisplay で設定したカートの詳細がリーダーに表示されている場合は、このメソッドによって画面がクリアされ、スプラッシュ画面にリセットされます。

コマンドが成功した場合、空のオブジェクトに解決される Promise が返されます。コマンドが失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

setSimulatorConfiguration(configuration)

シミュレーションされたカードリーダーの設定オブジェクトを設定します。

このメソッドは、シミュレーションされたリーダーに接続されている場合にのみ有効となり、それ以外の場合は何のアクションも実行しません。

シミュレーションされたリーダーは、processPayment が完了するまでのみ、指定された設定に従います。この時点で、シミュレーションされたリーダーはデフォルトの動作に戻ります。

このメソッドでは、現在有効な設定オブジェクトがすべて上書きされます。オブジェクトに特定のキーと値のペアを追加するには、必ずこのメソッドと getSimulatorConfiguration の組み合わせを使用してください。

以下の設定オプションが使用できます。

getSimulatorConfiguration()

現在有効な設定オブジェクトを返します。

Stripe Terminal JavaScript SDK は、processPayment 完了後の値のリセットや、キーと値の不明なペアの削除など (これらに限定されません)、必要に応じてこの値を上書きすることがあります。

collectRefundPaymentMethod(charge_id, amount, currency, options, config)

返金する支払い方法の収集を開始します。このメソッドでは、2 つの必須パラメータを使用します。

• charge_id。返金される支払いの ID。
• amount: 金額 (セント) を表す数値。この金額が支払いから返金されます。この数値は、元の支払いで請求された金額以下である必要があります。
• currency: 3 文字の通貨の ISO コード (小文字)。サポートされる通貨である必要があります。
• options: 追加の返金パラメーターを含むオプションのオブジェクト。

• config: 回収の設定を含むオプションのオブジェクト。

以下のいずれかで解決される Promise が返されます。

• 空のオブジェクト (支払い方法の収集に成功した場合)、または
• エラーフィールドを含むオブジェクト (返金の支払い方法の収集中にエラーが発生した場合)。

cancelCollectRefundPaymentMethod()

未処理の collectRefundPaymentMethod コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する Promise が返されます。キャンセルに失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

processRefund()

進行中の返金を処理します。このメソッドは、collectRefundPaymentMethod が正常に返された後にのみ呼び出すことができます。

以下のいずれかで解決される Promise が返されます。

• 返金オブジェクト (返金に成功した場合)。または
• エラーフィールドを含むオブジェクト (返金の処理中にエラーが発生した場合)。

cancelProcessRefund()

未処理の processRefund コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する Promise が返されます。キャンセルに失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

collectInputs(collectInputsParameters)

入力の収集を使用して、フォームの表示と顧客からの情報の収集を開始します。

このメソッドでは、ICollectInputsParameters オブジェクトを入力として使用します。

コマンドが成功した場合、収集された結果に解決される Promise が返されます。コマンドが失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

cancelCollectInputs()

未処理の collectInputs コマンドをキャンセルします。

キャンセルが成功した場合、空のオブジェクトに解決される Promise が返されます。コマンドが失敗した場合、Promise はエラーを含むオブジェクトに解決されます。

エラー

JavaScript SDK から返されるエラーには、エラーの code や、人間が読める message などが含まれます。

processPayment のように PaymentIntent に関係するメソッドの場合、エラーには payment_intent オブジェクトが含まれることもあります。

エラーコード

変更ログ

JavaScript SDK の以前のバージョン (2019 年 6 月 7 日以前) を使用している場合は、実装に含まれるスクリプトの URL を変更して、最新のリリースに更新してください。

<script src="https://js.stripe.com/terminal/v1/"></script>

Stripe Terminal ベータからの移行の詳細については、Terminal ベータの移行ガイドをご覧ください。

2025 年 6 月 2 日

• 更新: シミュレーションされたリーダーは、入力情報の収集をサポートします。
• アップデート: processPayment、confirmSetupIntent、processRefund は、それぞれ cancelProcessPayment、cancelConfirmSetupIntent、cancelProcessRefund でキャンセルできるようになりました。これにより、QR コード決済の提示など、特定のシナリオで操作をキャンセルできます。

v1

• confirmPaymentIntent を processPayment に名称変更。
• PaymentStatus の値の名称を変更。PaymentStatus の値は not_ready、ready、waiting_for_input、processing となりました。
• collectPaymentMethod へのレスポンスからカード詳細を削除。以前は、response.paymentIntent.payment_method.card_payment に含まれていました。
• 領収書情報の格納先を payment_intent.charges[0].payment_method_details.card_present ハッシュに変更。
• シミュレーションされたリーダーを検出する API を discoverReaders({ simulated: true }) に変更。
• readSource を readReusableCard に名称変更。readReusableCard の呼び出しに成功すると、Source ではなく PaymentMethod が返されます。PaymentMethod は、PaymentIntent とともに使用する必要があります。詳細については、Payment Methods API の概要をご覧ください。
• connectReader のレスポンスを { reader: Reader } に変更し、ラッパーの Connection オブジェクトを削除。
• startReaderDiscovery メソッドと stopReaderDiscovery メソッドを削除。リーダーを反復的に検出するには、JavaScript の setInterval メソッドを使用できます。
• clearConnectionToken を clearCachedCredentials に名称変更。