JavaScript API リファレンス

Stripe Terminal JavaScript SDK を上手に活用するために、Stripe の API リファレンスをご使用ください。

API methods

StripeTerminal.create([options])

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

オプション	説明
onFetchConnectionToken	バックエンドから接続トークンを取得するイベントハンドラ。
onUnexpectedReaderDisconnect	アプリからリーダーが切断される際に呼び出されるイベントハンドラー。
onConnectionStatusChange オプション	SDK の ConnectionStatus が変更されると呼び出されるイベントハンドラー。
onPaymentStatusChange オプション	SDK の PaymentStatus が変更されると呼び出されるイベントハンドラー。
readerBehavior オプション	SDK のライフサイクルを通じてリーダーの動作を設定するオブジェクト。readerBehavior の設定オプションについては、以下を参照してください。

リーダーの動作設定

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

動作説明

動作	説明
allowCustomerCancel	顧客がリーダーのインターフェイスから `collectPaymentMethod` をキャンセルできるかどうかを決定するブール値。デフォルトでは `false` です。注意: このプロパティーは利用可能範囲が狭いため、現時点ではユーザーを受け入れていません。

allowCustomerCancel

顧客がリーダーのインターフェイスから collectPaymentMethod をキャンセルできるかどうかを決定するブール値。デフォルトでは false です。

注意: このプロパティーは利用可能範囲が狭いため、現時点ではユーザーを受け入れていません。

discoverReaders([options])

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

オプション説明

simulated オプションシュミレーションされたリーダーを検出するかどうかを示すブール値。何も入力しない場合、この値はデフォルトの false になります。

オプション	説明
simulated オプション	シュミレーションされたリーダーを検出するかどうかを示すブール値。何も入力しない場合、この値はデフォルトの `false` になります。
location オプション	指定された `location` に割り当てられたリーダーのみを返します。シミュレーションされたリーダーを検出する際はこのパラメーターが無視されます。場所を使用して検出されたリーダーを絞り込む方法について、詳細は場所を管理するをご覧ください。

location オプション

指定された location に割り当てられたリーダーのみを返します。シミュレーションされたリーダーを検出する際はこのパラメーターが無視されます。

場所を使用して検出されたリーダーを絞り込む方法について、詳細は場所を管理するをご覧ください。

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

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

注

アプリケーションで Verifone P400 を検出する前に、リーダーをアカウントに登録する必要があります。

connectReader(reader, connectOptions)

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

オプション	説明
fail_if_in_use オプション	リーダーが現在 Terminal SDK に接続されている場合に、接続に失敗していることを示すブール値。何も入力しない場合、この値はデフォルトの `false` になります。

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

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

注

アプリケーションに Reader オブジェクトをキャッシュしないでください。リーダーの IP アドレスが変更されている場合は、以前の Reader に接続できない場合があります。

disconnectReader()

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

getConnectionStatus()

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

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

getPaymentStatus()

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

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

clearCachedCredentials()

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

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

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

collectPaymentMethod(request, options)

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

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

オプション説明

オプション	説明
config_override オプション	取引ごとに設定の上書きを指定できるようにするオブジェクト。このオブジェクトのデフォルトは Null に設定されています。 `skip_tipping` オプション。デフォルトは false に設定されています。true の場合、リーダーではチップ処理画面がスキップされます。 `tipping` 取引ごとにチップ処理関連のオプションを指定できるようにするオブジェクト。以下で説明します。 `update_payment_intent` ブール値が `payment_intent_id` とペアになると、`PaymentIntent` を更新し、関連付けられた `PaymentMethod` をカード詳細とともに返すように呼び出します。 `enable_customer_cancellation` オプション。デフォルトは false です。true の場合、Android ベースのスマートリーダーにキャンセルボタンが表示されます。 `allow_redisplay` `setup_future_usage` が設定されている場合は必須、それ以外の場合はデフォルトで `unspecified`。今後の決済フローでこの決済手段を顧客に表示できるかどうかを示す列挙値。 `{ update_payment_intent: boolean, payment_intent_id: string, enable_customer_cancellation: boolean, skip_tipping: boolean, tipping: object, allow_redisplay: string }`

config_override オプション

取引ごとに設定の上書きを指定できるようにするオブジェクト。このオブジェクトのデフォルトは Null に設定されています。

