コンテンツにスキップ
アカウントを作成
または
サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成
サインイン

Payment Intents API

Stripe の支払いに Payment Intents API を使用する方法をご紹介します。

PaymentIntent (支払いインテント) API を使用して、PaymentIntent のライフサイクルを通じてステータスが変化する複雑な決済フローを処理できるシステムを構築します。この API は、支払いの作成から決済までを追跡し、必要に応じて追加の認証ステップをトリガーします。

Payment Intents API を使用すると、以下のようなメリットがあります。

包括的な API セット

Payment Intents API、Setup Intents API、Payment Methods API を組み合わせて使用します。上記の API は、動的な支払い (3D セキュアなどの追加認証) への対応に役立ち、また他の国々にビジネスを拡大する準備となります。さらに、新しい規制や地域固有の決済手段に対応することもできます。

Payment Intents API を利用した組み込みを構築するには、2 つのアクションが必要です。それは PaymentIntent の作成と確定です。一般的に各 PaymentIntent はアプリケーションの 1 つのショッピングカートや顧客セッションと関連付けられています。PaymentIntent はサポートされる支払い方法、回収金額、指定通貨といった取引の詳細をカプセル化します。

PaymentIntent を作成する

使用を開始するには、決済の受け付けガイドをご覧ください。このガイドは、サーバーで PaymentIntent を作成し、PaymentIntent オブジェクト全体を渡す代わりに、その client secret をクライアントに渡す方法を説明します。

PaymentIntent を作成する際には、金額や通貨などのオプションを指定できます。

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd

ベストプラクティス

  • PaymentIntent は、金額がわかり次第 (顧客が決済プロセスを開始したときなど)、作成することをお勧めします。これは購買ファネルの追跡に役立ちます。金額が変更された場合は、金額を更新できます。たとえば、顧客が決済プロセスを離れてカートに新しいアイテムを追加した場合は、顧客が再度決済プロセスを開始するときに金額を更新する必要があります。

  • 購入プロセスを中断し、後で再開する場合は、新しい PaymentIntent を作成するのではなく、同じ PaymentIntent の再利用を試してください。各 PaymentIntent には固有の ID があり、再度必要になった際はその ID を使用して取得できます。アプリケーションのデータモデルでは、PaymentIntent の ID を顧客のショッピングカートやセッションに保存することで、簡単に取得できます。PaymentIntent を再利用するメリットは、オブジェクトのステータスによって特定のカートやセッションの失敗した支払いを追跡できることです。

  • 同じ購入に対して PaymentIntent を重複して作成するのを防止するために、べき等キーを必ず指定してください。このキーは通常、アプリケーションのカートまたは顧客セッションに関連付けられる ID に基づいています。

クライアント側に client secret を渡す

PaymentIntent には、client secret、すなわち個々の PaymentIntent に固有のキーが格納されます。アプリケーションのクライアント側で、支払いを完了するために関数 (stripe.confirmCardPayment や stripe.handleCardAction など) を呼び出す際に、Stripe.js は client secret をパラメーターとして使用します。

client secret を取得する

PaymentIntent には、client secret が含まれています。これは、支払いプロセスを安全に完了するためにクライアント側で使用されます。client secret をクライアント側に渡す際は、いくつかの方法を使用できます。

ブラウザーの fetch 関数を使用して、サーバーのエンドポイントから client secret を取得します。この方法は、クライアント側が 1 ページのアプリケーションで、特に React などの最新のフロントエンドフレームワークで構築されている場合に最適です。client secret を処理するサーバーのエンドポイントを作成します。

main.rb
get '/secret' do
  intent = # ... Create or retrieve the PaymentIntent
  {client_secret: intent.client_secret}.to_json
end

その後、クライアント側で JavaScript を使用して client secret を取得します。

(async () => {
  const response = await fetch('/secret');
  const {client_secret: clientSecret} = await response.json();
  // Render the form using the clientSecret
})();

注意

client secret を使用して、PaymentIntent で指定した金額の支払いプロセスを完了できます。client secret は、記録したり、URL に埋め込んだり、顧客以外の人に公開することがないようにしてください。client secret が含まれるすべてのページで TLS を設定するのを忘れないでください。

