API v2 の概要

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

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

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

API v2 をサポートする SDK

すべてのサーバー側の SDK は、/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 バージョンを指定する必要があります。

たとえば、API バージョン 2024-09-30.acacia を使用する curl リクエストは次のようになります。

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

リストのページ分割

/v2 名前空間の API (GET /v2/core/events など) には、/v1 名前空間のものとは異なるページ分割インターフェイスが含まれます。

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

これらの URL から、Stripe の SDK を使用せずにリクエストを行うことができます。Stripe の SDK を使用する場合は、SDK が自動ページ分割を行うため、これらの URL を使用する必要はありません。

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

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 はサポートされていません。ただし、この名前空間内ではサンドボックスを使用してテストできます。
• Stripe は、現在 /v2 エンドポイントおよびリソースを使用して thin イベントのみを生成しています。
• API v2 によって生成されたリクエストログは、開発者ダッシュボードではなくワークベンチでのみ確認することが可能です。