# コンビニ決済 Payment Intents API と Payment Methods API を使用して、日本でよく使用されるコンビニエンスストアでの支払いを受け付けます。 # Checkout > This is a Checkout for when payment-ui is checkout. View the full page at https://docs.stripe.com/payments/konbini/accept-a-payment?payment-ui=checkout. > Stripe は、通貨、支払い方法の制限、その他のパラメーターを評価することで、適切な支払い方法を顧客に自動的に提示できます。 > > - [決済の受け付け](https://docs.stripe.com/payments/accept-a-payment.md?payment-ui=checkout&ui=stripe-hosted)ガイドに従って、[動的な決済手段](https://docs.stripe.com/payments/payment-methods/dynamic-payment-methods.md)を使用するチェックアウトの統合機能を構築します。 - 動的な決済手段を使用しない場合は、チェックアウトの導入で、決済方法を手動で設定するために以下のステップに従ってください。 コンビニ決済は [1 回限り使用](https://docs.stripe.com/payments/payment-methods.md#usage)の支払い方法であり、顧客は支払いを完了するために[追加の対応をする](https://docs.stripe.com/payments/payment-methods.md#customer-actions)必要があります。顧客は日本のコンビニエンスストアで支払いコード、確認番号を提示し、現金で支払います。支払いが完了すると、Stripe から通知が届きます。 ## 互換性を判断する **サポート対象のビジネスの所在地**: JP **対応可能な通貨**: `jpy` **取引通貨**: `jpy` **支払いモード**: Yes **セットアップモード**: No **サブスクリプションモード**: No コンビニ決済に対応するには、Checkout セッションで次の条件をすべて満たしている必要があります。 - ラインアイテムの*価格* (Prices define how much and how often to charge for products. This includes how much the product costs, what currency to use, and the interval if the price is for subscriptions)はすべて、同じ通貨 (JPY) である必要があります。 - 使用できるのは単一の項目だけです (継続的な*サブスクリプション* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)プランには対応していません)。 ## 支払いを受け付ける > このガイドを使用する前に、まず Checkout で[決済を受け付ける](https://docs.stripe.com/payments/accept-a-payment.md?integration=checkout)ための実装を構築します。 このガイドでは、コンビニ決済を有効にする方法について手順を追って説明し、動的な支払い方法を使用して決済を受け付ける場合と支払い方法を手動で設定する場合の違いを示します。 ### 支払い方法としてコンビニ決済を有効にする 新しい [Checkout セッション](https://docs.stripe.com/api/checkout/sessions.md)を作成する際は、以下を行う必要があります。 1. `コンビニ`を `payment_method_types` のリストに追加します。 1. すべての `line_items` が `jpy` 通貨を使用していることを確認します。 #### Stripe ホスト型ページ ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][currency]=jpy" \ -d "line_items[0][price_data][product_data][name]=Tシャツ" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d "payment_method_types[0]=card" \ -d "payment_method_types[1]=konbini" \ --data-urlencode "success_url=https://example.com/success" ``` #### 組み込みフォーム ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][currency]=jpy" \ -d "line_items[0][price_data][product_data][name]=Tシャツ" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d "payment_method_types[0]=card" \ -d "payment_method_types[1]=konbini" \ --data-urlencode "return_url=https://example.com/return" \ -d ui_mode=embedded_page ``` ### その他の支払い方法オプション 支払い方法オプションは、[支払い方法オプション](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-konbini)の `konbini` キーで指定できます。 | フィールド | 値 | 必須 | デフォルト値 | | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | | `expires_after_days` | 保留中のコンビニ決済の期限切れまでの日数。有効値は 1 ～ 60 日です。[有効期限](https://docs.stripe.com/payments/konbini/accept-a-payment.md#checkout-additional-options-expiration)をご覧ください。 | いいえ | 3 | #### 有効期限 保留中のコンビニ決済は、指定した日付の真夜中 (23:59:59 JST) に期限切れになります。たとえば、`expires_after_days` に 2 が設定され、月曜日に PaymentIntent が確定された場合、保留中のコンビニ決済は水曜日の日本時間 (UTC+9) 23:59:59 に期限切れになります。 #### Stripe ホスト型ページ ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][currency]=jpy" \ -d "line_items[0][price_data][product_data][name]=Tシャツ" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d "payment_method_options[konbini][expires_after_days]=7" \ -d "payment_method_types[0]=card" \ -d "payment_method_types[1]=konbini" \ --data-urlencode "success_url=https://example.com/success" ``` #### 組み込みフォーム ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "line_items[0][price_data][currency]=jpy" \ -d "line_items[0][price_data][product_data][name]=Tシャツ" \ -d "line_items[0][price_data][unit_amount]=2000" \ -d "line_items[0][quantity]=1" \ -d mode=payment \ -d "payment_method_options[konbini][expires_after_days]=7" \ -d "payment_method_types[0]=card" \ -d "payment_method_types[1]=konbini" \ --data-urlencode "return_url=https://example.com/return" \ -d ui_mode=embedded_page ``` #### 電話番号 コンビニの決済フォームでは、顧客はオプションで電話番号を入力して確認番号として使用できます。これにより、店内の UI で支払いコードと確認番号の入力が求められるコンビニエンスストアでの支払いプロセスが簡素化されます。両方とも、顧客が決済フォームを提示した後に表示される支払い手順に反映されます。顧客が電話番号を提供しない場合、Stripe はランダムな確認番号を生成します。 電話番号がゼロのみで構成される場合、Stripe はその番号をブロックします。 ### Stripe がオンラインで提供する取引の詳細ページにリダイレクトする > カード支払いと異なり、コンビニ決済では顧客は [success_url](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-success_url) にリダイレクトされません。 Checkout フォームの送信に成功すると、顧客は `hosted_voucher_url` にリダイレクトされます。顧客はオンラインで提供されるページに記載されている支払い手順書を参照して、支払いを完了する詳しい方法を確認できます。このページはデスクトップとモバイルで見ることができ、印刷も可能です。 Stripe は、コンビニ決済用の取引詳細が正常に作成されると、[payment_intent.requires_action](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.requires_action) イベントを送信します。店舗支払いの詳細を記載したリンクを顧客にメールで送信する必要がある場合は、[payment_intent.next_action.konbini_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-konbini_display_details-hosted_voucher_url) に `hosted_voucher_url` が含まれています。[Webhook で PaymentIntent を監視する](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks)方法をご確認ください。 Stripe では、[ブランディング設定](https://dashboard.stripe.com/account/branding) ページで顧客に表示される UI をカスタマイズすることができます。取引の詳細には、以下のブランド設定を適用できます。 - **アイコン**: ブランド画像と公開ビジネス名 - **アクセント**:「番号をコピー」ボタンのカラーとして使用されます - **ブランドカラー**: 背景色として使用されます ### 注文のフルフィルメントを実行する Konbini は通知遅延型の支払い方法であるため、*Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) などの方法を使用して支払いステータスを監視し、注文の*フルフィルメント* (Fulfillment is the process of providing the goods or services purchased by a customer, typically after payment is collected)を履行する必要があります。詳細については、[Webhook の設定と注文のフルフィルメントの履行](https://docs.stripe.com/checkout/fulfillment.md)をご覧ください。 支払いのステータスに変化があると、以下のイベントが送信されます。 | イベント名 | 説明 | 次のステップ | | -------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | | [checkout.session.completed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.completed) | 顧客が Checkout フォームの送信を完了しました。Stripe がコンビニ決済向けに取引の詳細を生成しています。 顧客がコンビニ決済のための取引詳細を紛失した場合に備え、顧客に `hosted_voucher_url` をメールで送信することもできます。 | 顧客がコンビニで支払うのを待っています。 | | [checkout.session.async_payment_succeeded](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_succeeded) | 顧客がコンビニ決済を完了しました。`PaymentIntent` が `succeeded` に移行します。 | 顧客が購入した商品またはサービスのフルフィルメントを実行します。 | | [checkout.session.async_payment_failed](https://docs.stripe.com/api/events/types.md#event_types-checkout.session.async_payment_failed) | コンビニ決済の有効期限が切れたか、その他の理由で支払いが失敗しました。`PaymentIntent` のステータスは `requires_payment_method` に戻ります。 | 顧客にメールで連絡して、新たに注文を行うようリクエストします。 | ## 組み込みをテストする Checkout の組み込みをテストする際は、支払い方法としてコンビニ決済を選択して、**支払う**ボタンをクリックします。 決済フォームに次の値を指定して、さまざまなシナリオをテストします。特殊な確認番号とメールパターンのいずれかを使用してテストできます。両方を指定した場合、特殊な確認番号の動作が適用されます。 | メールアドレス | 確認番号 | 説明 | | ---------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{any_prefix}@{any_domain}` | `11111111110` | 3 分後に成功し、その後 `payment_intent.succeeded` Webhook を受信するコンビニ決済をシミュレーションします。 例: hanako@test.com | | `{any_prefix}succeed_immediately@{any_domain}` | `22222222220` | 即座に成功し、その後 `payment_intent.succeeded` Webhook を受信するコンビニ決済をシミュレーションします。 例: succeed_immediately@test.com | | `{any_prefix}expire_immediately@{any_domain}` | `33333333330` | 即座に有効期限が切れ、その後 `payment_intent.payment_failed` Webhook を受信するコンビニ決済をシミュレーションします。 [支払い方法オプション](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-konbini-expires_after_days)で `expires_after_days` や `expires_at` のパラメーターに設定された値に関係なく、[next_action.konbini_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-konbini_display_details-expires_at) の `expires_at` フィールドは現在の時刻に設定されます。 例: expire_immediately@test.com | | `{any_prefix}expire_with_delay@{any_domain}` | `44444444440` | 成功することなく、3 分後に有効期限が切れ、その後 `payment_intent.payment_failed` Webhook を受信するコンビニ決済をシミュレーションします。 [支払い方法オプション](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-konbini-expires_after_days)で `expires_after_days` や `expires_at` のパラメーターに設定された値に関係なく、[next_action.konbini_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-konbini_display_details-expires_at) の `expires_at` フィールドは 3 分後に設定されます。 例: expire_with_delay@test.com | | `{any_prefix}fill_never@{any_domain}` | `55555555550` | コンビニ決済を成功させずにシミュレーションを実行します。[支払い方法オプション](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-konbini-expires_after_days)で指定されたパラメーターに基づき、`next_action.konbini_display_details` の `expires_at` フィールドに従って有効期限が切れ、その後 `payment_intent.payment_failed` Webhook が届きます。 例: fill_never@test.com | [確認番号](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-confirm-payment-intent-additional-options-confirmation-number)のエラーをテストするには、以下の値を使用できます。 - `01234567890` は、確認番号の拒否をシミュレートします。 - `00000000000` は検証エラーを引き起こします。 ## 有効期限とキャンセル `expires_at` の値で指定された [next_action.konbini_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-konbini_display_details-expires_at) の期限を過ぎると、顧客はコンビニエンスストアのキオスクで、保留中のコンビニ決済の処理を_「開始」*できなくなります。ただし、期限が切れる前に有効な払込取扱票を発行した場合には、`expires_at` の後でもレジで決済を*「完了」_できます。 このような場合に備え、早期に支払いが失敗しないように、バッファーの時間が設けられています。PaymentIntent のステータスは `requires_payment_method` に変わります。この時点では、別の支払い方法を指定して PaymentIntent を確定するか、キャンセルできます。 保留中のコンビニ決済は、確定後 `next_action.konbini_display_details.expires_at` で指定された時間までの間に、キャンセルすることもできます。PaymentIntent を更新するか、またはそれを別の支払い方法で確定することでも、暗黙的に既存のコンビニ決済がキャンセルされます。 顧客が現在コンビニエンスストアでコンビニ決済による支払いを行っている場合、キャンセルリクエストは失敗します。顧客が決済の試行を放棄した場合や、払込取扱票の期限が切れた後に、キャンセルを再試行できる場合があります。 [支払い方法が一時的に利用できなくなる問題](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-handling-temporary-availability-issues)は、(明示的および暗黙的な) キャンセルリクエストにも影響することにご注意ください。 > 保留中の支払いをキャンセルすると、元の決済手順は無効になります。ほぼすべてのユースケースで、顧客にキャンセルについて連絡することをお勧めします。 > > ステータスが `requires_action` の PaymentIntent を正常に再確定すると、新しい指示と新しい `hosted_voucher_url` が作成されます。顧客がこれについて通知されていることを確認する必要があります。 ## 返金 Konbini での決済は、[ダッシュボード](https://dashboard.stripe.com/payments)または [API](https://docs.stripe.com/api.md#create_refund) から返金できます。 顧客の銀行口座に直接返金するには、顧客が返金先の口座情報を指定する必要があります。Stripe は支払い方法の請求詳細に登録されているメールアドレスを使用して顧客に連絡し、顧客に詳細情報をリクエストします。銀行口座情報を受け取ると、その後返金は自動的に処理されます。 返金のステータスは次のように移行します。 | イベント | 返金のステータス | | --------------------------------------- | ----------------- | | 返金が作成されました | `requires_action` | | 顧客が銀行口座の詳細を送信し、Stripe が返金の処理を開始します | `pending` | | 返金が顧客の銀行に入金される予定です | `succeeded` | | 顧客の銀行が資金を Stripe に戻します | `requires_action` | | 返金は、作成後 45 日間、`requires_action` です | `failed` | | 返金が `requires_action` ステータスからキャンセルされました | `canceled` | 顧客の銀行口座で送金に失敗した場合、資金は Stripe に戻り、返金のステータスは `requires_action` に変わります。これは、口座保有者の名前が受取人の銀行に登録されている名前と異なるか、指定した銀行口座番号に入力ミスがある場合に発生する可能性があります。この場合、Stripe から顧客に対し、メールで失敗の通知と銀行口座の詳細の再送依頼が行われます。 顧客から 45 日以内に銀行口座情報が提供されなかった場合、返金のステータスは `failed` に移行し、[refund.failed](https://docs.stripe.com/api/events/types.md#event_types-refund.failed) イベントが送信されます。この場合、Stripe は返金を処理できないため、[Stripe の外部で顧客に返金する](https://docs.stripe.com/refunds.md#failed-refunds)必要があります。 返金の [instructions_email](https://docs.stripe.com/api/refunds/object.md#refund_object-instructions_email) フィールドは、返金の送信先のメールアドレスです。返金が顧客からの応答を待機している間、顧客に送信されたメールの詳細も返金の [next_action.display_details.email_sent](https://docs.stripe.com/api/refunds/object.md#refund_object-next_action-display_details-email_sent) フィールドに示されます。 個々の返金 (一部返金を含む) ごとに手数料が発生する場合があります。詳細については、Stripe の担当者にお問い合わせください。 ### 返金をテストする テスト環境で返金の動作を確認するには、顧客に送信されたメールにリンクが記載された銀行アカウントの詳細収集ページで、以下のテスト用銀行口座を使用してください。これら以外の銀行口座の詳細は受け付けられません。 | 金融番号 | 口座 | 種別 | | --------- | ------------------------------------------------------------- | --------- | | `1100000` | `0001234` | 返金は成功します。 | | `1100000` | `1111113` `1111116` `1111113` `3333335` `4444440` | 返金は失敗します。 | #### 返金の有効期限をテストする API コールを実行して、テスト環境の返金の有効期限をシミュレーションできます。 ```bash curl https://api.stripe.com/v1/test_helpers/refunds/{{REFUND_ID}}/expire \ -X POST \ -u <>: ``` ## See also - [Checkout のフルフィルメント](https://docs.stripe.com/checkout/fulfillment.md) - [Checkout をカスタマイズする](https://docs.stripe.com/payments/checkout/customization.md) # ダイレクト API > This is a ダイレクト API for when payment-ui is direct-api. View the full page at https://docs.stripe.com/payments/konbini/accept-a-payment?payment-ui=direct-api. 日本の Stripe のユーザは、Payment Intents API および Payment Methods API を使用して、日本の顧客からコンビニ決済を受け付けることができます。顧客は日本のコンビニエンスストアで、支払いコードと確認番号を指定し、現金で支払います。支払いが完了すると、Stripe からお客様に通知が送られます。 ## Stripe を設定する [サーバ側] まず、Stripe アカウントが必要です。[今すぐ登録](https://dashboard.stripe.com/test/register)してください。 アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。 #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # If you use bundler, you can add this line to your Gemfile gem 'stripe' ``` ## PaymentIntent を作成する [サーバ側] Stripe は [PaymentIntent (支払いインテント)](https://docs.stripe.com/api/payment_intents.md) オブジェクトを使用して、顧客から支払いを回収するお客様の意図を示し、コンビニ決済の PaymentIntent の作成から完了までの状態の変化を追跡します。 サーバーで金額と `jpy` 通貨を使用して PaymentIntent を作成します (コンビニ決済は他の通貨をサポートしていません)。すでに [Payment Intents API](https://docs.stripe.com/payments/payment-intents.md) を使用した導入がある場合は、PaymentIntent の[決済手段タイプ](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_types)のリストに `konbini` を追加します。 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=jpy \ -d "payment_method_types[]=konbini" \ -d "payment_method_options[konbini][product_description]=Tシャツ" \ -d "payment_method_options[konbini][expires_after_days]=3" ``` ### client secret を取得する PaymentIntent には、*client secret* (The client secret is a unique key returned from Stripe as part of a PaymentIntent. This key lets the client access important fields from the PaymentIntent (status, amount, currency) while hiding sensitive ones (metadata, customer)) が含まれています。これは、支払いプロセスを安全に完了するためにクライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。 #### 1 ページのアプリケーション ブラウザーの `fetch` 関数を使用して、サーバーのエンドポイントから client secret を取得します。この方法は、クライアント側が 1 ページのアプリケーションで、特に React などの最新のフロントエンドフレームワークで構築されている場合に最適です。client secret を処理するサーバーのエンドポイントを作成します。 #### Ruby ```ruby get '/secret' do intent = # ... Create or retrieve the PaymentIntent {client_secret: intent.client_secret}.to_json end ``` その後、クライアント側で JavaScript を使用して client secret を取得します。 ```javascript (async () => { const response = await fetch('/secret'); const {client_secret: clientSecret} = await response.json(); // Render the form using the clientSecret })(); ``` #### サーバ側のレンダリング サーバーからクライアントに client secret を渡します。この方法は、アプリケーションがブラウザーへの送信前に静的なコンテンツをサーバーで生成する場合に最適です。 決済フォームに [client_secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) を追加します。サーバー側のコードで、PaymentIntent から client secret を取得します。 #### Ruby ```erb
``` ```ruby get '/checkout' do @intent = # ... Fetch or create the PaymentIntent erb :checkout end ``` ### その他の支払い方法オプション 支払い方法オプションは、[支払い方法オプション](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-konbini)の `konbini` キーで指定できます。 | フィールド | 値 | 必須 | デフォルト値 | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ---------- | | `expires_after_days` | 保留中のコンビニ決済の期限が切れるまでの日数。有効な値は 1 ～ 60 日です。[有効期限](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-additional-options-expiration)をご覧ください。 | いいえ | 3 | | `expires_at` | 保留中のコンビニ決済が期限切れとなる Unix タイムスタンプ。この有効期限は、現在時刻から 30 分後以降で、PaymentIntent に設定を適用してから 60 日以内にする必要があります。[有効期限](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-additional-options-expiration)をご覧ください。 | いいえ | 「設定解除」 | | `product_description` | コンビニエンスストアで顧客に表示される、最大 22 文字の商品の表記。シフト JIS ([JIS X 0208:1997](https://en.wikipedia.org/wiki/Shift_JIS)) 以外の文字が含まれていると、エラーが返されます。このオプションは必須ではありませんが、設定することをお勧めします。設定しない場合は、弊社の判断で選択された一般的なプレースホルダー (例: お買い上げ商品・サービス) が使用されます。 | いいえ | 「プレースホルダー」 | #### 有効期限 保留中のコンビニ決済は、指定した日付の真夜中 (23:59:59 JST) に期限切れになります。たとえば、`expires_after_days` に 2 が設定され、月曜日に PaymentIntent が確定された場合、保留中のコンビニ決済は水曜日の日本時間 (UTC+9) 23:59:59 に期限切れになります。 `expires_at` 設定は、秒単位の Unix タイムスタンプです。値が現在時刻から 30 分未満である場合、または有効期限の 30 分前以降に PaymentIntent の確定が発生した場合は、エラーが返されます。 `expires_after_days` と `expires_at` は相互排他的です。両方を設定するとエラーが返されます。また、どちらも省略可能であり、どちらも設定しなかった場合、有効期限は PaymentIntent の作成から 3 日後の日本時間 (UTC+9) 23:59 にデフォルト設定されます。 ### エラー処理 PaymentIntents の作成、更新、確定などのリクエストは失敗することがあります。API レスポンスの `error` 値を調査して原因を特定し、多くの場合、リクエストを再送信するか、エラーを修正できます。特に、決済手段のオプション `confirmation_number` を指定している場合は、当社が返す特定のエラーコードに対処することをお勧めします。詳細については、[確認番号](https://docs.stripe.com/payments/konbini/accept-a-payment.md#confirm-payment-intent-additional-options-confirmation-number)をご覧ください。 決済手段は、障害、定期メンテナンス、使用パターンによって、一時的に利用できなくなることがあります。詳細は、一時的な可用性の[問題に対処する](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-handling-temporary-availability-issues)]をご覧ください。 ## 支払い方法の詳細を収集する [クライアント側] クライアントで支払いフォームを作成し、必要な請求先情報を顧客から収集します。 | フィールド | 値 | | ------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `name` | 顧客の氏名。コンビニエンスストアの UI と領収書では最大 20 文字に切り詰められます。シフト JIS ([JIS X 0208:1997](https://en.wikipedia.org/wiki/Shift_JIS)) 以外の文字は、削除または置換されます。 | | `email` | 顧客の完全なメールアドレス。 | このフォームの例では電話番号も収集しています。顧客が提供する確認番号として使用します。 ```html
``` ## Stripe に支払いを送信する [クライアント側] 顧客がコンビニ決済をクリックしたら、Stripe.js を使用してその支払いを Stripe に送信します。[Stripe.js](https://docs.stripe.com/payments/elements.md) は、決済フローの構築に使用できる Stripe の基本的な JavaScript ライブラリです。 Stripe.js スクリプトを決済ページに含めるには、このスクリプトを HTML ファイルの `head` に追加します。 ```html Checkout ``` 決済ページで以下の JavaScript を使用して、Stripe.js のインスタンスを作成します。 ```javascript // Set your publishable key. Remember to switch to your live publishable key in production! // See your keys here: https://dashboard.stripe.com/apikeys const stripe = Stripe('<>'); ``` 顧客の請求先情報を送信するには、[stripe.confirmKonbiniPayment](https://docs.stripe.com/js/payment_intents/confirm_konbini_payment) と、[ステップ 2](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-create-payment-intent) で作成した PaymentIntent オブジェクトの [client secret](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-client_secret) を使用します。 確定されると、Stripe はモーダルを自動的に開き、顧客にコンビニ決済の手順を表示します。 ```javascript const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const result = await stripe.confirmKonbiniPayment( '{{PAYMENT_INTENT_CLIENT_SECRET}}', { payment_method: { billing_details: { name: document.getElementById('name').value, email: document.getElementById('email').value, }, }, payment_method_options: { konbini: { confirmation_number: document.getElementById('phone').value.replace(/\D/g,''), }, }, } ); // Stripe.js will open a modal to display the Konbini payment instructions to your customer // This async function finishes when the customer closes the modal if (result.error) { // Display error to your customer const errorMsg = document.getElementById('error-message'); errorMsg.innerText = result.error.message; } }); ``` > `stripe.confirmKonbiniPayment` の完了には数秒かかる場合があります。この間、フォームが再送信されないように無効化し、スピナーのような待機中のインジケータを表示します。エラーが発生した場合は、それを顧客に表示し、フォームを再度有効化し、待機中のインジケータを非表示にします。 ### その他の支払い方法オプション Konbini PaymentIntent を確定する際に、[支払い方法オプション](https://docs.stripe.com/api/payment_intents/confirm.md#confirm_payment_intent-payment_method_options-konbini)の `konbini` キーで、その他の支払い方法オプションを指定できます。 | フィールド | 値 | 必須 | デフォルト値 | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ------ | | `confirmation_number` | 10 ～ 11 桁の数値文字列です。この文字列は支払い手順にも表示され、0 のみで構成することはできません。`confirmation_number` の値を指定しない場合、Stripe は番号をランダムに生成します。詳細は、[確認番号](https://docs.stripe.com/payments/konbini/accept-a-payment.md#confirm-payment-intent-additional-options-confirmation-number)をご覧ください。 | いいえ | 「設定解除」 | #### 確認番号 顧客は支払いの実行時に `confirmation_number` を参照する必要があります。この値を設定するか、顧客に設定を許可する場合に一般的に推奨される値は、顧客の電話番号です。`confirmation_number` は、サーバー側での PaymentIntent の作成時に設定することもできますが、一般的には、クライアント側で顧客が PaymentIntent を確定する際に設定することです。PaymentIntent の作成時に設定された番号は、確定までのすべての段階で更新される可能性があります。 指定した `confirmation_number` が進行中のすべてのコンビニエンスストア取引において使用される可能性が高い番号である場合は、PaymentIntent の確定時点で拒否される可能性があります。この場合、PaymentIntent の確定時にのみ想定されるエラーコード `payment_intent_konbini_rejected_confirmation_number` が返されます。 Stripe は、PaymentIntent の作成時、および更新と確定の際に、ゼロのみで構成される確認番号を予防的にブロックします。この値を設定したり、顧客に設定を許可しないようにしてください。 ### エラー処理 クライアント側での PaymentIntent の確定も失敗することがあります。`error` 戻り値を調べて原因を特定し、必要に応じて顧客にエラーを表示するか、エラーを修正して再試行してください。 ## Optional: 顧客に独自のコンビニ決済の手順を表示する [クライアント側] `confirmKonbiniPayment` でコンビニ決済の手順の表示を処理するには、Stripe.js を利用することをお勧めします。ただし、次の方法で顧客に手動で支払い手順を表示することもできます。 顧客へのコンビニ決済の詳細表示に続くアクションに手動で対応するには、[ステップ 4](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-submit-payment) で `stripe.confirmKonbiniPayment` を呼び出す際に、`handleActions: false` を使用します。 ```javascript const form = document.getElementById('payment-form'); form.addEventListener('submit', async (event) => { event.preventDefault(); const result = await stripe.confirmKonbiniPayment( '{{PAYMENT_INTENT_CLIENT_SECRET}}', { payment_method: { billing_details: { name: document.getElementById('name').value, email: document.getElementById('email').value, }, }, payment_method_options: { konbini: { confirmation_number: document.getElementById('phone').value.replace(/\D/g,''), }, }, }, {handleActions: false}, ); // This async function finishes when the PaymentIntent is confirmed if (result.error) { // Display error to your customer var errorMsg = document.getElementById('error-message'); errorMsg.innerText = result.error.message; } else { // A Konbini PaymentIntent was successfully created var amount = result.paymentIntent.amount; var currency = result.paymentIntent.currency; var details = result.paymentIntent.next_action.konbini_display_details; for (var store in details.stores) { // Do something with each store's details } var expires_at = details.expires_at; // Display Konbini details to end customer } }); ``` ### 表示 顧客に支払い手順をどのように表示するかを指定します。手順には少なくとも次を含める必要があります。 - 商品の説明、金額、支払いの有効期限など、購入に関連する一般的な情報。 - PaymentIntent の確定により取得された、各コンビニエンスストアチェーンの支払いコードおよび確認番号。 - コンビニ決済を実行する方法を示した顧客向けの手順。支払い手順の例を以下に示します。 ### コンビニ決済の手順 1. 支払いに利用するコンビニエンスストアチェーンの支払いコードと確認番号を確認します。 1. コンビニエンスストアで、支払い端末か、レジで支払いコードと確認番号を指定します。 1. 支払いが完了したら、記録のために領収書を保管しておきます。 1. ご不明な点がございましたら、お問い合わせください。 ## Optional: サーバーから Stripe に支払いを送信する [サーバー側] クライアント側で [stripe.confirmKonbiniPayment](https://docs.stripe.com/js/payment_intents/confirm_konbini_payment) を使用してコンビニ決済を処理するには、Stripe.js を使用することをお勧めします。Stripe.js を使用すると、他の決済手段にも簡単に対応できるようになります。ただし、以下のステップに従って、お客様のサーバーに顧客を手動でリダイレクトすることも可能です。 - タイプが `konbini` の [PaymentIntent (支払いインテント)](https://docs.stripe.com/api/payment_intents/object.md) を作成する際に、`confirm` を `true` に設定するか、既存の PaymentIntent を[確定](https://docs.stripe.com/api/payment_intents/confirm.md)します。`payment_method_data.billing_details.name` プロパティと `payment_method_data.billing_details.email` プロパティを指定する必要があります。オプションで、`payment_method_options.konbini.confirmation_number` またはその他の [payment_method_options](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-additional-options) を設定することもできます。`payment_method_data` を指定すると、*PaymentMethod* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) が作成され、この PaymentIntent ですぐに使用されます。 ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=1099 \ -d currency=jpy \ -d confirm=true \ -d "payment_method_types[]=konbini" \ -d "payment_method_data[type]=konbini" \ -d "payment_method_data[billing_details][name]=Jenny Rosen" \ --data-urlencode "payment_method_data[billing_details][email]=jenny@example.com" ``` 作成される `PaymentIntent` のステータスは `requires_action` であり、`next_action` のタイプは `konbini_display_details` です。 #### Json ```json {"status": "requires_action", "next_action": { "type": "konbini_display_details", "konbini_display_details": { "expires_at": 1642431599, "hosted_voucher_url": "https://payments.stripe.com/konbini/voucher/...", "stores": { "familymart": { "confirmation_number": "12345678901", "payment_code": "123456" }, ... } } }, "id": "pi_1G1sgdKi6xqXeNtkldRRE6HT", "object": "payment_intent", "amount": 1099, "client_secret": "pi_1G1sgdKi6xqXeNtkldRRE6HT_secret_h9B56ObhTN72fQiBAuzcVPb2E", "confirmation_method": "automatic", "created": 1642126547, "currency": "jpy", "livemode": true, "charges": { "data": [], "object": "list", "has_more": false, "url": "/v1/charges?payment_intent=pi_1G1sgdKi6xqXeNtkldRRE6HT" }, "payment_method_options": { "konbini": { "confirmation_number": null, "expires_after_days": null, "expires_at": null, "product_description": null } }, "payment_method_types": [ "konbini" ] } ``` - `next_action.konbini_display_details.hosted_voucher_url` プロパティーで指定した URL に顧客をリダイレクトします。ここで示すコード例はおおまかなものであり、リダイレクト方法は、ご使用のウェブフレームワークによって異なる場合があります。 #### Ruby ```ruby if payment_intent.status == 'requires_action' && payment_intent.next_action.type == 'konbini_display_details' url = payment_intent.next_action.konbini_display_details.hosted_voucher_url redirect(url) end ``` 支払いのステータスを確認するには、[Webhook を利用](https://docs.stripe.com/payments/payment-intents/verifying-status.md#webhooks)することをお勧めします。 ## Optional: 支払い手順をカスタマイズする [ブランディング設定](https://dashboard.stripe.com/account/branding)ページを使用して、顧客に表示される内容をカスタマイズできます。[Customer (顧客)](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) が PaymentIntent にリンクされている場合、オンラインで提供される支払い手順では顧客の利用言語が使用されます。それ以外の場合は顧客のブラウザーの言語が使用されます。 オンラインで提供される支払い手順には、以下のブランド設定を適用できます。 - **アイコン**: ブランド画像と公開ビジネス名 - **ロゴ**: ブランド画像 - **アクセント**: 印刷ボタンのカラー - **ブランドカラー**: 背景色 ## Optional: 支払い手順メールを送信する ダッシュボードの[メール設定](https://dashboard.stripe.com/settings/emails)ページで、コンビニ決済の手順メールとリマインドメールを有効にできます。手順メールを有効にすると、Stripe は、PaymentIntent の確定時に支払い手順のメールを送信します。メールには、コンビニエンスストアでの支払いに必要な支払いコード、確認番号、その他の詳細が含まれます。オンラインで提供される支払い手順ページへのリンクも含まれます。 ## Optional: リマインドメールを送信する ダッシュボードの[メール設定](https://dashboard.stripe.com/settings/emails)ページで、支払いのリマインドメールを有効にして、PaymentIntent ごとのリマインドメールの最大件数を設定できます。Stripe は、支払いが成功、期限切れ、またはキャンセルになるまで、最大で 1 日に 1 回リマインドメールを送信します。 > テスト環境では、手順メールとリマインドメールは Stripe アカウントに関連付けられたメールアドレスにのみ送信されます。 ## 支払い後のイベントを処理する [サーバー側] コンビニ決済は[通知遅延型](https://docs.stripe.com/payments/payment-methods.md#payment-notification)の決済手段であるため、売上はすぐには利用可能になりません。顧客が購入操作直後にはコンビニエンスストアで保留中のコンビニ決済に対する支払いを実行しない場合があります。 保留中のコンビニ決済が完了すると、Stripe はその [payment_intent.succeeded](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.succeeded) イベントを送信します。ダッシュボードを使用するか、*Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) ハンドラーを構築して、これらのイベントを受信し、アクション (顧客への注文確認メールの送信、データベースへの売上の記録、配送ワークフローの開始など) を実行します。 Stripe は、保留中のコンビニ決済が完了していないことが確実と見込まれるようになった場合 (通常は有効期限の約 1 時間後)、[payment_intent.payment_failed](https://docs.stripe.com/api/events/types.md#event_types-payment_intent.payment_failed) イベントを送信します。 | イベント | 説明 | 次のステップ | | -------------------------------- | ---------------------------------------- | ------------------------------------------------------- | | `payment_intent.requires_action` | 保留中のコンビニ決済が作成されています。 | オプションとして、顧客に支払い手順のページを送信します。顧客がコンビニ決済に対する支払いを行うまで待機します。 | | `payment_intent.succeeded` | 顧客は有効期限が切れる前に保留中のコンビニ決済に対する支払いを行っています。 | 顧客が購入した商品またはサービスのフルフィルメントを行います。 | | `payment_intent.payment_failed` | 顧客は有効期限が切れる前に保留中のコンビニ決済に対する支払いを行いませんでした。 | 顧客にメールまたはプッシュ通知で連絡し、別の支払い方法をリクエストします。 | > テスト中、`email` など、送信されたパラメーターに基づいて Konbini PaymentIntent のステータスが自動的に変わる場合があります。更新内容は[ダッシュボード](https://dashboard.stripe.com/test/payments)で確認できます。詳細については、[実装内容をテストする](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-test-integration)をご覧ください。 ### イベントを受信し、ビジネスアクションを実行する #### 手動 Stripe ダッシュボードを使用して、Stripe のすべての支払いの確認、メール領収書の送信、入金処理、失敗した支払いの再試行を実行します。 - [ダッシュボードでテスト支払いを確認する](https://dashboard.stripe.com/test/payments) #### カスタムコード Webhook ハンドラーを構築してイベントをリッスンし、非同期型のカスタムの決済フローを作成します。Stripe CLI を使用して、ローカルで Webhook の組み込みのテストとデバッグを行います。 - [Build a custom webhook](https://docs.stripe.com/webhooks/handling-payment-events.md#build-your-own-webhook) ## 組み込みをテストする テスト時、[stripe.confirmKonbiniPayment](https://docs.stripe.com/js/payment_intents/confirm_konbini_payment) をコールするときに `payment_method.billing_details.email` に以下の値を設定して、さまざまなシナリオをテストします。特殊な確認番号とメールパターンのいずれかを使用してテストできます。両方を指定した場合は、特殊な確認番号の動作が適用されます。 | メールアドレス | 確認番号 | 説明 | | ---------------------------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `{any_prefix}@{any_domain}` | `11111111110` | 3 分後に成功し、その後 `payment_intent.succeeded` Webhook を受信するコンビニ決済をシミュレーションします。 例: hanako@test.com | | `{any_prefix}succeed_immediately@{any_domain}` | `22222222220` | 即座に成功し、その後 `payment_intent.succeeded` Webhook を受信するコンビニ決済をシミュレーションします。 例: succeed_immediately@test.com | | `{any_prefix}expire_immediately@{any_domain}` | `33333333330` | 即座に有効期限が切れ、その後 `payment_intent.payment_failed` Webhook を受信するコンビニ決済をシミュレーションします。 [支払い方法オプション](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-konbini-expires_after_days)で `expires_after_days` や `expires_at` のパラメーターに設定された値に関係なく、[next_action.konbini_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-konbini_display_details-expires_at) の `expires_at` フィールドは現在の時刻に設定されます。 例: expire_immediately@test.com | | `{any_prefix}expire_with_delay@{any_domain}` | `44444444440` | 成功することなく、3 分後に有効期限が切れ、その後 `payment_intent.payment_failed` Webhook を受信するコンビニ決済をシミュレーションします。 [支払い方法オプション](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-konbini-expires_after_days)で `expires_after_days` や `expires_at` のパラメーターに設定された値に関係なく、[next_action.konbini_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-konbini_display_details-expires_at) の `expires_at` フィールドは 3 分後に設定されます。 例: expire_with_delay@test.com | | `{any_prefix}fill_never@{any_domain}` | `55555555550` | コンビニ決済を成功させずにシミュレーションを実行します。[支払い方法オプション](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method_options-konbini-expires_after_days)で指定されたパラメーターに基づき、`next_action.konbini_display_details` の `expires_at` フィールドに従って有効期限が切れ、その後 `payment_intent.payment_failed` Webhook が届きます。 例: fill_never@test.com | [確認番号](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-confirm-payment-intent-additional-options-confirmation-number)のエラー処理をテストするには、`payment_method_options[confirmation_number]` に以下の値を使用できます。 - `01234567890` は `payment_intent_konbini_rejected_confirmation_number` エラーコードを発生します。 - `00000000000` は汎用的な検証エラーコードになります。組み込みで事前検証を使用して、このエラーを回避する必要があります。 ## 有効期限とキャンセル `expires_at` の値で指定された [next_action.konbini_display_details](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action-konbini_display_details-expires_at) の期限を過ぎると、顧客はコンビニエンスストアのキオスクで、保留中のコンビニ決済の処理を_「開始」*できなくなります。ただし、期限が切れる前に有効な払込取扱票を発行した場合には、`expires_at` の後でもレジで決済を*「完了」_できます。 このような場合に備え、早期に支払いが失敗しないように、バッファーの時間が設けられています。PaymentIntent のステータスは `requires_payment_method` に変わります。この時点では、別の支払い方法を指定して PaymentIntent を確定するか、キャンセルできます。 保留中のコンビニ決済は、確定後 `next_action.konbini_display_details.expires_at` で指定された時間までの間に、キャンセルすることもできます。PaymentIntent を更新するか、またはそれを別の支払い方法で確定することでも、暗黙的に既存のコンビニ決済がキャンセルされます。 顧客が現在コンビニエンスストアでコンビニ決済による支払いを行っている場合、キャンセルリクエストは失敗します。顧客が決済の試行を放棄した場合や、払込取扱票の期限が切れた後に、キャンセルを再試行できる場合があります。 [支払い方法が一時的に利用できなくなる問題](https://docs.stripe.com/payments/konbini/accept-a-payment.md#web-handling-temporary-availability-issues)は、(明示的および暗黙的な) キャンセルリクエストにも影響することにご注意ください。 > 保留中の支払いをキャンセルすると、元の決済手順は無効になります。ほぼすべてのユースケースで、顧客にキャンセルについて連絡することをお勧めします。 > > ステータスが `requires_action` の PaymentIntent を正常に再確定すると、新しい指示と新しい `hosted_voucher_url` が作成されます。顧客がこれについて通知されていることを確認する必要があります。 ## 提供状況の一時的な問題を処理する 次のエラーコードは、支払い方法の可用性における一時的な問題を示しています。 | コード | 説明 | 処理 | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `payment_method_rate_limit_exceeded` | この支払い方法には、Stripe の [API 全体のレート制限](https://docs.stripe.com/rate-limits.md)よりも厳しい制限が適用されていますが、大量のリクエストが立て続けに実行されました。 | 通常、バックオフで再試行すればこの状況は解消されます。ただし、対象の支払い方法で使用量が高い状態が長時間続く場合 (Web サイトでセールが実施されているなど)、これらのエラーは一定のリクエストで継続することがあります。その場合は、顧客に別の支払い方法の選択を検討してもらうことで、対応できる可能性があります。 | | `payment_method_not_available` | 支払い方法で原因不明の一時的な問題が発生しており、これがしばらく続く可能性があります (システム障害の間または定期メンテナンス期間など)。 | 別の決済手段で購入を完了するようにユーザーを招待するか、しばらくしてからもう一度試してもらうことをお勧めします。 | > 全般的に、または今後のイベントで使用量が高くなることが想定される場合は、事前にお問い合わせください。 ## 返金 Konbini での決済は、[ダッシュボード](https://dashboard.stripe.com/payments)または [API](https://docs.stripe.com/api.md#create_refund) から返金できます。 顧客の銀行口座に直接返金するには、顧客が返金先の口座情報を指定する必要があります。Stripe は支払い方法の請求詳細に登録されているメールアドレスを使用して顧客に連絡し、顧客に詳細情報をリクエストします。銀行口座情報を受け取ると、その後返金は自動的に処理されます。 返金のステータスは次のように移行します。 | イベント | 返金のステータス | | --------------------------------------- | ----------------- | | 返金が作成されました | `requires_action` | | 顧客が銀行口座の詳細を送信し、Stripe が返金の処理を開始します | `pending` | | 返金が顧客の銀行に入金される予定です | `succeeded` | | 顧客の銀行が資金を Stripe に戻します | `requires_action` | | 返金は、作成後 45 日間、`requires_action` です | `failed` | | 返金が `requires_action` ステータスからキャンセルされました | `canceled` | 顧客の銀行口座で送金に失敗した場合、資金は Stripe に戻り、返金のステータスは `requires_action` に変わります。これは、口座保有者の名前が受取人の銀行に登録されている名前と異なるか、指定した銀行口座番号に入力ミスがある場合に発生する可能性があります。この場合、Stripe から顧客に対し、メールで失敗の通知と銀行口座の詳細の再送依頼が行われます。 顧客から 45 日以内に銀行口座情報が提供されなかった場合、返金のステータスは `failed` に移行し、[refund.failed](https://docs.stripe.com/api/events/types.md#event_types-refund.failed) イベントが送信されます。この場合、Stripe は返金を処理できないため、[Stripe の外部で顧客に返金する](https://docs.stripe.com/refunds.md#failed-refunds)必要があります。 返金の [instructions_email](https://docs.stripe.com/api/refunds/object.md#refund_object-instructions_email) フィールドは、返金の送信先のメールアドレスです。返金が顧客からの応答を待機している間、顧客に送信されたメールの詳細も返金の [next_action.display_details.email_sent](https://docs.stripe.com/api/refunds/object.md#refund_object-next_action-display_details-email_sent) フィールドに示されます。 個々の返金 (一部返金を含む) ごとに手数料が発生する場合があります。詳細については、Stripe の担当者にお問い合わせください。 ### 返金をテストする テスト環境で返金の動作を確認するには、顧客に送信されたメールにリンクが記載された銀行アカウントの詳細収集ページで、以下のテスト用銀行口座を使用してください。これら以外の銀行口座の詳細は受け付けられません。 | 金融番号 | 口座 | 種別 | | --------- | ------------------------------------------------------------- | --------- | | `1100000` | `0001234` | 返金は成功します。 | | `1100000` | `1111113` `1111116` `1111113` `3333335` `4444440` | 返金は失敗します。 | #### 返金の有効期限をテストする API コールを実行して、テスト環境の返金の有効期限をシミュレーションできます。 ```bash curl https://api.stripe.com/v1/test_helpers/refunds/{{REFUND_ID}}/expire \ -X POST \ -u <>: ```