カスタムのストアフロントを構築

Stripe 決済機能に対応したカスタムのストアフロントを構築する方法をご紹介します。

Adobe Commerce は、ストアフロントから切り離されたヘッドレスコマースプラットフォームとして動作します。REST API または GraphQL API を使用することで、プログレッシブウェブアプリ (PWA)、モバイルアプリ、React や Vue などのフレームワークをベースとするフロントエンドなど、カスタムのストアフロントを構築できます。

Stripe モジュールは、次のように REST API および GraphQL API を拡張します。

注文時の支払い方法トークンの設定
3D セキュア顧客認証の実行
顧客の保存済みの支払い方法の管理

Stripe モジュールは購入ページで REST API を使用します。API を使用する方法の例については、Stripe モジュールディレクトリーの resources/examples/ サブディレクトリーをご覧ください。このガイドでは、GraphQL API を使用してカスタムのストアフロントを構築します。

初期化パラメーターを取得する

フロントエンドで Stripe.js と決済フォームを初期化するには、管理エリアで設定した Stripe の公開可能な API キーが必要です。次の GraphQL ミューテーションを使用して、このキーとその他の初期化パラメーターを取得できます。

query {
getStripeConfiguration {
	apiKey
		locale
		appInfo
		options {
			betas
			apiVersion
		}
	elementsOptions
	}
}

決済フローで支払い方法をトークン化する

PaymentElement を使用すると、決済フローで顧客から支払い方法を収集できます。顧客が支払い方法の詳細を指定して注文するをクリックした後に、支払い方法をトークン化して使用し、注文を行うことができます。createPaymentMethod を呼び出して、PaymentElement で指定された詳細から支払い方法トークンを生成します。

var stripe = Stripe(API_PUBLISHABLE_KEY);

var options = {
  mode: 'payment',
  amount: 1099,
  currency: 'eur'
};

var elements = stripe.elements(options);
var paymentElement = elements.create('payment');
paymentElement.mount('#payment-element');

var placeOrder = function()
{
    elements.submit().then(function()
    {
        stripe.createPaymentMethod({
            elements: elements,
            params: {
                billing_details: {
                    name: 'Jenny Rosen'
                }
            }
        }).then(function(result)
        {
            if (result && result.paymentMethod)
            {
                // Success
            }
        });
    });
}

トークン化された支払い方法を渡す

支払い方法トークンの取得後に、setPaymentMethodOnCart を呼び出して注文で支払い方法を設定する必要があります。

mutation {
  setPaymentMethodOnCart(input: {
      cart_id: "CART_ID"
      payment_method: {
        code: "stripe_payments"
        stripe_payments: {
          payment_method: "PAYMENT_METHOD_ID"
          save_payment_method: true
        }
      }
  }) {
    cart {
      selected_payment_method {
        code
      }
    }
  }
}

setPaymentMethodOnCart の以下のパラメーターを使用します。

パラメーター	タイプ	説明
`payment_method`	文字列	このパラメーターを使用して、トークン化された支払い方法 ID を渡します。顧客が決済フローで保存済みの支払い方法を選択した場合は、保存済みの支払い方法のトークンを渡すこともできます。
`save_payment_method`	ブール値	支払い方法を保存するかどうかを指定します。
`cvc_token`	文字列	保存済みのカードに対してセキュリティコードが有効になっている場合は、このパラメーターを使用してセキュリティコードトークンを渡して確認を実行します。

注文する

支払い方法トークンの設定後は、Adobe Commerce placeOrder ミューテーションを使用して注文を行うことができます。

mutation {
  placeOrder(input: {cart_id: "CART_ID"}) {
    order {
      order_number
      client_secret
    }
  }
}

上記の例では、client_secret をリクエストしています。これはデフォルトの placeOrder ミューテーションパラメーターではありません。Stripe モジュールでこれが追加されているのは、注文が行われた後にこのパラメーターを使用して、選択した支払い方法に固有の詳細を確定できるようにするためです。stripe.handleNextAction(client_secret) メソッドを使用して支払いを確定できます。クレジットカードに対してインライン 3D セキュア認証を実行したり、特定の支払い方法で印刷可能なクーポンを表示したり、認証のために顧客を外部にリダイレクトしたりするといったオプションをご利用いただけます。

注文振り分けフロー

支払い方法のタイプが card または link で、3D セキュア (3DS) による顧客認証を必要とする場合、以下のプロセスが実行されます。

注文は Pending Payment ステータスになります。
client secret がフロントエンドに渡され、認証が実行されます。
認証が成功すると、クライアント側で支払いが回収され、顧客は注文成功ページにリダイレクトされます。
charge.succeeded Webhook イベントがウェブサイトのサーバー側に届きます。
モジュールはイベントを処理し、宗門ステータスを Payment Pending から processing に変更します。

この手順は、GraphQL のデフォルトですが、Rest API ではデフォルトではありません。REST API で顧客認証が必要な場合、注文は Authentication require: client_secret エラーで失敗します。 client_secret を使用して支払いを認証し、認証の成功後に注文を再試行する必要があります。このアプローチの利点は、支払いが成功するまで在庫が保持されないことです。GraphQL でこの手順を使用するには、モジュールの etc/config.xml ファイルを編集して、<graphql_api> ノードの下に card と link を追加します。

<manual_authentication>
     <rest_api>card,link</rest_api>
     <graphql_api>card,link</graphql_api>
</manual_authentication>

保存済みの支払い方法を取得する

listStripePaymentMethods を使用して、有効な決済フローセッションで顧客の保存済みの支払い方法のリストを取得できます。

mutation {
  listStripePaymentMethods {
    id
    created
    type
    fingerprint
    label
    icon
    cvc
    brand
    exp_month
    exp_year
  }
}

支払い方法を保存する

addStripePaymentMethod を使用して、支払い方法を顧客のアカウントに保存できます。payment_method パラメーターは、トークン化された支払い方法 ID です。このトークン化プロセスは、決済フローでのトークン化プロセスと同様です。

mutation {
  addStripePaymentMethod(
    input: {
      payment_method: "PAYMENT_METHOD_ID"
    }
  ) {
    id
    created
    type
    fingerprint
    label
    icon
    cvc
    brand
    exp_month
    exp_year
  }
}

保存済みの支払い方法を削除する

deleteStripePaymentMethod を使用して、顧客がアカウントで保存済みの支払い方法を削除できるようにすることが可能です。

ほとんどの用途で、支払い方法のフィンガープリントを渡すことをお勧めします。これにより、そのフィンガープリントに一致している支払い方法がすべて削除されます。listStripePaymentMethods ミューテーションは、自動的に重複を削除してから、特定のフィンガープリントに一致している最近追加された支払い方法を返します。ただし、ID だけで支払い方法を削除した場合は、listStripePaymentMethods の結果には、同じフィンガープリントで保存済みの古い支払い方法が含まれることがあります。

mutation {
  deleteStripePaymentMethod(
    input: {
      payment_method: "paste a payment method ID here"
      fingerprint: null
    }
  )
}