Payment Intents API

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

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

• 自動じどう認証にんしょう処理しょり
• 二に重じゅう支払しはらいの防止ぼうし
• べき等とうキーの問題もんだいがない
• 強力きょうりょくな顧客こきゃく認証にんしょう (SCA) および同様どうようの規制きせい変更へんこうへの対応たいおう

包括ほうかつ的てきな API セット

PaymentIntent API を、SetupIntent API および PaymentMethod API と組くみ合あわせて使用しようします。これらの API により、動的どうてきな支払しはらい (3D セキュアなどの追加ついか認証にんしょう) を処理しょりしやすくなり、他たの国々くにぐににビジネスを展開てんかいするための準備じゅんびができます。これらの API を利用りようして、新あたらしい規制きせいや地域ちいきの支払しはらい方法ほうほうに対応たいおうすることもできます。

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

PaymentIntent を作成さくせいする

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

PaymentIntent を作成さくせいする際さいには、金額きんがくや通貨つうかなどのオプションを指定していできます。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 をクライアント側がわに渡わたす際さいは、いくつかの方法ほうほうを使用しようできます。

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

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

支払しはらい後ご

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

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

今後こんごの支払しはらいのために支払しはらい方法ほうほうを最適さいてき化かする

setup_future_usage パラメーターは、将来しょうらいの再さい使用しように備そなえて支払しはらい方法ほうほうを保存ほぞんします。カードの場合ばあい、このパラメーターは SCA などの地域ちいきの法規ほうき制せいやネットワーク規則きそくに準拠じゅんきょしてオーソリ率りつを最適さいてき化かします。この支払しはらい方法ほうほうを将来しょうらいどのように使用しようするかを考慮こうりょして、使用しようする値ねを決定けっていします。

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

次つぎの例れいは、PaymentIntent を作成さくせいし、setup_future_usage を指定していする方法ほうほうを示しめしています。

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

動的どうてきな明細めいさい書しょ表記ひょうき

デフォルトでは、Stripe アカウントの明細めいさい書しょ表記ひょうきは、カードに請求せいきゅうするたびに顧客こきゃくの明細めいさい書しょに表示ひょうじされます。支払しはらいごとに別べつの表記ひょうきを使用しようするには、statement_descriptor パラメーターを含ふくめます。

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_09l3shTSTKHYCzzZZsiLl2vA
:" \
  -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 によるメタデータの更新こうしんでは、以前いぜん作成さくせいされた支払しはらいのメタデータは変更へんこうされません。

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