Cash App Pay 支払い

システムに Cash App Pay のサポートを追加します。

Checkout

Elements

Direct API

モバイル

このガイドでは、Payment Element を使用して、ウェブサイトまたはアプリケーションにカスタムの Stripe 決済フォームを埋め込む方法をご紹介します。Payment Element では、Cash App Pay とその他の支払い方法に自動的に対応できます。高度な設定やカスタマイズについては、決済を受け付けるの導入ガイドをご覧ください。

Stripe を設定する
サーバー側

まず、Stripe アカウントが必要です。今すぐご登録ください。

アプリケーションから Stripe API にアクセスするには、Stripe の公式ライブラリを使用します。

PaymentIntent を作成する
サーバー側

Stripe は PaymentIntent (支払いインテント) オブジェクトを使用して、顧客から支払いを回収する意図を示し、プロセス全体を通して請求の実施と支払い状態の変化を追跡します。

amount および currency を指定して、サーバーで PaymentIntent を作成します。支払い方法はダッシュボードで管理できます。Stripe は取引額、通貨、決済フローなどの要素に基づいて、適切な支払い方法が返されるように処理します。Payment Intent を作成する前に、支払い方法の設定ページで Cash App Pay が有効になっていることを確認してください。

支払い額は常に、クライアント側ではなく、信頼性の高い環境であるサーバー側で決定してください。このようにすることで、悪意のある顧客が価格を操作できないようにすることができます。

client secret を取得する

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

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

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

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

支払いの詳細を収集する
クライアント側

Payment Element を使用してクライアント側で支払い詳細を収集します。Payment Element は事前構築された UI コンポーネントであり、さまざまな決済手段の詳細の収集をシンプルにします。

Payment Element には、HTTPS 接続を介して支払い情報を Stripe に安全に送信する iframe が含まれています。一部の支払い方法では、支払いを確定するために別のページにリダイレクトする必要があるため、Payment Element を別の iframe 内に配置しないでください。

構築済みのシステムを機能させるには、決済ページのアドレスの先頭を http:// ではなく https:// にする必要があります。HTTPS を使用しなくてもシステムをテストできますが、本番環境で決済を受け付ける準備が整ったら、必ず、HTTPS を有効にしてください。

Stripe.js を設定する

Payment Element は Stripe.js の機能として自動的に使用できるようになります。決済ページに Stripe.js スクリプトを含めるには、HTML ファイルの head にスクリプトを追加します。常に js.stripe.com から Stripe.js を直接読み込むことにより、PCI 準拠が維持されます。スクリプトをバンドルに含めたり、そのコピーを自身でホストしたりしないでください。

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

決済ページで以下の JavaScript を使用して、Stripe のインスタンスを作成します。

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Payment Element を支払いページに追加する

Payment Element を決済ページに配置する場所が必要です。決済フォームで、一意の ID を持つ空の DOM ノード (コンテナー) を作成します。

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

前のフォームが読み込まれたら、Payment Element のインスタンスを作成して、それをコンテナーの DOM ノードにマウントします。Elements インスタンスを作成する際に、前のステップからの client secret を options に渡します。

client secret は支払いを完了できるため、慎重に取り扱う必要があります。記録したり、URL に埋め込んだり、当該の顧客以外に漏洩することがないようにしてください。

