Cash App Pay 支払い

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

ウェブ

モバイル

カスタムの決済フローシステムを実装することをお勧めします。カスタムの決済フローを使用すると、少ない労力で、決済システムに Cash App Pay やその他の支払い方法を追加することができます。API による直接連携を使用した Cash App Pay の受け付けは、以下で構成されます。

PaymentIntent (支払いインテント) オブジェクトを作成して、支払いを追跡します。
支払いを Stripe に送信して処理します。
支払いを (モバイルアプリケーションのリダイレクトまたは QR コードを使用して) 認証します。
注文が成功または失敗した後に顧客をリダイレクトするために支払い後のイベントを処理します。

Stripe を設定する
サーバー側

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

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

PaymentIntent を作成する
サーバー側

PaymentIntent (支払いインテント) は、顧客から支払いを回収する意図を表すオブジェクトで、決済プロセスのライフサイクルの各段階を追跡します。

サーバーで PaymentIntent を作成するには、次のようにします。

回収する金額と通貨を指定します。
PaymentIntent の支払い方法のタイプのリストに cashapp を追加します。ダッシュボードで 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
})();

Stripe に支払いを送信して、クライアント側で取引を認証する

このステップでは、Stripe.js を使用してクライアント側で Cash App Pay の支払いを完了します。取引を認証するには、顧客を Cash App にリダイレクトする必要があります。

Stripe.js スクリプトを決済ページに含めるには、このスクリプトを HTML ファイルの head に追加します。

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

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

client.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'
);

クライアント側で PaymentIntent を確認するには、stripe.confirmCashappPayment を使用します。

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

form.addEventListener('submit', function(event) {
  event.preventDefault();

  // Pass the clientSecret obtained from the server in step 2 as the first argument
  stripe.confirmCashappPayment(
    clientSecret,
    {
      payment_method: {
        type: 'cashapp',
      },
      return_url: 'https://www.example.com/checkout/done',
    },
  );
});

注意

confirmCashappPayment は、return_url にモバイルブラウザーのみをリダイレクトし、デスクトップブラウザーのリダイレクトは行いません。デスクトップブラウザーを使用する顧客については、返されたプロミスが解決された後で、戻り先 URL に手動でリダイレクトできます。

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

confirmCashappPayment の呼び出し後、顧客は 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 に戻ります。ステータスが移行すると、顧客には支払いエラーが表示され、支払いプロセスをもう一度開始する必要があります。

オプションリダイレクトと認証を手動で処理する

confirmCashappPayment でリダイレクトと認証を処理するには、Stripe.js を利用することをお勧めします。ただし、自社のサーバーでリダイレクトと認証を手動で処理することもできます。

confirmCashappPayment コールで handleActions: false を指定します。

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

form.addEventListener('submit', function(event) {
  event.preventDefault();

  // Set the clientSecret here you got in Step 2
  stripe.confirmCashappPayment(
    clientSecret,
    {
      payment_method_data: {
        type: 'cashapp',
      },
      return_url: 'https://www.example.com/checkout/done',
    },
    {
      handleActions: false
    },
  ).then((result) => {
    if (result.error) {
      // Display error to your customer.
    } else if (result.paymentIntent.status === "requires_action") {
      const nextAction = result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code;
      const expiresAt = nextAction.qr_code.expires_at;
      if (IS_MOBILE) {
        // This URL redirects the customer to Cash App to approve or decline the payment.
        const mobileAuthUrl = nextAction.mobile_auth_url;
      } else if (IS_DESKTOP) {
        // Render the QR code and display it to the customer using the below image source.
        const imageUrlSvg = nextAction.qr_code.image_url_svg;
        const imageUrlPng = nextAction.qr_code.image_url_png;
      }
    }
  });
});

顧客がモバイルデバイスで Cash App Pay を使用して支払う場合:

result.paymentIntent.next_action.cashapp_handle_redirect_or_display_qr_code.mobile_auth_url プロパティとして設定された URL に顧客をリダイレクトします。これにより、顧客は支払いを承認または拒否するために Cash App にリダイレクトされます。
顧客が支払いを承認すると、Payment Intent の return_url にリダイレクトされます。Stripe は payment_intent、payment_intent_client_secret、redirect_pm_type、redirect_status を URL クエリパラメーターとして (return_url の既存のクエリパラメーターとともに) 追加します。
mobile_auth_url は 30 秒後に期限切れになるので、ご注意ください。期限が切れる前に顧客が mobile_auth_url にリダイレクトされない場合、stripe.retrievePaymentIntent を呼び出して、新しい mobile_auth_url を取得します。

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

支払いをすぐ作成して、売上は後でキャプチャーするように、オーソリとキャプチャーを分離できます。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` を指定します。

注