Checkoutと Payment Link の支払いのフルフィルメントを履行

Checkout の決済フルフィルメントを履行するための関数をサーバーに作成します。この関数は Webhook によってトリガーされ、顧客が Checkout の決済フルフィルメントを完了した後、お客様のウェブサイトに転送されたときに呼び出されます。このガイドでは、この関数を fulfill_checkout と呼びますが、関数には任意の名前を指定できます。

fulfill_checkout 関数は以下を満たしている必要があります。

1. 同じ Checkout セッション ID で複数回呼び出される場合に適切に処理します。
2. 引数として Checkout セッション ID を受け入れます。
3. line_items プロパティを拡張して、API から Checkout セッションを取得します。
4. payment_status プロパティを確認して、フルフィルメントが必要かどうかを判断します。
5. ラインアイテムのフルフィルメントを履行します。
6. 指定した Checkout セッションのフルフィルメントのステータスを記録します。

以下のコードを fulfill_checkout 関数の開始点として使用します。 TODO コメントは、実装する必要のある機能を示します。

def fulfill_checkout(session_id)
  # Set your secret key. Remember to switch to your live secret key in production.
  # See your keys here: https://dashboard.stripe.com/apikeys
  Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

  puts "Fullfilling Checkout Session #{session_id}"

  # TODO: Make this function safe to run multiple times,
  # even concurrently, with the same session ID

  # TODO: Make sure fulfillment hasn't already been
  # peformed for this Checkout Session

  # Retrieve the Checkout Session from the API with line_items expanded
  checkout_session = Stripe::Checkout::Session.retrieve({
    id: session_id,
    expand: ['line_items'],
  })

  # Check the Checkout Session's payment_status property
  # to determine if fulfillment should be peformed
  if checkout_session.payment_status != 'unpaid'
    # TODO: Perform fulfillment of the line items

    # TODO: Record/save fulfillment status for this
    # Checkout Session
  end
end

受け付ける支払い方法とビジネスニーズに応じて、fulfill_checkout 関数に以下の処理を実行させることができます。

• サービスへのアクセスを提供します。
• 商品の配送をトリガーします。
• 支払いの詳細とラインアイテムのコピーをお客様のデータベースに保存します。
• Stripe の領収書が有効になっていない場合に、カスタムの領収書メールを顧客に送信します。
• 顧客が Checkout で数量を調整できるようにする場合、ラインアイテムと購入数量を照合します。
• 在庫または在庫記録を更新します。

フルフィルメントをトリガーするには、Webhook イベントハンドラーを作成して支払いイベントをリッスンし、fulfill_checkout 関数をトリガーします。

誰かが Checkout を利用して支払いを行うと、checkout.session.completed イベントが作成されます。これらのイベントの受信を受け付け、処理し、確認するためのエンドポイントをサーバーに設定します。

ACH ダイレクトデビット やその他の銀行振込など、一部の支払い方法は直ちに行われません。決済完了後、売上はすぐには利用可能になりません。遅延型の支払い方法は、後で支払いが完了したときに checkout.session.async_payment_succeeded イベントを生成します。

require 'sinatra'

# Use the secret provided by Stripe CLI for local testing
# or your webhook endpoint's secret.
endpoint_secret = 'whsec_...'

post '/webhook' do
  event = nil

  # Verify webhook signature and extract the event
  # See https://stripe.com/docs/webhooks#verify-events for more information.
  begin
    sig_header = request.env['HTTP_STRIPE_SIGNATURE']
    payload = request.body.read
    event = Stripe::Webhook.construct_event(payload, sig_header, endpoint_secret)
  rescue JSON::ParserError => e
    # Invalid payload
    return status 400
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    return status 400
  end

  if event['type'] == 'checkout.session.completed' ||
  event['type'] == 'checkout.session.async_payment_succeeded'
    fulfill_checkout(event['data']['object']['id'])
  end

  status 200
end

checkout.session.async_payment_failed イベントをリッスンして処理することもできます。たとえば、遅延型の支払いが失敗した場合に顧客にメールを送信できます。

