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