# サーバー側の連携

Stripe とのバックエンド連携を設定します。

バックエンドの最適な連携を設定するには、Stripe への認証を行い、API リクエストのベストプラクティスを確認し、Webhook を適切に設定する必要があります。

## Stripe への認証を行う

Stripe は API キーによる認証を行います。[制限付きアクセスキー](https://docs.stripe.com/keys-best-practices.md#limit-access)を作成して、特定のリソースへのアクセスをさらに制御することもできます。[シークレット API キーと公開可能 API キー](https://docs.stripe.com/keys.md#obtain-api-keys)を使用してトークンを作成できますが、サーバー側の認証にはシークレットキーが必要です。

以下は、API コールのサンプルです。

```curl
curl https://api.stripe.com/v1/balance \
  -u "<<YOUR_SECRET_KEY>>:"
```

## API リクエストのベストプラクティス

すべての POST リクエストに[べき等キー](https://docs.stripe.com/api/idempotent_requests.md)を追加することをお勧めします。ユニバーサル一意識別子 (UUID) や、顧客 ID と注文 ID の組み合わせなど、キーが一意であることを確認します。これらのキーを使用することで、ネットワークエラーが発生した場合に、リクエストを安全に再試行できます。

### Customer オブジェクト: 支払いの詳細を格納する

*PaymentMethods* (PaymentMethods represent your customer's payment instruments, used with the Payment Intents or Setup Intents APIs) を保存して再利用するには、これを [Customer オブジェクト](https://docs.stripe.com/payments/save-and-reuse.md)に関連付ける必要があります。

PaymentMethod を Customer に関連付けた後で、[Customer ID](https://docs.stripe.com/api/customers/object.md#customer_object-id) と [PaymentMethod ID](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-id) をシステムに保存し、将来の支払いに使用できるようにします。1 つの Customer オブジェクトに[複数の支払い方法のリスト](https://docs.stripe.com/api/payment_methods/list.md)を設定できるため、後から支払いを作成する際は、Customer ID と PaymentMethod ID の両方を指定する必要があります。

Customer を作成して PaymentMethod を関連付ける場合の例を以下に示します。

```curl
curl https://api.stripe.com/v1/customers \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "name=Jenny Rosen" \
  --data-urlencode "email=jenny.rosen@stripe.com" \
  -d payment_method={PAYMENT_METHOD_ID}
```

### 返金

返金は [Refunds](https://docs.stripe.com/api/refunds.md) API を使用して管理され、全額または一部の金額に対して実行できます。Stripe での取引を返金するには、返金が必要な取引の PaymentIntent ID または Charge ID が必要です。

返金は「利用可能な」 Stripe 残高を使用し、保留中の残高は使用できません。利用可能な残高に、返金額に充当できるだけの十分な資金がない場合、Stripe は残りの金額をご利用の銀行口座から引き落とします。一部返金、全額返金、1 件の支払いに対する複数の返金が可能ですが、当初の支払い金額より多い総額の返金は実行できません。

返金には、[API](https://docs.stripe.com/api.md) または[ダッシュボード](https://dashboard.stripe.com/test/dashboard)を使用できます。返金の発行後にキャンセルすることはできません。返金が顧客の明細に表示されるまでに、[5 ～ 10 営業日](https://support.stripe.com/questions/customer-refund-processing-time)かかります。顧客が返金ステータスの確認を希望している場合は、[ARN を提供](https://support.stripe.com/questions/acquirer-reference-number-\(arn\)-for-refunds) することで、顧客から銀行に対する問い合わせが可能になります。

PaymentIntent の返金例を次に示します。

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

金額を指定した一部返金の例を次に示します。

```curl
curl https://api.stripe.com/v1/refunds \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_intent={PAYMENT_INTENT_ID} \
  -d amount=1000
```

### 不審請求の申請とチャージバック

ビジネスは、[不審請求の申請 (チャージバックとも呼ばれる)](https://docs.stripe.com/disputes.md) を管理する責任を負います。不審請求の申請を積極的に監視し、必要に応じて、請求の有効性を裏付ける反証資料を収集および提出することをお勧めします。Stripe は不審請求が申請された売上を保留し、判定が下されるまでの間、Stripe 残高から差し引きます。不審請求の申請でお客様の主張が認めらたら、売上を戻します。

不審請求は、次の 2 つの方法で監視できます。

- Stripe ダッシュボードを使用して、通知をメールで送信します。この通知の設定は、[個人情報](https://dashboard.stripe.com/settings/user)設定から行うことが可能です。
- [Disputes](https://docs.stripe.com/api/disputes.md) API を使用して、不審請求の申請への対処と、反証資料の提出を完全に自動化できます。

## Webhook を設定

*Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) を使用して、アカウントで発生したイベント (銀行口座への入金、返金、支払いなど) をキャプチャーできます。非同期で発生する Stripe [イベント](https://docs.stripe.com/api/events.md)や、追加アクションのトリガーが必要なイベントに利用できます。
![](https://b.stripecdn.com/docs-statics-srv/assets/webhooks-endpoints.871d5a30be8e59762e191fa45b0421a2.png)

各タイプに推奨される Webhook をご覧ください。

| **Webhook タイプ**     | **推奨 Webhook**                                                                                 |
| ------------------- | ---------------------------------------------------------------------------------------------- |
| **チャージ**            | - `charge.succeeded`
  - `charge.failed`
  - `charge.refunded`                                 |
| **自動返金**            | - `refund.created`
  - `refund.failed`                                                         |
| **入金**              | - `payout.created`
  - `payout.paid`
  - `payout.failed`                                       |
| **Payment Intents** | - `payment_intent.succeeded`
  - `payment_intent.payment_failed`
  - `payment_intent.canceled` |
| **不審請求の申請**         | - `radar.early_fraud_warning.created`
  - `charge.dispute.created`
  - `charge.dispute.closed` |

次のリソースを使用して Webhook をセットアップし、正しく設定されていることを検証します。

- [Webhook](https://docs.stripe.com/webhooks.md)
- [Webhook の署名の確認](https://docs.stripe.com/webhooks.md#verify-events)
- [イベントタイプ](https://docs.stripe.com/api/events/types.md)
- [Webhook 使用のベストプラクティス](https://docs.stripe.com/webhooks.md#best-practices)
- [Webhook 設定の確認](https://dashboard.stripe.com/account/webhooks)