# Issuing のリアルタイムのオーソリ

リアルタイムのオーソリについてご紹介します。

同期 Webhook は、承認リクエストにのみ使用されます。その他の通知はすべて、通常の Webhook エンドポイントに送信されます。連携状況を良好に保つため、[Webhook レスポンスをモニタリング](https://docs.stripe.com/issuing/controls/real-time-authorizations.md#monitor-your-webhook-responses)してください。

同期型の Webhook を使用すると、オーソリリクエストをリアルタイムで承認または拒否できます。

Webhook エンドポイントは、[設定](https://dashboard.stripe.com/account/issuing)で設定できます。カードを使用した購入が行われると、Stripe は `issuing_authorization.request` を作成し、お客様の承認を受けるために設定済みのエンドポイントに送信します。

[リアルタイムのオーソリの対話型ガイド](https://docs.stripe.com/issuing/controls/real-time-authorizations/quickstart.md)を参照して開始してください。

## オーソリリクエストへの応答

Webhook イベントに直接応答することで、オーソリリクエストに応答できます。

### 直接応答する

オーソリリクエストを受信後に、`issuing_authorization.request` Webhook イベントに直接応答して承認または拒否します。

#### Webhook の応答

Webhook は、以下のパラメーターが指定された `JSON` レスポンスを受け入れます。

**ステータスコード:** 成功を示す場合は `200` を返します。

**ヘッダー:**

| フィールド名             | 必須またはオプション | 説明                                                                             |
| ------------------ | ---------- | ------------------------------------------------------------------------------ |
| **Stripe-Version** | 必須         | 対応している値については、[API のバージョン管理](https://docs.stripe.com/api/versioning.md)をご覧ください。 |
| **コンテンツタイプ**       | オプション      | オーソリ Webhook の応答で受け入れられる唯一のコンテンツタイプは `application/json` です。                    |

**本文:**

| フィールド名                                | 必須またはオプション | タイプ                                                    | 説明                                                                                                                    |
| ------------------------------------- | ---------- | ------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- |
| **approved**                          | 必須         | ブール値                                                   | オーソリを承認する場合は `true` に設定し、拒否する場合は `false` に設定します。                                                                      |
| **amount**                            | オプション      | 整数                                                     | オーソリの `pending_request.is_amount_controllable` プロパティが `true` である場合、この値を指定して、オーソリように保持しておく金額を管理できます。値はプラスの値にする必要があります。 |
| **metadata**                          | オプション      | [キーと値のペア](https://docs.stripe.com/api/metadata.md)のセット | これは、オブジェクトに関する追加情報を構造化された形式で保存する場合に便利です。                                                                              |
| **send\_fraud\_challenges**(公開プレビュー版) | オプション      | 文字列の配列                                                 | このオーソリに関する不正利用のチャレンジを送信するには、SMS から行う必要があります。チャレンジを送信しない場合、空欄にします。                                                     |

#### Ruby

```ruby
# Using Sinatra.
require 'sinatra'
require 'stripe'

set :port, 4242

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
Stripe.api_key = '<<YOUR_SECRET_KEY>>'

# Replace with a real secret. You can find your endpoint's secret in your webhook settings.
webhook_secret = 'whsec_...'

post '/webhook' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']

  event = nil

  # Verify webhook signature and extract the event.
  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, webhook_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload.
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature.
    status 400
    return
  end

  if event['type'] == 'issuing_authorization.request'
    auth = event['data']['object']
    # ... custom business logic

    status 200
    header 'Stripe-Version' => '2025-03-31.basil', 'Content-Type' => 'application/json'
    data = { 'approved' => true }
    body data.to_json
  end
  # ...handle other cases
end
```

Stripe が 2 秒以内に承認または却下の応答を受信しない場合、`Authorization` は [timeout settings](https://dashboard.stripe.com/account/issuing) に基づいて自動的に承認または拒否されます。設定されている場合は、[Autopilot settings](https://docs.stripe.com/issuing/controls/real-time-authorizations.md#autopilot) に基づきます。

> 発行残高の資金が今後のオーソリに不足している場合、オーソリは拒否され、Webhook エンドポイントは `issuing_authorization.request` イベントを受け取りません。発行残高への資金追加について、詳細は[こちら](https://docs.stripe.com/issuing/funding/balance.md)をご覧ください。

## オーソリリクエスト

オーソリリクエストが Webhook に送信されると、リクエストされた `amount` は `pending_request` に保存されます。

```json
{
  "id": "iauth_1CmMk2IyNTgGDVfzFKlCm0gU",
  "object": "issuing_authorization",
  "approved": false,
  "amount": 0,
  "currency": "usd",
  "status": "pending",
  ...
  "pending_request": {"amount": 400,
    "currency": "usd",
    "merchant_amount": 360,
    "merchant_currency": "gbp"
  }
}
```

リクエストの最上位の `amount` は 0 に設定され、`approved` は false です。リクエストに応答すると、最上位の `amount` が承認または拒否された合計金額を反映し、`approved` フィールドが更新され、`pending_request` が null に設定されます。

### Ｗebhook をローカルでテストする

Webhook をローカルでテストするには、[Stripe CLI](https://docs.stripe.com/stripe-cli.md) を使用できます。Stripe CLI をインストールすると、イベントをサーバーに転送できます。

```bash
stripe listen --forward-to localhost:4242/webhook
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
```

別の端末で CLI から手動で `issuing_authorization.request` イベントをトリガーして、より効率的なテストを行うことができます。

```bash
stripe trigger issuing_authorization.request
```

[Webhook の設定](https://docs.stripe.com/webhooks.md)についてもっと知る。

## Webhook レスポンスを監視する

`issuing_authorization.created` および `issuing_authorization.updated` の Webhook イベントに登録して、タイムアウトやエラーをモニタリングしてください。[request_history.reason](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason) プロパティが `webhook_error` または `webhook_timeout` の場合、Stripe はレスポンスを受信できていません。エラー発生時は Autopilot が代理で承認を行うことがあるため、連携状況の判断に `approved` の値だけを信頼しないでください。たとえば、承認結果が `approved: true` であっても、`request_history.reason: webhook_error` となっている場合は調査が必要です。詳細なエラーメッセージは、[request_history.reason_message](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason_message) フィールドに表示されます。

## Autopilot(公開プレビュー版)

Autopilot にはフォールバックオプションが用意されており、システムがダウンした場合や、オーソリリクエストに応答しない場合、または無効なレスポンスを返した場合でも、リアルタイムでオーソリの判断を続行できるようになっています。

Autopilot は、定義済みの一連のルールに基づき、ユーザーに代わってオーソリの判断を行います。Autopilot の取引を照合するために、送信用の `Authorization` オブジェクトが作成されます。Autopilot がオーソリを承認または拒否すると、`issuing_authorization.created` Webhook の [request_history.reason](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason) プロパティは `webhook_error` または `webhook_timeout` になります。

- `webhook_error`: [リクエストヘッダー](https://docs.stripe.com/issuing/controls/real-time-authorizations.md#respond-directly)に無効な [Stripe API バージョン](https://docs.stripe.com/api/versioning.md)を指定してリアルタイムオーソリ Webhook に応答した場合、または Stripe がレスポンスを処理できない場合。
- `webhook_timeout`: その他すべての支払い失敗モードの場合。

Autopilot を設定するには、[Stripe サポートに問い合わせ](https://support.stripe.com/contact/login)て、[監視](https://docs.stripe.com/issuing/controls/real-time-authorizations.md#monitor-your-webhook-responses)してください。

## Stripe Autopilot (パブリックプレビュー版)

専用の銀行識別番号 (BIN) を持つユーザーの場合、カードネットワークが Stripe に到達できない場合に Stripe Autopilot がオーソリの判断を支援します。

Stripe のサービスが停止しているときに Stripe Autopilot によってオーソリが承認または拒否されると、`issuing_authorization.created` Webhook の [request_history.reason](https://docs.stripe.com/api/issuing/authorizations/object.md#issuing_authorization_object-request_history-reason) プロパティは `network_fallback` になります。

Stripe Autopilot を設定するには、[Stripe サポートに問い合わせ](https://support.stripe.com/contact/login)、[監視](https://docs.stripe.com/issuing/controls/real-time-authorizations.md#monitor-your-webhook-responses)してください。

## Webhook による不正利用チャレンジ(公開プレビュー)

[不正利用チャレンジ](https://docs.stripe.com/issuing/controls/fraud-challenges.md)を使用すると、カード会員は、通常はブロックされるはずの不正利用以外の取引を再試行できます。不正利用チャレンジは一般提供されていますが、リアルタイムの Webhook レスポンスを使用して自らトリガーする機能は公開プレビューです。

不正利用に関するチャレンジが送信されるタイミングを決定するルールを管理するには、`issuing_authorization.request` Webhook へのレスポンスを調整します。疑わしい支出を検出し、追加の確認が必要なシナリオ (カード保有者が海外でカードを使用している場合など) で、不正利用に関するチャレンジをトリガーできます。

これを行うには、`issuing_authorization.request` Webhook を拒否し、`send_fraud_challenges` フィールドに `["sms"]` 値を含めます。

リアルタイムの Webhook レスポンスによる不正利用チャレンジのトリガーは、現在、プレビューユーザーに限定されています。プレビューに参加するには、Issuing のお客様である必要があります。プレビューへのアクセスをリクエストするには、Stripe アカウントにログインしてページを更新してください。詳細については、[Stripe までお問い合わせください](https://stripe.com/contact/sales)。