支払い後

クライアントが支払いを確定したら、ペストプラクティスとして、支払いが成功したか失敗したかを検出するために、サーバーで Webhook を監視します。

複数の支払い試行があった場合には (リトライなど)、PaymentIntent はそれに関連する 1 つ以上の Charge (支払い) オブジェクトを持つ場合があります。支払いごとに、使用された Outcome (結果) と details of the payment method (支払い方法の詳細) を調査することができます。

今後の支払いのために支払い方法を最適化する

setup_future_usage パラメーターは、将来の再使用に備えて支払い方法を保存します。カードの場合、このパラメーターは SCA などの地域の法規制やネットワーク規則に準拠してオーソリ率を最適化します。この支払い方法を将来どのように使用するかを考慮して、使用する値を決定します。

支払い方法の使用計画使用する setup_future_usage 列挙型値
オンセッション支払いのみon_session
オフセッション支払いのみoff_session
オンセッション支払いとオフセッション支払いの両方off_session

オンセッション支払い用に設定されたカードによるオフセッション支払いを受け入れることはできますが、銀行がオフセッション支払いを拒否し、カード保有者の認証を求める可能性が高くなります。

次の例は、PaymentIntent を作成し、setup_future_usage を指定する方法を示しています。

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d setup_future_usage=off_session

注意

オフセッション支払い用の設定では負担が増える可能性が高くなります。保存したカードでオフセッション支払いを受け付けない場合は、オンセッションの設定を使用してください。

動的な明細書表記

デフォルトでは、Stripe アカウントの明細書表記は、カードに請求するたびに顧客の明細書に表示されます。支払いごとに別の表記を使用するには、statement_descriptor パラメーターを含めます。

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d statement_descriptor="Custom descriptor"

明細書表記は最大 22 文字で、特殊文字 <, >、'、"、および * は使用できません。また、数字だけにすることもできません。動的な明細書表記を使用するときは、Stripe ダッシュボードで設定された明細書表記プレフィックスに動的なテキストが付加されます。動的なテキストとデフォルトの明細書表記を分離するため、アスタリスク (*) と空のスペースも追加されます。これらの 2 つの文字も、22 文字の上限に含まれます。

メタデータに情報を保存する

Stripe では、支払い処理などの最も一般的なリクエストへのメタデータの追加がサポートされています。メタデータは顧客には表示されず、また不正防止システムでの支払いの拒否やブロックでは考慮されません。

メタデータを使用すると、自社に有用な関連情報を Stripe アクティビティーに関連付けることができます。

追加したメタデータはすべてダッシュボードで確認でき (個々の支払いのページを表示するときなど)、一般的なレポートで使用することもできます。一例として、お客様のストアの注文 ID を、その注文の PaymentIntent に関連付けることができます。このようにすると、Stripe での支払いを自社システム内の注文と簡単に照合できるようになります。

Radar for Teams を使用している場合、メタデータとして追加の顧客情報や注文情報を渡すことを検討してください。このようにすると、メタデータ属性を使用して Radar ルールを記述し、ダッシュボードでより多くの情報を利用できるため、審査プロセスの効率化につながります。

PaymentIntent が支払いを作成する際、PaymentIntent はそのメタデータを支払いにコピーします。その後の PaymentIntent によるメタデータの更新では、以前作成された支払いのメタデータは変更されません。

Command Line
curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=usd \
  -d "payment_method_types[]"=card \
  -d "metadata[order_id]"=6735

注意

機密情報 (個人が特定される情報、カード詳細など) は、メタデータや、PaymentIntent の description パラメーターに保存しないでください。

参照情報

このページはお役に立ちましたか。
はいいいえ
お困りのことがございましたら 、サポートにお問い合わせください。
早期アクセスプログラムにご参加ください。
変更ログをご覧ください。
ご不明な点がございましたら、お問い合わせください。
LLM ですか？llms.txt を読んでください。
Powered by Markdoc
関連ガイド
PaymentIntents の仕組み
使用製品
Payments