skip_tipping

オプション。デフォルトは false に設定されています。true の場合、リーダーではチップ処理画面がスキップされます。

tipping

取引ごとにチップ処理関連のオプションを指定できるようにするオブジェクト。以下で説明します。

update_payment_intent

ブール値が payment_intent_id とペアになると、PaymentIntent を更新し、関連付けられた PaymentMethod をカード詳細とともに返すように呼び出します。

enable_customer_cancellation

オプション。デフォルトは false です。true の場合、Android ベースのスマートリーダーにキャンセルボタンが表示されます。

allow_redisplay

setup_future_usage が設定されている場合は必須、それ以外の場合はデフォルトで unspecified。今後の決済フローでこの決済手段を顧客に表示できるかどうかを示す列挙値。

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

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

オプション説明

オプション	説明
eligible_amount オプション	パーセンテージに基づくチップの計算対象となる取引金額を指定できる数値。この値は 0 以上に設定してください。 0 の場合は、`skip_tipping` の値に関係なくチップ処理がスキップされます。 PaymentIntent の金額と同じ場合、パラメーターは無視され、指定された金額に基づいてチップが計算されます。 `{ eligible_amount: number, }`

eligible_amount オプション

パーセンテージに基づくチップの計算対象となる取引金額を指定できる数値。この値は 0 以上に設定してください。

0 の場合は、skip_tipping の値に関係なくチップ処理がスキップされます。

PaymentIntent の金額と同じ場合、パラメーターは無視され、指定された金額に基づいてチップが計算されます。

{
  eligible_amount: number,
}

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

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

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

cancelCollectPaymentMethod()

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

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

processPayment(paymentIntent, options)

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

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

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

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

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

collectSetupIntentPaymentMethod(clientSecret, allowRedisplay, config)

SetupIntent (支払い方法設定インテント) の、オンラインで再利用するための支払い方法の収集を開始します。

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

clientSecret: バックエンドで作成された SetupIntent オブジェクトの clientSecret フィールド。
allowRedisplay: 今後の決済フローでこの決済手段を顧客に表示できるかどうかを示す列挙値。
config: 回収の設定を含むオプションのオブジェクト。

オプション	説明
enable_customer_cancellation	オプション。デフォルトでは false に設定されています。 true の場合、Android ベースのスマートリーダーではキャンセルボタンが表示されます。

オプション

説明

enable_customer_cancellation

オプション。デフォルトでは false に設定されています。

true の場合、Android ベースのスマートリーダーではキャンセルボタンが表示されます。

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

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

カード保存の詳細については、オンライン決済のためのカードの保存ガイドをご覧ください。

cancelCollectSetupIntentPaymentMethod()

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

confirmSetupIntent(setupIntent)

支払い方法が収集されたら、SetupIntent を確定します。

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

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

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

readReusableCard()

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

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

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

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

注

現在、Stripe Terminal を使用して、将来の再利用に備えて非接触型のカードおよびモバイルウォレット (Apple Pay や Google Pay など) を保存することはできません。

cancelReadReusableCard()

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

setReaderDisplay(displayInfo)

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

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

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

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

clearReaderDisplay()

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

setSimulatorConfiguration(configuration)

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

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

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

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

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

フィールド	値	説明
testCardNumber	シミュレーションされたテストカードのリストを参照してください。	ユーザーが提示する支払い方法として、テスト用カード番号を使用するように、シミュレーションされたリーダーを設定します。これを使用して、複数のカードブランドによる支払いや、支払い拒否のような処理中のエラーなど、実装のさまざまなシナリオをテストできます。
testPaymentMethod	シミュレーションされたテストカードのリストを参照してください。	`testCardNumber` と目的は同じですが、テストの支払い方法を使用します。
tipAmount	任意の金額または null。	シミュレーションされたリーダーを設定して、顧客が選択したリーダー上のチップ金額をシミュレーションします。
paymentMethodType deprecated	`card_present` (デフォルト) `interac_present`	`collectPaymentMethod` が呼び出されたときに、シミュレーションされたリーダーによって作成される支払い方法のタイプを決定します。

getSimulatorConfiguration()

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

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

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

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

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