checkout.js
const options = {
  clientSecret: '{{CLIENT_SECRET}}',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret obtained in a previous step
const elements = stripe.elements(options);
// Optional: Autofill user's saved payment methods. If the customer's
// email is known when the page is loaded, you can pass the email
// to the linkAuthenticationElement on mount:
//
//   linkAuthenticationElement.mount("#link-authentication-element",  {
//     defaultValues: {
//       email: 'jenny.rosen@example.com',
//     }
//   })

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

Stripe に支払いを送信する
クライアント側

Payment Element からの詳細を指定して stripe.confirmPayment を使用し、支払いを完了します。ユーザーが支払いを完了した後に Stripe がユーザーをリダイレクトする場所を指定するには、この関数に return_url を指定します。ユーザーはまず、銀行のオーソリページなどの中間サイトにリダイレクトされ、その後 return_url にリダイレクトされます。カード支払いでは、支払いが正常に完了するとすぐに return_url にリダイレクトします。

checkout.js
const form = document.getElementById('payment-form');

form.addEventListener('submit', async (event) => {
  event.preventDefault();

  const {error} = await stripe.confirmPayment({
    //`Elements` instance that was used to create the Payment Element
    elements,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point will only be reached if there is an immediate error when
    // confirming the payment. Show error to your customer (for example, payment
    // details incomplete)
    const messageContainer = document.querySelector('#error-message');
    messageContainer.textContent = error.message;
  } else {
    // Your customer will be redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer will be redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

return_url が、Web サイト上の支払いステータスを表示するページと対応していることを確認します。Stripe が顧客を return_url にリダイレクトするときは、以下の URL クエリーパラメーターが指定されます。

パラメーター	説明
`payment_intent`	`PaymentIntent` の一意の識別子。
`payment_intent_client_secret`	`PaymentIntent` オブジェクトの client secret。

注意

顧客のブラウザーセッションを追跡するツールを利用している場合、リファラー除外リストに stripe.com ドメインの追加が必要になる場合があります。リダイレクトを行うと、一部のツールでは新しいセッションが作成され、セッション全体の追跡ができなくなります。

クエリパラメーターのいずれか 1 つを使用して PaymentIntent を取得します。PaymentIntent のステータスを調べて、顧客に表示する内容を決定します。また、return_url を指定するときにカスタムのクエリパラメーターを追加することもできます。このパラメーターはリダイレクトプロセスの間維持されます。

status.js
// Initialize Stripe.js using your publishable key
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

// Retrieve the "payment_intent_client_secret" query parameter appended to
// your return_url by Stripe.js
const clientSecret = new URLSearchParams(window.location.search).get(
  'payment_intent_client_secret'
);

// Retrieve the PaymentIntent
stripe.retrievePaymentIntent(clientSecret).then(({paymentIntent}) => {
  const message = document.querySelector('#message')

  // Inspect the PaymentIntent `status` to indicate the status of the payment
  // to your customer.
  //
  // Some payment methods will [immediately succeed or fail][0] upon
  // confirmation, while others will first enter a `processing` state.
  //
  // [0]: https://stripe.com/docs/payments/payment-methods#payment-notification
  switch (paymentIntent.status) {
    case 'succeeded':
      message.innerText = 'Success! Payment received.';
      break;

    case 'processing':
      message.innerText = "Payment processing. We'll update you when payment is received.";
      break;

    case 'requires_payment_method':
      message.innerText = 'Payment failed. Please try another payment method.';
      // Redirect your user back to your payment page to attempt collecting
      // payment again
      break;

    default:
      message.innerText = 'Something went wrong.';
      break;
  }
});

リダイレクトと取引の認証

顧客は、モバイルアプリまたはデスクトップアプリで Cash App Pay 取引を認証できます。confirmPayment の呼び出し後、顧客が使用するクライアントによって認証方法が決定されます。

confirmPayment の呼び出し後、顧客は Cash App にリダイレクトされ、そこで支払いを承認または拒否します。顧客が支払いを承認すると、Payment Intent の return_url にリダイレクトされます。Stripe は payment_intent、payment_intent_client_secret、redirect_pm_type、redirect_status を URL クエリパラメーターとして (return_url の既存のクエリパラメーターとともに) 追加します。

認証セッションは 60 分後に期限切れになり、PaymentIntent のステータスは require_payment_method に戻ります。ステータスが移行すると、顧客には支払いエラーが表示され、支払いプロセスをもう一度開始する必要があります。

オプションオーソリとキャプチャーを分離する

支払いをすぐ作成して、売上は後でキャプチャーするように、オーソリとキャプチャーを分離できます。7 日の期間内に支払いがキャプチャーされない場合、Stripe は PaymentIntent をキャンセルし、payment_intent.canceled イベントを送信します。

支払いをキャプチャーできないことが分かっている場合は、7 日間経過するのを待つのではなく、PaymentIntent をキャンセルすることをお勧めします。

オーソリのみを行うよう Stripe に指示する

オーソリとキャプチャーの分離を指定するには、PaymentIntent の作成時に capture_method を manual に設定します。このパラメーターは、顧客の Cash App Pay アカウントの金額のみをオーソリするように Stripe に指示します。

売上をキャプチャーする

オーソリが成功すると、PaymentIntent のステータスは requires_capture に移行します。オーソリされた売上をキャプチャーするには、PaymentIntent のキャプチャーリクエストを作成します。

デフォルトでは、オーソリされた合計金額がキャプチャーされます。amount_to_capture を指定して、合計金額以下の金額を指定することもできます。

任意オーソリをキャンセルする

オーソリをキャンセルする必要がある場合は、PaymentIntent をキャンセルしてください。

オプション支払い後のイベントを処理する

支払いが完了すると、Stripe は payment_intent.succeeded イベントを送信します。ダッシュボード、カスタム Webhook、またはパートナーソリューションを使用してこれらのイベントを受信し、また、顧客への注文確認メールの送信、データベースでの売上の記録、配送ワークフローの開始などのアクションを実行します。

クライアントからのコールバックを待つのではなく、これらのイベントをリッスンします。クライアント側では、コールバックが実行される前に顧客がブラウザーのウィンドウを閉じたり、アプリを終了したりする可能性があります。また、悪意を持つクライアントがレスポンスを不正操作する恐れもあります。非同期型のイベントをリッスンするよう構築済みのシステムを設定することで、これ以降はより多くの決済手段を簡単に受け付けられるようになります。サポートされているすべての決済手段の違いをご確認ください。

ダッシュボードでイベントを手動で処理する
ダッシュボードを使用して、テスト決済をダッシュボードで表示したり、メール領収書を送信したり、入金を処理したり、失敗した決済を再試行したりできます。
Custom Webhook を構築する
Custom Webhook ハンドラを構築してイベントをリッスンし、カスタム非同期型の決済フローを作成します。Stripe CLI を使用して、ローカルで Webhook の導入のテストとデバッグを行います。
構築済みアプリを導入する
パートナーアプリケーションを統合することで、自動化やマーケティング/セールスなどの一般的なビジネスイベントを処理します。

導入をテストする

実装内容をテストするには、決済手段として Cash App Pay を選択し、支払うをタップします。テスト時はテスト決済ページにリダイレクトされ、そこで決済を承認または拒否できます。

本番環境では、支払うをタップすると、Cash App モバイルアプリケーションにリダイレクトされます。Cash App 内で支払いを承認または拒否するオプションはありません。リダイレクトされた後、支払いは自動的に承認されます。

失敗した支払い

Cash App Pay は複数のデータポイントを使用して、取引を拒否する状況を判断します (たとえば、AI モデルが取引において消費者の高い不正利用リスクを検出した場合や、Cash App で請求する許可を消費者が取り消した場合など)。

このケースでは、PaymentMethod (支払い方法) は切り離され、PaymentIntent (支払いインテント) オブジェクトのステータスは自動的に requires_payment_method に移行します。

支払いが拒否された場合を除き、Cash App Pay の PaymentIntent (支払いインテント) が requires_action ステータスである場合、顧客は Cash App にリダイレクトされてから 10 分以内に支払いを完了する必要があります。10 分経過してもアクションが行われない場合、PaymentMethod (支払い方法) の関連付けが解除され、PaymentIntent オブジェクトのステータスは自動的に requires_payment_method に移行します。

これが発生すると、Payment Element はエラーメッセージを表示し、顧客に別の支払い方法で再試行するように求めます。

エラーコード

次の表は、一般的なエラーコードと推奨アクションの詳細を示しています。

エラーコード	推奨される対応
`payment_intent_invalid_currency`	適切な通貨を入力します。Cash App Pay は `usd` にのみ対応しています。
`missing_required_parameter`	必須パラメーターの詳細については、エラーメッセージをご確認ください。
`payment_intent_payment_attempt_failed`	このコードは PaymentIntent の last_payment_error.code フィールドに表示されることがあります。エラーメッセージで失敗の詳細な理由と推奨されるエラー処理を確認します。
`payment_intent_redirect_confirmation_without_return_url`	Cash App Pay で PaymentIntent を確定する際は、`return_url` を指定します。

メモ