Webhook イベントハンドラーを開発、テストするための最も簡単な方法は、Stripe CLI を使用することです。Stripe CLI をお持ちでない場合は、インストールガイド に従ってインストールしてください。

Stripe CLI がインストールされている場合は、イベントハンドラーをローカルでテストできます。サーバーを (localhost:4242 などで) 実行し、次に stripe listen コマンドを実行すると、Stripe CLI がイベントをローカルサーバーに転送します。

stripe listen --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is 'whsec_<REDACTED>' (^C to quit)

Webhook シークレット (whsec_...) をイベント処理コードに追加し、顧客として Checkout を実行してフルフィルメントをテストします。

• 決済ボタンを押すと、Checkout に移動するか、または Payment Links にアクセスします
• Checkout で次のテストデータを入力します。
  • カード番号として 4242 4242 4242 4242 を入力する
  • カードの有効期限として任意の将来の日付を入力する
  • 任意の 3 桁のセキュリティコードを入力する
  • 請求先の任意の郵便番号 (90210) を入力する
• 支払うボタンを押す

支払いが完了したら、以下を確認します。

• stripe listen が実行されているコマンドラインには、ローカルサーバーに転送された checkout.session.completed イベントが表示されます。
• サーバーログには、fulfill_checkout 関数からの想定出力が表示されます。

ローカルでテストした後、Webhook イベントハンドラーをサーバで設定して実行します。次に、Webhook エンドポイントを作成して checkout.session.completed イベントをサーバーに送信し、 決済フローを再度テストします。

Checkout を設定することで、顧客の決済完了後にお客様のウェブサイトのページを送信します。ページの URL に {CHECKOUT_SESSION_ID} プレースホルダーを含めると、顧客が Checkout からリダイレクトされるときにプレースホルダーが Checkoutセッション ID に置き換えられます。

ホストされた Checkout

デフォルトの ui_mode が hosted の Checkout セッションでは、success_url を設定します。

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  --data-urlencode success_url="https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}"

デフォルト以外の ui_mode での決済フロー

ui_mode が hosted に設定されていない Checkout セッションでは、return_url を設定します。

curl https://api.stripe.com/v1/checkout/sessions \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d mode=payment \
  -d ui_mode=embedded \
  --data-urlencode return_url="https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}"

Payment Links

API を使用して作成する Payment Links の場合、after_completion.redirect.url を設定します。

curl https://api.stripe.com/v1/payment_links \
  -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:" \
  -d "line_items[0][price]"=
{{PRICE_ID}} \
  -d "line_items[0][quantity]"=1 \
  -d "after_completion[type]"=redirect \
  --data-urlencode "after_completion[redirect][url]"="https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID}"

Payment Links の場合、次のようにダッシュボードで作成します。

1. 支払い後タブに移動します。
2. 確認ページを表示しないを選択します。
3. {CHECKOUT_SESSION_ID} プレースホルダーが含まれたランディングページの URL を指定します (例: https://example.com/after-checkout?session_id={CHECKOUT_SESSION_ID})。

Webhook のリッスン は、各支払いのフルフィルメントを常にトリガーするために必要ですが、Webhook は遅延することがあります。決済フローを最適化し、顧客がアクセスしているときにすぐにフルフィルメントを履行できるようにするには、ランディングページからもフルフィルメントをトリガーする必要があります。

前のステップで指定した URL の Checkout セッション ID を使用して、以下を実行します。

1. サーバーが Checkou tランディングページに対するリクエストを受信したら、URL から Checkout セッション ID を抽出します。
2. 指定した ID を使用して fulfill_checkout 関数を実行します。
3. フルフィルメントの試行が完了した後、ページをレンダリングします。

ランディングページをレンダリングする際、以下を表示できます。

• フルフィルメントプロセスの詳細。
• 顧客が現在アクセスできるサービスのリンクまたは情報。
• 物品の配送またはロジスティクスの詳細。