オプション	説明
refund_application_fee	オプション。デフォルトでは false に設定されています (Connect のみ)。この支払いを返金する際に、プラットフォーム手数料を返金するかどうかを示すブール値。支払いを全額返金する場合、プラットフォーム手数料は全額返金されます。それ以外の場合は、返金する支払い金額に比例した金額のプラットフォーム手数料が返金されます。プラットフォーム手数料は、支払いを作成したアプリケーションでのみ返金できます。
reverse_transfer	オプション。デフォルトでは false に設定されています (Connect のみ)。この支払いを返金する際に、送金を差戻すかどうかを示すブール値。送金は、返金する金額に比例して差戻されます (全額または一部の金額)。送金は、支払いを作成したアプリケーションでのみ差戻しできます。

オプション

説明

refund_application_fee

オプション。デフォルトでは false に設定されています (Connect のみ)。

この支払いを返金する際に、プラットフォーム手数料を返金するかどうかを示すブール値。支払いを全額返金する場合、プラットフォーム手数料は全額返金されます。それ以外の場合は、返金する支払い金額に比例した金額のプラットフォーム手数料が返金されます。

プラットフォーム手数料は、支払いを作成したアプリケーションでのみ返金できます。

reverse_transfer

オプション。デフォルトでは false に設定されています (Connect のみ)。

この支払いを返金する際に、送金を差戻すかどうかを示すブール値。送金は、返金する金額に比例して差戻されます (全額または一部の金額)。

送金は、支払いを作成したアプリケーションでのみ差戻しできます。

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

オプション	説明
enable_customer_cancellation	オプション。デフォルトでは false に設定されています。 true の場合、Android ベースのスマートリーダーではキャンセルボタンが表示されます。

オプション

説明

enable_customer_cancellation

オプション。デフォルトでは false に設定されています。

true の場合、Android ベースのスマートリーダーではキャンセルボタンが表示されます。

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

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

processRefund()

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

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

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

cancelCollectRefundPaymentMethod()

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

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

collectInputs(collectInputsParameters)

注

Collect Inputs のベータへのアクセスをリクエストするには、stripe-terminal-betas@stripe.com 宛にメールでお問い合わせください。

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

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

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

cancelCollectInputs()

注

Collect Inputs のベータへのアクセスをリクエストするには、stripe-terminal-betas@stripe.com 宛にメールでお問い合わせください。

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

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

Errors

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

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

エラーコード

コード	説明
`no_established_connection`	リーダーが接続されていないためコマンドが失敗しました。
`no_active_collect_payment_method_attempt`	`cancelCollectPaymentMethod` は、`collectPaymentMethod` が実行中の場合にのみ呼び出すことができます。
`no_active_read_reusable_card_attempt`	`cancelCollectReusableCard` は、`readReusableCard` が実行中の場合にのみ呼び出すことができます。
`canceled`	コマンドがキャンセルされました。
`cancelable_already_completed`	操作はすでに完了しているため、キャンセルできませんでした。
`cancelable_already_canceled`	操作はすでにキャンセルされているため、キャンセルできませんでした。
`network_error`	ネットワーク経由でサーバーやリーダーと通信しているときに、不明なエラーが発生しました。詳細はエラーメッセージを参照してください。
`network_timeout`	ネットワーク経由でサーバーやリーダーと通信しているときに、リクエストがタイムアウトになりました。デバイスとリーダーが両方とも、安定した接続状態でネットワークに接続されていることを確認してください。
`already_connected`	リーダーがすでに接続されているため、`connectReader` が失敗しました。
`failed_fetch_connection_token`	接続トークンの取得に失敗しました。接続トークンハンドラーが、接続トークンで解決される Promise を返すことを確認してください。
`discovery_too_many_readers`	`discoverReaders` によって返されるリーダーが多すぎます。場所を使用して、検出されたリーダーを場所で絞り込んでください。
`invalid_reader_version`	サポートされていないソフトウェアバージョンがリーダーで実行されています。リーダーを更新して、再度お試しください。
`reader_error`	リクエストの処理中にリーダーからエラーが返されました。詳細については、エラーメッセージを参照してください。
`command_already_in_progress`	このアクションを妨げる別のアクションが実行されているため、このアクションを実行できません。

Changelog

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

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

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

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 に名称変更。