API v2 の概要

Stripe API は、異なるエンドポイントが含まれる 2 つの名前空間を提供しています。

• API v1: /v1 名前空間には、現在既存の Stripe API の大部分が含まれています。
• API v2: /v2名前空間には、/v2 デザインパターンを使用するエンドポイントが含まれます。

v1 と v2 の名前空間の主な違い

API v2 をサポートする SDK

すべてのサーバー側 SDK (Golang を除く) は、/v2 名前空間の API をサポートしています。

Golang を使用する場合は、カスタムリクエスト機能を使用して /v2 名前空間の API にアクセスします。

Stripe CLI で API v2 を使用する

stripe trigger と stripe listen を使用して、システムのイベント処理をテストします。Stripe CLI を使用して、/v2 名前空間の API にアクセスすることはできません。

SDK、CLI、API のバージョン管理

SDK と Stripe CLI には、すべてのリクエストの API バージョンが自動的に含まれます。SDK または CLI のバージョンを更新すると、Stripe は、リクエストとレスポンスの API バージョンを同時に更新します。

SDK や CLI を使用せず Stripe-Version を含める

API /v2 名前空間に対する API リクエストのすべてに Stripe-Version ヘッダーを含め、基礎となる API バージョンを指定する必要があります。

For example, a curl request using API version 2024-09-30.acacia looks like:

curl -G https://api.stripe.com/v2/core/events \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: 2024-09-30.acacia" \
  -d object_id=fa_123

v1 と v2 の名前空間の API を、同じシステムで使用する

同じシステムであれば、/v1 または /v2 名前空間の API を自由に組み合わせて使用することができます。

import com.stripe.StripeClient;

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

// Call a v2 API
Event event = stripe.v2().core().events().retrieve("evt_123");

// Call a v1 API
Customer customer = stripe.customers().retrieve("cus_123");

公式の SDK または CLI を使用していない場合は、必ず、API コールの URL パスに名前空間を含めてください。以下に例を示します。

# Call a v2 API
curl https://api.stripe.com/v2/core/events?object_id=mtr_123

# Call a v1 API
curl https://api.stripe.com/v1/charges -d amount=2000 -d currency=usd

リストのページ分割

APIs within the /v2 namespace (for example, GET /v2/core/events) contain a different pagination interface compared to those in the /v1 namespace.

• previous_page_url プロパティは、リストの前のページを取得するための URL を返します。前のページがない場合、値は null になります。
• next_page_url プロパティは、リストの次のページを取得するための URL を返します。これ以上ページがない場合、値は null になります。

最初のリクエストの後でリストフィルターを変更できません。

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

EventListParams params =
  EventListParams.builder()
    .setObjectId("mtr_123")
    .build();

for (Event event : stripe.v2().core().events().list(params).autoPagingIterable()) {
  // process event object
}

べき等

/v2 名前空間の API では、べき等の動作に対するサポートが改善されており、同じべき等キーを使用してリクエストが複数回実行されたときの想定外の副次的影響は防止されます。API が、同じべき等キーを使用する 2 つのリクエストを受信すると、以下のようになります。

• 最初のリクエストが成功すると、 API は新たに加えられた変更をスキップし、更新されたレスポンスを返します。
• 最初のリクエストが失敗 (または部分的に失敗) すると、API はその失敗したリクエストを再実行して、新しいレスポンスを返します。
• まれに、べき等の再生が成功しなくなった場合、API は、理由を説明するエラーを返します。

以下のすべてが該当する場合、2 つのリクエストはべき等と見なされます。

• 同じ API に同じべき等キーを使用する
• 同じアカウントまたはサンドボックス内で発生する
• 互いに過去 30 日以内に発生する

べき等キーを指定するには、Idempotency-Key ヘッダーを使用して、操作を表す一意の値 (UUID を推奨) を指定します。キーが指定されない場合、Stripe は UUID を自動的に生成します。

POST と DELETE の API v2 リクエストはすべて、べき等キーを受け入れ、べき等を利用して動作します。GET リクエストは、定義により、べき等性を備えているため、べき等キーを送信しても効果はありません。

API v1 と API v2 のべき等の違い

API v1 と API v2 のべき等には、大きな違いがいくつかあります。

• API v1 は、POST リクエストでのみ、べき等の再生をサポートしています。API v2 は、すべての POST リクエストと DELETE リクエストをサポートしています。
• 以下の場合、2 つのリクエストはべき等と見なされます。
  • API v1: これらの値が同じべき等キーを使用し、互いに 24 時間以内に発生した場合。
  • API v2: 同じべき等キーを使用し、同じ API に対して作成され、アカウントまたはサンドボックス内で発生し、互いに 30 日以内に作成された場合。
• 2 つのリクエストに同じべき等キーを指定する場合、以下のようになります。
  • API v1: 最初の API リクエストがエラーであった場合でも、以前保存されたレスポンスを常に返します。
  • API v2 は、副次的作用 (API コールの結果として発生する外部の変更または観測可能な動作) を発生させることなく、失敗したリクエストを再試行し、更新されたレスポンスを提供します。

べき等リクエストを作成する

SDK を使用すると、 API リクエストで idempotencyKey プロパティを使用してべき等キーを指定できます。

たとえば、特定のべき等キーを使用して API リクエストを作成するには、次の手順に従います。

StripeClient stripe = new StripeClient("{{YOUR_API_KEY}}");

String idempotencyKey = "unique-idempotency-key";
Example result = stripe.v2().examples().create(
        ExampleCreateParams.builder()
          .setName("My example")
          .build(),

        RequestOptions.builder()
          .setIdempotencyKey(idempotencyKey)
          .build());

SDK または CLI を使用していない場合、リクエストには Idempotency-Key ヘッダーを含めることができます。

curl https://api.stripe.com/v2/examples \
  -H "Authorization: Bearer {{YOUR_API_KEY}}" \
  -H "Stripe-Version: {{STRIPE_API_VERSION}}" \
  -H "Idempotency-Key: unique-idempotency-key" \
  -d <JSON request body>

制限事項

• テスト環境では、/v2 はサポートされていません。ただし、この名前空間内ではサンドボックスを使用してテストできます。
• 制限付きのキーは、現在 API v2 に対応していません。API v2 をコールするには、シークレットキーを使用します。
• Go SDK は現在、/v2 を直接サポートしていません。ただし、/v2 API に対するカスタムリクエストを作成できます。
• Stripe は、現在 /v2 エンドポイントおよびリソースを使用して thin イベントのみを生成しています。
• CLI は /v2 thin イベントの trigger および listen コマンドをサポートしていますが、/v2 リソースの作成はサポートしていません。
• 開発者ダッシュボードとワークベンチのグローバルイベントタブには、/v2 thin イベントが表示されませんが、イベント送信タブには、イベントの送信先の /v2 thin イベントが一覧化されます。
• API v2 によって生成されたリクエストログは、開発者ダッシュボードではなくワークベンチでのみ確認することが可能です。