JavaScript API リファレンス
API メソッド
- StripeTerminal.create()
- discoverReaders()
- connectReader()
- disconnectReader()
- getConnectionStatus()
- getPaymentStatus()
- clearCachedCredentials()
- collectPaymentMethod()
- cancelCollectPaymentMethod()
- processPayment()
- collectSetupIntentPaymentMethod()
- cancelCollectSetupIntentPaymentMethod()
- confirmSetupIntent()
- readReusableCard()
- cancelReadReusableCard()
- setReaderDisplay()
- clearReaderDisplay()
- setSimulatorConfiguration()
- getSimulatorConfiguration()
- collectRefundPaymentMethod()
- processRefund()
- cancelCollectRefundPaymentMethod()
- collectInputs()
- cancelCollectInputs()
StripeTerminal.create([options])
指定のオプションを使用して、StripeTerminal
のインスタンスを作成します。
オプション | 説明 |
---|---|
onFetchConnectionToken | バックエンドから接続トークンを取得するイベントハンドラー。 |
onUnexpectedReaderDisconnect | アプリからリーダーが切断される際に呼び出されるイベントハンドラー。 |
onConnectionStatusChange オプション | SDK の ConnectionStatus が変更されると呼び出されるイベントハンドラー。 |
onPaymentStatusChange オプション | SDK の PaymentStatus が変更されると呼び出されるイベントハンドラー。 |
readerBehavior オプション | SDK のライフサイクルを通じてリーダーの動作を設定するオブジェクト。readerBehavior の設定オプションについては、以下を参照してください。 |
リーダーの動作設定
現在、動作設定のオプションは、以下の 1 つのみです。
動作 | 説明 |
---|---|
allowCustomerCancel | 顧客がリーダーのインターフェイスから 注意: このプロパティーは利用可能範囲が狭いため、現時点ではユーザーを受け入れていません。 |
discoverReaders([options])
指定のオプションを使用して、リーダーの検出を開始します。
オプション | 説明 |
---|---|
simulated オプション | シミュレーションされたリーダーを検出するかどうかを示すブール値。何も入力しない場合、この値はデフォルトの false に設定されます。 |
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)
Begins collecting a payment method for a PaymentIntent. This method takes one required parameter, request
:
request
: バックエンドで作成されたPaymentIntent
オブジェクトのclientSecret
フィールド。詳細については、PaymentIntent を作成し、その client secret を渡す方法をご確認ください。options
: 追加の支払いパラメーターを含むオブジェクト。
オプション | 説明 |
---|---|
config_override オプション | 取引ごとに設定の上書きを指定できるようにするオブジェクト。このオブジェクトのデフォルトは Null に設定されています。
|
tipping
オブジェクトでは、以下のオプションを使用できます。
オプション | 説明 |
---|---|
eligible_amount オプション | パーセンテージに基づくチップの計算対象となる取引金額を指定できる数値。この値は 0 以上に設定してください。 0 の場合は、 Payment Intent の金額と同じ場合、パラメーターは無視され、指定された金額に基づいてチップが計算されます。
|
以下のフィールドを持つオブジェクトで解決される、Promise
を返します。
paymentIntent
: 更新された PaymentIntent (支払いインテント) オブジェクト (コマンドが成功した場合)。error
: エラー (コマンドが失敗した場合)。
For more information on collecting payments, see our Collecting Payments guide.
cancelCollectPaymentMethod()
未処理の collectPaymentMethod コマンドをキャンセルします。
コマンドのキャンセルに成功すると、空のオブジェクトに解決される Promise
が返されます。キャンセルに失敗すると、Promise
は、エラーを含むオブジェクトに解決されます
processPayment(paymentIntent, options)
Processes a payment after a payment method has been collected.
このメソッドでは、paymentIntent
という 1 つの必須パラメーターを使用します。
paymentIntent
:collectPaymentMethod
が正常に呼び出されると取得されるPaymentIntent
オブジェクト。options
: 追加の支払いパラメーターを含むオブジェクト。
以下のフィールドを持つオブジェクトで解決される、Promise
を返します。
paymentIntent
: 確定済みの PaymentIntent (支払いインテント) オブジェクト (コマンドが成功した場合)。error
: An error, if the command failed. For more information, see Handling processing failures.
collectSetupIntentPaymentMethod(clientSecret, customerConsentCollected, config)
SetupIntent (支払い方法設定インテント) の、オンラインで再利用するための支払い方法の収集を開始します。
このメソッドでは、2 つの必須パラメーターを使用します。
clientSecret
: バックエンドで作成されたSetupIntent
オブジェクトのclientSecret
フィールド。customerConsentCollected
: カードの保存について顧客の同意を収集したかどうかを示すブール値。config
: 回収の設定を含むオプションのオブジェクト。
オプション | 説明 |
---|---|
enable_customer_cancellation | オプション。デフォルトでは false に設定されています。 true の場合、Android ベースのスマートリーダーではキャンセルボタンが表示されます。 |
以下のフィールドを持つオブジェクトで解決される、Promise
を返します。
setupIntent
: 更新済みの SetupIntent (支払い方法設定インテント) オブジェクト (コマンドが成功した場合)。error
: エラー (コマンドが失敗した場合)。
カード保存の詳細については、オンラインでの支払いのためのカードの保存ガイドをご覧ください。
cancelCollectSetupIntentPaymentMethod()
未処理の collectSetupIntentPaymentMethod
コマンドをキャンセルします。
コマンドのキャンセルに成功すると、空のオブジェクトに解決される Promise
が返されます。キャンセルに失敗すると、Promise
は、エラーを含むオブジェクトに解決されます
confirmSetupIntent(setupIntent)
決済手段が収集されたら、SetupIntent を確定します。
このメソッドでは、collectSetupIntentPaymentMethod
が正常に呼び出されると取得される SetupIntent
オブジェクトを単一のパラメーターとして使用します。
以下のフィールドを持つオブジェクトで解決される、Promise
を返します。
setupIntent
: 確定済みの SetupIntent (支払い方法設定インテント) オブジェクト (コマンドが成功した場合)。error
: エラー (コマンドが失敗した場合)。
readReusableCard()
オンラインで再利用するカードを読み込みます。
Online payments initiated from Terminal do not benefit from the lower pricing and liability shift given to standard Terminal payments. Most integrations do not need to use readReusableCard
. To only collect an in-person payment from a customer, use the standard flow.
以下のフィールドを持つオブジェクトで解決される、Promise
を返します。
payment_method
: PaymentMethod (支払い方法) オブジェクト (コマンドが成功した場合)。error
: エラー (コマンドが失敗した場合)。
注
現在、Stripe Terminal を使用して、将来の再利用に備えて非接触型のカードおよびモバイルウォレット (Apple Pay や Google Pay など) を保存することはできません。
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
の組み合わせを使用してください。
以下の設定オプションが使用できます。
フィールド | 値 | 説明 |
---|---|---|
testCardNumber | シミュレーションされたテストカードのリストを参照してください。 | ユーザーが提示する決済手段として、テスト用カード番号を使用するように、シミュレーションされたリーダーを設定します。これを使用して、複数のカードブランドによる支払いや、支払い拒否のような処理中のエラーなど、実装のさまざまなシナリオをテストできます。 |
testPaymentMethod | シミュレーションされたテストカードのリストを参照してください。 | testCardNumber と目的は同じですが、テストの支払い方法を使用します。 |
tipAmount | 任意の金額または null。 | シミュレーションされたリーダーを設定して、顧客が選択したリーダー上のチップ金額をシミュレーションします。 |
paymentMethodType deprecated |
| 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 のみ)。 この支払いを返金する際に、送金を差戻すかどうかを示すブール値。送金は、返金する金額に比例して差戻されます (全額または一部の金額)。 送金は、支払いを作成したアプリケーションでのみ差戻しできます。 |
config
: 回収の設定を含むオプションのオブジェクト。
オプション | 説明 |
---|---|
enable_customer_cancellation | オプション。デフォルトでは false に設定されています。 true の場合、Android ベースのスマートリーダーではキャンセルボタンが表示されます。 |
以下のいずれかで解決される Promise
が返されます。
- 空のオブジェクト (支払い方法の収集に成功した場合)、または
- エラーフィールドを含むオブジェクト (返金の支払い方法の収集中にエラーが発生した場合)。
processRefund()
進行中の返金を処理します。このメソッドは、collectRefundPaymentMethod
が正常に返された後にのみ呼び出すことができます。
以下のいずれかで解決される Promise
が返されます。
- 返金オブジェクト (返金に成功した場合)。または
- エラーフィールドを含むオブジェクト (返金の処理中にエラーが発生した場合)。
cancelCollectRefundPaymentMethod()
未処理の collectRefundPaymentMethod
コマンドをキャンセルします。
キャンセルに成功した場合は、空のオブジェクトで解決する Promise
が返されます。キャンセルに失敗した場合は、Promise
は error
フィールドを含むオブジェクトで解決されます。
collectInputs(collectInputsParameters)
注
To request access to the Collect Inputs beta, email us at stripe-terminal-betas@stripe.com.
Start displaying forms and collecting information from customers using collect inputs.
This method takes a ICollectInputsParameters
object as input.
Returns a Promise
that resolves to the collected results if the command succeeds. If the command fails, the Promise
resolves to an object with an error.
cancelCollectInputs()
注
To request access to the Collect Inputs beta, email us at stripe-terminal-betas@stripe.com.
Cancels an outstanding collectInputs
command.
Returns a Promise
that resolves to an empty object if the cancellation succeeds. If the command fails, the Promise
resolves to an object with an error.
エラー
JavaScript SDK から返されるエラーには、エラーの code
や、人間が読める message
などが含まれます。
For methods involving a PaymentIntent like processPayment, the error may also include a payment_intent
object.
エラーコード
コード | 説明 |
---|---|
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 によって返されるリーダーが多すぎます。Locations を使用して、検出されたリーダーを場所でフィルターしてください。 |
invalid_reader_version | サポートされていないソフトウェアバージョンがリーダーで実行されています。リーダーを更新して、再度お試しください。 |
reader_error | リクエストの処理中にリーダーからエラーが返されました。詳細については、エラーメッセージを参照してください。 |
command_already_in_progress | このアクションを妨げる別のアクションが実行されているため、このアクションを実行できません。 |
変更ログ
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
に名称変更。