# 支払いステータスの更新

支払いステータスを監視および確認して、支払いの成功と失敗に対応できるようにします。

*PaymentIntents* (The Payment Intents API tracks the lifecycle of a customer checkout flow and triggers additional authentication steps when required by regulatory mandates, custom Radar fraud rules, or redirect-based payment methods) は、顧客が実行したアクションまたは支払い方法に応じて更新されます。組み込みでは PaymentIntent を確認することで支払いプロセスのステータスを特定できるため、お客様はビジネスアクションを実行したり、さらなる介入が必要な状態に対応できます。

Stripe ダッシュボードを使用して、支払いの成功などの支払いのステータスをメールで送信するようにアカウントを設定することもできます。それには、[ユーザー設定](https://dashboard.stripe.com/settings/user)で[メール通知](https://docs.stripe.com/get-started/account/teams.md#email-notifications)を変更します。

## Payment statuses and PaymentIntent statuses 

The [Payments](https://dashboard.stripe.com/payments) page in the Dashboard shows a payment status for each payment, which you can use to filter the list. This status summarizes the payment but doesn’t include the additional details provided by the PaymentIntent [status](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status).

A PaymentIntent’s `status` tracks the status of a payment and indicates when a payment requires further processing or customer actions. A payment that uses a PaymentIntent might require a payment method, confirmation, or other action to succeed. In the Dashboard, these states map to **Incomplete**.

To understand a payment’s incomplete status, click the payment and use [Workbench Inspector](https://docs.stripe.com/workbench/overview.md#inspector) to see the PaymentIntent’s details in JSON. Search for `status` to see the exact value.

The following table maps each PaymentIntent `status` to the payment statuses in the Dashboard. Edge cases such as expired attempts and specific decline codes can affect this mapping. Use the API or Workbench Inspector to get the authoritative state.

| PaymentIntent `status`    | Payment status                        | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| ------------------------- | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `requires_payment_method` | **Incomplete**                        | Typically occurs if there’s no [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) or the intent hasn’t progressed past collection. Depending on the payment method, amounts, and errors, the payment status can also be **Partially paid**, **Waiting on funding**, or **Failed**.                                                                                                                                                               |
| `requires_confirmation`   | **Incomplete**                        | Occurs after your customer provides payment information and is ready to confirm. Most integrations skip this state because they submit payment method information when the payment is confirmed.                                                                                                                                                                                                                                                                                                         |
| `requires_action`         | **Incomplete**                        | Occurs when the payment requires additional actions, such as authenticating with [3D Secure](https://docs.stripe.com/payments/3d-secure.md). The payment status in the Dashboard can also be **Partially paid**, **Waiting on funding**, or **Failed** under certain authentication or error conditions.                                                                                                                                                                                                 |
| `processing`              | **Pending**                           | Occurs when required actions are complete and the payment uses an *asynchronous payment method* (Asynchronous payment methods can take up to several days to confirm whether the payment has been successful. During this time, the payment can't be guaranteed), such as bank debits. These payment methods can take up to a few days to process.                                                                                                                                                       |
| `requires_capture`        | **Uncaptured** or **Partial capture** | Occurs if your flow uses [separate capture](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md). If any amount is received toward the intent, the status is **Partial capture**. If no amount is received, the status is **Uncaptured**.                                                                                                                                                                                                                                               |
| `succeeded`               | **Succeeded**                         | A PaymentIntent with a `succeeded` status means the corresponding payment flow is complete. The funds are in your account and you can fulfill the order.

  If the payment attempt fails (for example, due to a decline), the PaymentIntent’s status returns to `requires_payment_method` so the payment can be retried.

  Subsequent refunds, disputes, and outcomes are reflected on the Charge. These might change what you see in the Dashboard, even though the PaymentIntent remains `succeeded`. |
| `canceled`                | **Canceled**                          | Occurs when the payment is canceled. If the intent was canceled as part of a failed invoice flow and the latest charge failed, the status might show **Failed**.                                                                                                                                                                                                                                                                                                                                         |

## Handle next actions 

Some payment methods require additional steps, such as authentication, to complete the payment process. Stripe.js handles these automatically when confirming the PaymentIntent, but if you have an advanced integration, you can handle these manually.

The PaymentIntent’s [next_action](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-next_action) property exposes the next step that your integration must handle to complete the payment. Available next actions vary by payment method. For a full list, see the [API reference](https://docs.stripe.com/api.md#payment_intent_object-next_action-type).

Learn how to [handle a payment method’s required next actions](https://docs.stripe.com/payments/payment-methods/overview.md).

## クライアントで PaymentIntent ステータスを確認する

クライアントで [confirmPayment](https://docs.stripe.com/js/payment_intents/confirm_payment) 関数を使用して決済を完了する場合、返された PaymentIntent を確認して現在のステータスを判断できます:

```javascript
(async () => {
  const {paymentIntent, error} = await stripe.confirmPayment({
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/complete',
    },
    redirect: 'if_required',
  });
  if (error) {
    // Handle error here
  } else if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  }
})();
```

`confirmPayment` 関数を使用した場合、考えられる結果は次のとおりです:

| **イベント**          | **発生内容**          | **想定される組み込み**                   |
| ----------------- | ----------------- | ------------------------------- |
| PaymentIntent で解決 | 顧客が決済ページで支払いを完了した | 支払いが成功したことを顧客に通知する              |
| エラーで解決            | 決済ページで顧客の支払いが失敗した | エラーメッセージを表示して、顧客に支払いを再度実行するよう促す |

`confirmPayment` が返すプロミスは、決済プロセスが完了するか、エラーで失敗した時点で解決されます。正常に完了して PaymentIntent が返される場合、ステータスは常に `succeeded` です ([capturing later](https://docs.stripe.com/payments/place-a-hold-on-a-payment-method.md) の場合は `requires_capture`)。決済に認証などの追加のステップが必要な場合、そのステップが完了するかタイムアウトするまで、プロミスは完了しません。

## confirmPayment を使用せずにクライアントで PaymentIntent のステータスを確認する

`confirmPayment` 関数を使用せずに 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)) を渡して、[retrievePaymentIntent](https://docs.stripe.com/js/payment_intents/retrieve_payment_intent) 関数で個別に取得します。

```javascript
(async () => {
  const {paymentIntent} = await stripe.retrievePaymentIntent(clientSecret);
  if (paymentIntent && paymentIntent.status === 'succeeded') {
    // Handle successful payment here
  } else {
    // Handle unsuccessful, processing, or canceled payments and API errors here
  }
})();
```

以下に、確定後の PaymentIntent の[想定されるステータス](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-status)を示します。

| **発生内容**          | **想定される PaymentIntent ステータス** |
| ----------------- | ----------------------------- |
| 顧客が決済ページで支払いを完了した | `succeeded`                   |
| 顧客が決済フローを完了しなかった  | `requires_action`             |
| 決済ページで顧客の支払いが失敗した | `requires_payment_method`     |

[PaymentIntent のステータスの詳細をご覧ください](https://docs.stripe.com/payments/paymentintents/lifecycle.md)。

## Webhook で PaymentIntent を監視する

Stripe は、PaymentIntent のステータスが変化した時にサーバーに *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 を使用して `payment_intent.succeeded` イベントを監視し、その完了を非同期で処理します。

> 技術的には、Webhook の代わりにポーリングを使用して、非同期の操作によって発生した変化を監視することも可能です。その場合、そのステータスを確認するために PaymentIntent の取得を繰り返します。ただし、この方法は信頼性がかなり低く、レート制限の問題が発生する可能性があります。Stripe では API リクエストの[レート制限](https://docs.stripe.com/testing.md#rate-limits)を実施しているため、ポーリングを使用する際には注意が必要です。

Webhook イベントを処理するには、サーバーにルートを作成し、[ダッシュボード](https://dashboard.stripe.com/account/webhooks)で対応する Webhook エンドポイントを設定します。Stripe は、支払いが成功した場合は `payment_intent.succeeded` イベントを、支払いが失敗した場合は `payment_intent.payment_failed` イベントを送信します。

Webhook ペイロードには PaymentIntent オブジェクトが含まれます。次の例は、この 2 つのイベントの処理方法を示しています。

#### Ruby

```ruby
require 'sinatra'
require 'stripe'

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

    begin
        event = Stripe::Webhook.construct_event(
            payload, sig_header, endpoint_secret
        )
    rescue JSON::ParserError => e
        # Invalid payload
        status 400
        return
    rescue Stripe::SignatureVerificationError => e
        # Invalid signature
        status 400
        return
    end

    case event['type']
    when 'payment_intent.succeeded'
        intent = event['data']['object']
        puts "Succeeded:", intent['id']
        # Fulfill the customer's purchase
    when 'payment_intent.payment_failed'
        intent = event['data']['object']
        error_message = intent['last_payment_error'] && intent['last_payment_error']['message']
        puts "Failed:", intent['id'], error_message
        # Notify the customer that payment failed
    end

    status 200
end
```

支払いに失敗した場合、PaymentIntent の `last_payment_error` プロパティを調査することで詳細を確認できます。顧客に支払いが完了していないことを通知し、別の支払い方法で再実行するように促すことができます。同じ PaymentIntent を再利用して顧客の購入を引き続き追跡します。

### 特定の Webhook イベントを処理する

次のリストは、Webhook イベントの処理方法を示しています。

| イベント                        | 説明                                                                                                                            | 次のステップ                                  |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
| `processing`                | 顧客の決済は Stripe に正常に送信されました。[成功の確認が遅延する](https://docs.stripe.com/payments/payment-methods.md#payment-notification)決済手段にのみ該当します。 | 開始された支払いが成功するか、失敗するかの結果を待ちます。           |
| `succeeded`                 | 顧客の決済が成功しました。                                                                                                                 | 購入された商品やサービスのフルフィルメントを行います。             |
| `amount_capturable_updated` | 顧客の決済がオーソリされ、キャプチャーが可能になりました。                                                                                                 | 決済に利用できる資金をキャプチャーします。                   |
| `payment_failed`            | 顧客の決済がカードネットワークから拒否されたか、有効期限が切れています。                                                                                          | 顧客にメールまたはプッシュ通知で連絡し、別の決済手段を指定するよう依頼します。 |

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)
```

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

## PaymentIntent で支払いを識別する

顧客からの支払いを回収しようとしたときに、PaymentIntent によって [Charge (支払い)](https://docs.stripe.com/api/charges.md) が作成されます。最新の支払いの ID を取得するには、PaymentIntent の [latest_charge](https://docs.stripe.com/api/payment_intents/object.md#payment_intent_object-latest_charge) プロパティを調べます。

#### Ruby

```ruby

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

intent = client.v1.payment_intents.retrieve('{{PAYMENT_INTENT_ID}}')
latest_charge = intent.latest_charge
```

失敗した支払いも含めて PaymentIntent に関連するすべての支払いを表示するには、[すべての支払いをリスト](https://docs.stripe.com/api/charges/list.md#list_charges-payment_intent)して、`payment_intent​` パラメーターを指定します。

```curl
curl -G https://api.stripe.com/v1/charges \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_intent={{PAYMENTINTENT_ID}}"
```