# JavaScript API リファレンス

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

## API メソッド

- [StripeTerminal.create()](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-create)
- [discoverReaders()](https://docs.stripe.com/terminal/references/api/js-sdk.md#discover-readers)
- [connectReader()](https://docs.stripe.com/terminal/references/api/js-sdk.md#connect-reader)
- [disconnectReader()](https://docs.stripe.com/terminal/references/api/js-sdk.md#disconnect)
- [getConnectionStatus()](https://docs.stripe.com/terminal/references/api/js-sdk.md#get-connection-status)
- [getPaymentStatus()](https://docs.stripe.com/terminal/references/api/js-sdk.md#get-payment-status)
- [clearCachedCredentials()](https://docs.stripe.com/terminal/references/api/js-sdk.md#clear-cached-credentials)
- [collectPaymentMethod()](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-payment-method)
- [cancelCollectPaymentMethod()](https://docs.stripe.com/terminal/references/api/js-sdk.md#cancel-collect-payment-method)
- [processPayment()](https://docs.stripe.com/terminal/references/api/js-sdk.md#process-payment)
- [cancelProcessPayment()](https://docs.stripe.com/terminal/references/api/js-sdk.md#cancel-process-payment)
- [collectSetupIntentPaymentMethod()](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-setup-intent-payment-method)
- [cancelCollectSetupIntentPaymentMethod()](https://docs.stripe.com/terminal/references/api/js-sdk.md#cancel-collect-setup-intent-payment-method)
- [confirmSetupIntent()](https://docs.stripe.com/terminal/references/api/js-sdk.md#confirm-setup-intent)
- [cancelConfirmSetupIntent()](https://docs.stripe.com/terminal/references/api/js-sdk.md#cancel-confirm-setup-intent)
- [readReusableCard()](https://docs.stripe.com/terminal/references/api/js-sdk.md#read-reusable-card)
- [cancelReadReusableCard()](https://docs.stripe.com/terminal/references/api/js-sdk.md#cancel-read-reusable-card)
- [setReaderDisplay()](https://docs.stripe.com/terminal/references/api/js-sdk.md#set-reader-display)
- [clearReaderDisplay()](https://docs.stripe.com/terminal/references/api/js-sdk.md#clear-reader-display)
- [setSimulatorConfiguration()](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-setsimulatorconfig)
- [getSimulatorConfiguration()](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-getsimulatorconfig)
- [collectRefundPaymentMethod()](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-collectrefundpaymentmethod)
- [cancelCollectRefundPaymentMethod()](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-cancelcollectrefundpaymentmethod)
- [processRefund()](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-processrefund)
- [cancelProcessRefund()](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-cancelprocessrefund)
- [collectInputs()](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-inputs)
- [cancelCollectInputs()](https://docs.stripe.com/terminal/references/api/js-sdk.md#cancel-collect-inputs)
- [print()](https://docs.stripe.com/terminal/references/api/js-sdk.md#print)

### StripeTerminal.create([options])

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

| オプション | 説明 |
| --- | --- |
| **onFetchConnectionToken** | バックエンドから[接続トークンを取得する](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=js#connection-token)イベントハンドラ。 |
| **onUnexpectedReaderDisconnect** | アプリからリーダーが切断される際に呼び出されるイベントハンドラー。 |
| **onConnectionStatusChange** (オプション) | SDK の ConnectionStatus が変更されると呼び出されるイベントハンドラー。 |
| **onPaymentStatusChange** (オプション) | SDK の PaymentStatus が変更されると呼び出されるイベントハンドラー。 |
| **readerBehavior** (オプション) | SDK のライフサイクルを通じてリーダーの動作を設定するオブジェクト。readerBehavior の設定オプションについては、以下を参照してください。 |

### リーダーの動作設定

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

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

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

### discoverReaders([options])

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

| オプション | 説明 |
| --- | --- |
| **simulated** (オプション) | *シミュレーションリーダー* (Stripe Terminal SDKs and server-driven integrations come with a built-in simulated card reader, so you can develop and test your app without connecting to physical hardware. Whether your integration is complete or you're still building it, use the simulated reader to emulate all the Terminal flows in your app) を検出するかどうかを示すブール値。空の場合、この値のデフォルトは `false` になります。 |
| **location** (オプション) | 指定された `location` に割り当てられたリーダーのみを返します。シミュレーションされたリーダーを検出する際はこのパラメーターが無視されます。

検出されたリーダーを店舗で絞り込む方法については、[店舗を管理する](https://docs.stripe.com/terminal/fleet/locations-and-zones.md)をご覧ください。 |

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

- `discoveredReaders`: 検出された [Reader (リーダー)](https://docs.stripe.com/api/terminal/readers/object.md) オブジェクトのリスト (コマンドが成功した場合)。
- `error`: [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) (コマンドが失敗した場合)。

> アプリケーションでスマートリーダーを検出するには、まずリーダーをアカウントに[登録する](https://docs.stripe.com/terminal/payments/connect-reader.md?reader-type=internet#register-reader)必要があります。

### connectReader(reader, connectOptions)

指定されたオプションを使用して、指定されたリーダーへの[接続](https://docs.stripe.com/terminal/payments/connect-reader.md?reader-type=internet#connect-reader)を試みます。

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

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

- `reader`: 接続された [Reader (リーダー)](https://docs.stripe.com/api/terminal/readers/object.md) (コマンドが成功した場合)。
- `error`: [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) (コマンドが失敗した場合)。

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

### disconnectReader()

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

### getConnectionStatus()

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

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

### getPaymentStatus()

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

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

### clearCachedCredentials()

現在の [ConnectionToken](https://docs.stripe.com/terminal/payments/setup-integration.md?terminal-sdk-platform=js#connection-token) と、その他のキャッシュされた認証情報をクリアします。

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

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

### collectPaymentMethod(request, options)

PaymentIntent の[支払い方法の収集](https://docs.stripe.com/terminal/payments/collect-card-payment.md#collect-payment)を開始します。このメソッドでは、必須パラメーター `request` を使用します。

- `request`: バックエンドで作成された `PaymentIntent` オブジェクトの `clientSecret` フィールド。PaymentIntent を作成し、その Client Secret を渡す方法は[こちら](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=elements&api-integration=paymentintents#web-create-intent)をご覧ください。
- `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`。今後の決済フローでこの決済手段を顧客に表示できるかどうかを示す列挙値。

`moto`

- 省略可能で、デフォルトは false です。true の場合、Android ベースのスマートリーダーによって、[通信販売または電話販売](https://docs.stripe.com/terminal/features/mail-telephone-orders/payments.md)取引用の収集が開始されます。

```json
{
  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** (オプション) | パーセンテージに基づくチップの計算対象となる取引金額を指定できる数値。この値は 0 以上に設定してください。

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

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

```json
{
  eligible_amount: number,
}
``` |

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

- `paymentIntent`: 更新された [PaymentIntent (支払いインテント) オブジェクト](https://docs.stripe.com/api/payment_intents/object.md) (コマンドが成功した場合)。
- `error`: [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) (コマンドが失敗した場合)。

支払いの回収について、詳細は[支払いの回収](https://docs.stripe.com/terminal/payments/collect-card-payment.md)ガイドをご覧ください。

### cancelCollectPaymentMethod()

未処理の [collectPaymentMethod](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-payment-method) コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する `Promise` が返されます。キャンセルに失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### processPayment(paymentIntent, options)

支払い方法が[収集](https://docs.stripe.com/terminal/payments/collect-card-payment.md#collect-payment)されたら、支払いを[処理](https://docs.stripe.com/terminal/payments/collect-card-payment.md#process-payment)します。

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

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

| オプション | 説明 |
| --- | --- |
| **config\_override** (オプション) | 取引ごとに設定の上書きを指定できるようにするオブジェクト。このオブジェクトのデフォルトは Null に設定されています。

`return_url`

- 顧客が決済手段のアプリまたはサイトで決済を認証またはキャンセルした後にリダイレクトされる URL。このパラメータは、リダイレクトベースの支払い方法にのみ使用されます。デフォルトは null です。

```json
{
  return_url: string,
}
``` |

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

- `paymentIntent`: 確定済みの [PaymentIntent (支払いインテント) オブジェクト](https://docs.stripe.com/api/payment_intents/object.md) (コマンドが成功した場合)。
- `error`: [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) (コマンドが失敗した場合)。詳細については、[処理の失敗に対処する](https://docs.stripe.com/terminal/payments/collect-card-payment.md#handling-failures)をご覧ください。

### cancelProcessPayment()

未処理の [processPayment](https://docs.stripe.com/terminal/references/api/js-sdk.md#process-payment) コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する `Promise` が返されます。キャンセルに失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### collectSetupIntentPaymentMethod(clientSecret, allowRedisplay, config)

[オンラインで再利用するための決済手段を収集](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md)して、[SetupIntent](https://docs.stripe.com/api/setup_intents/object.md) で使用します。

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

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

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

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

| オプション | 説明 |
| --- | --- |
| **enable\_customer\_cancellation** | オプション。デフォルトでは false に設定されています。

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

true の場合、Android ベースのスマートリーダーによって[通信販売または電話販売](https://docs.stripe.com/terminal/features/mail-telephone-orders/save-directly.md)用カードの保存が開始されます。 |

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

- `setupIntent`: 更新済みの [SetupIntent (支払い方法設定インテント) オブジェクト](https://docs.stripe.com/api/setup_intents/object.md) (コマンドが成功した場合)。
- `error`: [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) (コマンドが失敗した場合)。

決済手段の保存についての詳細は、[オンライン決済での決済情報の保存](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md)ガイドをご覧ください。

### cancelCollectSetupIntentPaymentMethod()

未処理の [collectSetupIntentPaymentMethod](https://docs.stripe.com/terminal/references/api/js-sdk.md#collect-setup-intent-payment-method) コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する `Promise` が返されます。キャンセルに失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### confirmSetupIntent(setupIntent)

決済手段が[回収](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md#submit-payment-method)された後に SetupIntent を[確定](https://docs.stripe.com/terminal/features/saving-payment-details/save-directly.md#collect-payment-method)します。

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

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

- `setupIntent`: 確定済みの [SetupIntent (支払い方法設定インテント) オブジェクト](https://docs.stripe.com/api/setup_intents/object.md) (コマンドが成功した場合)。
- `error`: [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) (コマンドが失敗した場合)。

### cancelConfirmSetupIntent()

未処理の [confirmSetupIntent](https://docs.stripe.com/terminal/references/api/js-sdk.md#confirm-setup-intent) コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する `Promise` が返されます。キャンセルに失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### readReusableCard()

[オンラインで再利用](https://docs.stripe.com/terminal/features/saving-payment-details/overview.md)するカードを読み取ります。

Terminal から開始したオンライン決済の場合、[標準的な Terminal の支払い](https://docs.stripe.com/terminal/payments/collect-card-payment.md)を対象とした[低料金](https://stripe.com/terminal#pricing)および*ライアビリティシフト* (With some 3D Secure transactions, the liability for fraudulent chargebacks (stolen or counterfeit cards) shifts from you to the card issuer)の特典は「受けられません」。ほとんどの構築済みのシステムでは `readReusableCard` を使用する必要は「ありません」。顧客から対面支払いのみを受けるには、[標準フロー](https://docs.stripe.com/terminal/payments/collect-card-payment.md)を使用します。

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

- `payment_method`: [PaymentMethod (支払い方法) オブジェクト](https://docs.stripe.com/api/payment_methods/object.md) (コマンドが成功した場合)。
- `error`: [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) (コマンドが失敗した場合)。

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

### cancelReadReusableCard()

未処理の [readReusableCard](https://docs.stripe.com/terminal/references/api/js-sdk.md#read-reusable-card) コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する `Promise` が返されます。キャンセルに失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### setReaderDisplay(displayInfo)

[カートの詳細](https://docs.stripe.com/terminal/features/display.md)でリーダーの表示を更新します。

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

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

コマンドが成功した場合、空のオブジェクトに解決される `Promise` が返されます。コマンドが失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### clearReaderDisplay()

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

コマンドが成功した場合、空のオブジェクトに解決される `Promise` が返されます。コマンドが失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### setSimulatorConfiguration(configuration)

*シミュレーションカードリーダー* (Stripe Terminal SDKs and server-driven integrations come with a built-in simulated card reader, so you can develop and test your app without connecting to physical hardware. Whether your integration is complete or you're still building it, use the simulated reader to emulate all the Terminal flows in your app) の設定オブジェクトを構成します。

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

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

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

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

| フィールド | 値 | 説明 |
| --- | --- | --- |
| **testCardNumber** | [シミュレーションされたテストカード](https://docs.stripe.com/terminal/references/testing.md#simulated-test-cards)のリストを参照してください。 | ユーザーが提示する支払い方法として、テスト用カード番号を使用するように、シミュレーションされたリーダーを設定します。これを使用して、複数のカードブランドによる支払いや、支払い拒否のような処理中のエラーなど、実装のさまざまなシナリオをテストできます。 |
| **testPaymentMethod** | [シミュレーションされたテストカード](https://docs.stripe.com/terminal/references/testing.md#simulated-test-cards)のリストを参照してください。 | `testCardNumber` と目的は同じですが、テストの支払い方法を使用します。 |
| **tipAmount** | 任意の金額または null。 | シミュレーションされたリーダーを設定して、顧客が選択したリーダー上のチップ金額をシミュレーションします。 |
| **collectInputsResult** | 以下の動作のテストに対応しています。

- 成功:
  - 入力をスキップしない: `{ resultType: 'succeeded', skipBehavior: 'none' }`
  - 必須ではない入力のスキップ: `{ resultType: 'succeeded', skipBehavior: 'all' }`
- タイムアウト: `{ resultType: 'timeout' }`

詳細については、[実装をテストする](https://docs.stripe.com/terminal/features/collect-inputs.md?terminal-sdk-platform=js#test-your-integration)をご覧ください。 | [入力の収集](https://docs.stripe.com/terminal/features/collect-inputs.md?terminal-sdk-platform=js)をシミュレーションするように、シミュレーションされたリーダーを設定します。 |
| **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 コード](https://docs.stripe.com/currencies.md) (小文字)。[サポートされる通貨](https://docs.stripe.com/currencies.md)である必要があります。
- `options`: 追加の返金パラメーターを含むオプションのオブジェクト。

| オプション | 説明 |
| --- | --- |
| **refund\_application\_fee** | オプション。デフォルトでは false に設定されています (Connect のみ)。

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

プラットフォーム手数料は、支払いを作成したアプリケーションでのみ返金できます。 |
| **reverse\_transfer** | オプション。デフォルトでは false に設定されています (Connect のみ)。

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

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

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

| オプション | 説明 |
| --- | --- |
| **enable\_customer\_cancellation** | オプション。デフォルトでは false に設定されています。

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

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

- 空のオブジェクト (支払い方法の収集に成功した場合)、または
- [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)フィールドを含むオブジェクト (返金の支払い方法の収集中にエラーが発生した場合)。

### cancelCollectRefundPaymentMethod()

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

コマンドのキャンセルに成功すると、空のオブジェクトに解決する `Promise` が返されます。キャンセルに失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### processRefund()

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

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

- 返金オブジェクト (返金に成功した場合)。または
- [エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)フィールドを含むオブジェクト (返金の処理中にエラーが発生した場合)。

### cancelProcessRefund()

未処理の [processRefund](https://docs.stripe.com/terminal/references/api/js-sdk.md#stripeterminal-processrefund) コマンドをキャンセルします。

コマンドのキャンセルに成功すると、空のオブジェクトに解決する `Promise` が返されます。キャンセルに失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### collectInputs(collectInputsParameters)

[入力の収集](https://docs.stripe.com/terminal/features/collect-inputs.md)を使用して、フォームの表示と顧客からの情報の収集を開始します。

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

コマンドが成功した場合、収集された結果に解決される `Promise` が返されます。コマンドが失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### cancelCollectInputs()

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

キャンセルが成功した場合、空のオブジェクトに解決される `Promise` が返されます。コマンドが失敗した場合、`Promise` は[エラー](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors)を含むオブジェクトに解決されます。

### print(content)

> 印刷は [Verifone V660p](https://stripe.com/terminal/v660p) リーダーでのみ使用できます。詳細については、[統合ガイド](https://docs.stripe.com/terminal/features/print-content.md?terminal-sdk-platform=js) をご覧ください。

使用可能な場合、指定されたコンテンツを接続されたリーダーのプリンターに印刷します。このメソッドには、`content` という必須パラメーターが 1 つあります。

- `content`: 印刷するコンテンツ。これは `HTMLCanvasElement` オブジェクトである必要があります。

print コマンドが成功した場合、空のオブジェクトに解決される `Promise` が返されます。コマンドが失敗した場合、`Promise` は [error](https://docs.stripe.com/terminal/references/api/js-sdk.md#errors) を含むオブジェクトに解決されます。

## エラー

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

[processPayment](https://docs.stripe.com/terminal/payments/collect-card-payment.md#handling-failures) のように 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` によって返されるリーダーが多すぎます。[店舗](https://docs.stripe.com/terminal/fleet/locations-and-zones.md)を使用して、検出されたリーダーを店舗で絞り込んでください。 |
| `invalid_reader_version` | サポートされていないソフトウェアバージョンがリーダーで実行されています。リーダーを更新して、再度お試しください。 |
| `reader_error` | リクエストの処理中にリーダーからエラーが返されました。詳細については、エラーメッセージを参照してください。 |
| `command_already_in_progress` | このアクションを妨げる別のアクションが実行されているため、このアクションを実行できません。 |
| `printer_busy` | 別の印刷操作がすでに進行中です。 |
| `printer_paperjam` | プリンターに紙詰まりがあります。プリンターのカバーを開き、手動で紙詰まりを取り除きます。 |
| `printer_cover_open` | プリンターのカバーまたはヘッドアセンブリが開いている。 |
| `printer_out_of_paper` | プリンターの用紙が切れています。 |
| `printer_absent` | リーダーにプリンターがありません。 |
| `printer_unavailable` | リーダーにプリンターがありますが、現在使用できません。 |
| `printer_error` | 印刷操作が不明な理由で失敗しました。 |

## 変更ログ

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

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

Stripe Terminal ベータからの移行の詳細については、[Terminal ベータの移行ガイド](https://docs.stripe.com/terminal/references/sdk-migration-guide.md)をご覧ください。

#### 2025 年 10 月 30 日

- 更新: `processPayment` で追加料金の同意回収のサポートを追加しました。リーダーに追加料金の同意画面を表示し、最大 220 文字のカスタマイズメッセージを含めることができるようになりました。

#### 2025 年 10 月 6 日

- プレビュー: Verifone V660p リーダーで画像を印刷できるようにする `print` メソッドを追加しました。
  - プレビューへの参加をご希望の場合は、[Stripe サポート](https://support.stripe.com/) にお問い合わせください。

#### 2025 年 6 月 2 日

- 更新: シミュレーションされたリーダーは、[入力情報の収集](https://docs.stripe.com/terminal/features/collect-inputs.md?terminal-sdk-platform=js#test-your-integration)をサポートします。
- アップデート: `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](https://docs.stripe.com/api/payment_methods.md) が返されます。PaymentMethod は、PaymentIntent とともに使用する必要があります。詳細については、[Payment Methods API](https://docs.stripe.com/payments/payment-methods.md) の概要をご覧ください。
- `connectReader` のレスポンスを `{ reader: Reader }` に変更し、ラッパーの `Connection` オブジェクトを削除。
- `startReaderDiscovery` メソッドと `stopReaderDiscovery` メソッドを削除。リーダーを反復的に検出するには、JavaScript の `setInterval` メソッドを使用できます。
- `clearConnectionToken` を `clearCachedCredentials` に名称変更。