サーバーサイド SDK の概要

Stripe のサーバー側 SDK を使用すると、Stripe の REST API が使用されるため必要な作業量が削減されます。Stripe が管理しているる SDK は、Ruby、PHP、Java、Python、Node、.NET、Go で利用できます。コミュニティライブラリは、他のサーバー言語でも利用できます。

インストールとセットアップ

以下の言語セレクターで言語を選択し、指示に従って SDK をインストールします。

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

インストールが完了したら、Stripe を初期化する必要があります。

require 'stripe'
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'

API リクエストを送信する

Stripe API が使用されているオブジェクトは、主に作成、更新、削除、取得、一覧表示、検索の 6 つの方法で操作できます。次の例は、Customer オブジェクトを用いて 6 つの方法をそれぞれ説明しています。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="John Doe"

API リクエストには、さまざまなタイプのパラメーターを含めることができます。たとえば、name (文字列)、address (オブジェクト)、preferred_locales (リスト) を使用して顧客を作成する方法を次に示します。

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d name="John Doe" \
  -d "address[country]"=US \
  -d "address[city]"="San Fransisco" \
  -d "preferred_locales[]"=EN \
  -d "preferred_locales[]"=FR

オブジェクトを更新するときに、そのプロパティの一部をクリアできます。動的な型付き言語の場合は、空の文字列を送信します。強力な型付き言語の場合は、特定の定数を使用します。たとえば、顧客の name (文字列) と metadata (キーと値のペアのハッシュ)を クリアする方法は次のとおりです。

customer = Stripe::Customer.update(
'{{CUSTOMER_ID}}', {
  name: '',
  metadata: '',
})

この例では、すべてのメタデータをクリアしますが、個々のキーをクリアすることもできます。メタデータの管理について詳しくは、メタデータガイドをご覧ください。

API レスポンスにアクセスする

API リクエストを行うたびに、Stripe から応答が返されます。

オブジェクトを作成、取得、または更新すると、オブジェクト自体が返されます。

{
  "id": "pi_001",
  "object": "payment_intent",
  "amount": 1099,
  "currency": "usd",
  /* ... */
}

変数を使用して、そのオブジェクトのプロパティにアクセスします。

paymentIntent = Stripe::PaymentIntent.retrieve('{{PAYMENT_INTENT_ID}}')
puts paymentIntent.amount

オブジェクトを一覧表示または検索すると、要求されたオブジェクトと data 配列を含む List オブジェクトが返されます。

{
  "object": "list",
  "data": [
    {
      "id": "pi_003",
      "object": "payment_intent",
      "amount": 4200,
      "currency": "usd",
      /* ... */
    },
    {
      "id": "pi_002",
      "object": "payment_intent",
      "amount": 2100,
      "currency": "usd",
      "payment_method_types": [ "link" ],
      /* ... */
    }
  ],
  "has_more": true,
  "url": "/v1/payment_intents"
}

data 配列でループを使用して、各オブジェクトのプロパティにアクセスします。

paymentIntentList = Stripe::PaymentIntent.list({ limit: 3 })
for pi in paymentIntentList.data do
  puts pi.amount
end

自動ページ分割を使用して、すべての結果を反復処理することもできます。

レスポンスの拡張

一部のプロパティは展開可能または包含可能であり、expand パラメーターを使用して返すことができます。たとえば：

• PaymentIntent を取得し、関連付けられている PaymentMethod を展開します。
  Command Line

  cURL

  curl -G https://api.stripe.com/v1/payment_intents/{{PAYMENT_INTENT_ID}} \
    -u "
  sk_test_BQokikJOvBiI2HlWgH4olfQ2
  :" \
    -d "expand[]"=payment_method

• Checkout セッションを取得し、line_items プロパティを含めます。
  Command Line

  cURL

  curl -G https://api.stripe.com/v1/checkout/sessions/{{SESSION_ID}} \
    -u "
  sk_test_BQokikJOvBiI2HlWgH4olfQ2
  :" \
    -d "expand[]"=line_items

詳しくは、レスポンスの拡張をご覧ください。

リクエスト ID を取得する

各 API リクエストには、一意のリクエスト ID (req_xxx) が関連付けられます。これは、ダッシュボードでリクエストを調べ、Stripe が受け取ったパラメーターを確認したり、問題の解決が必要な場合に Stripe サポートと問題を共有するために使用されます。

ID はダッシュボードのログで確認するか、次のようなコードで直接確認できます。

customer = Stripe::Customer.create({ name: 'John Doe', })
puts customer.last_response.request_id

追加のリクエストオプションを設定する

API リクエストを送信するときに、追加のリクエストオプションを次のように設定できます。

• 特定の API バージョンを設定します。
• 連結アカウントでリクエストを行います。
• べき等キーを指定します。

エラー処理

各サーバー SDK は、Stripe API からのエラー応答を例外タイプとして解釈するため、応答ステータスを自分で解析する必要はありません。各言語に適したエラー処理規則を使用して、これらのエラーを処理します。

begin
  Stripe::PaymentIntent.create(params)
rescue Stripe::CardError => e
  puts "A payment error occurred: #{e.error.message}"
rescue Stripe::InvalidRequestError => e
  puts "An invalid request occurred."
rescue Stripe::StripeError => e
  puts "Another problem occurred, maybe unrelated to Stripe."
else
  puts "No error."
end

詳しくはエラー処理をご覧ください。

プライベートプレビュー版機能

Stripe は、すぐには公開されない新しいプロパティやパラメーターを導入する非公開ベータ機能を定期的にリリースしています。動的に型付けされた SDK (PHP、Node、Ruby、Python) は、これらを自動的にサポートします。厳密に型指定された SDK (Java、.NET、Go) の場合、ベータリリースでサポートされていなければ次のコードを適用します。

文書化されていないパラメーターを送信:

CustomerCreateParams params =
  CustomerCreateParams.builder()
    .setEmail("jenny.rosen@example.com")
    .putExtraParam("secret_feature_enabled", "true")
    .build();

client.customers().create(params);

文書化されていないフィールドへのアクセス:

final Customer customer = client.customers().retrieve("cus_1234");
Boolean featureEnabled = customer.getRawJsonObject()
    .getAsJsonPrimitive("secret_feature_enabled")
    .getAsBoolean();

ソースコード

各サーバー SDK のソースコードは、GitHub で入手できます。

クライアントサービスパターン

一部の SDK では、操作の実行方法を変更するクライアントサービスパターンが導入されています。この新しいサービスパターンを使用すると、静的メソッドなしでモックを作成できるようになり、複数のクライアントインスタンスを個別の構成で同時に動作させることができます。

これらのライブラリの古いバージョンを対象とするコードをリソースベースのパターンと比較する場合、呼び出しは異なって見える可能性があります。

ベータバージョン

5.1.0-beta.3 や 5.1.0b3 など、beta または b ファイル名の接尾辞で識別できるベータ SDK を提供しています。これにより、開発中の製品や機能にアクセスでき、一般提供前にフィードバックを共有できます。

ベータ SDK リリースには、それぞれの GitHub リポジトリーの readme.md ファイルからアクセスします。