支払い取引のライフサイクル

販売者が決済アプリを統合する方法と、Payment Request API で決済取引がどのように機能するかについて説明します。

Web Payments API は、ブラウザに初めて組み込まれた専用の支払い機能です。ウェブ決済を使用すると、販売者による決済アプリとの統合が簡単になり、顧客体験が合理化され、安全性が向上します。

ウェブ決済を使用するメリットについて詳しくは、ウェブ決済による決済アプリの強化をご覧ください。

この記事では、販売者のウェブサイトでの支払い取引について説明し、決済アプリの統合の仕組みを理解できるようにします。

このプロセスは、次の 6 つのステップで構成されます。

  1. 販売者が支払い取引を開始します。
  2. 販売者が支払いボタンを表示します。
  3. お客様が支払いボタンを押します。

    BobPay(決済アプリ)ボタンが表示されたチーズショップのウェブサイトの図。

  4. ブラウザが決済アプリを起動します。

    モーダルで起動された BobPay アプリを含むチーズショップのウェブサイトの図。モーダルには配送オプションと合計費用が表示されます。

  5. お客様が詳細(配送オプションや住所など)を変更した場合、販売者はその変更を反映して取引明細を更新します。

    BobPay アプリのモーダルで、お客様が別の配送オプションを選択している図。販売者が BobPay に表示される合計費用を更新していることを示す 2 つ目の図。

  6. お客様が購入を確定すると、販売者は支払いを検証して取引を完了します。

    お客様が

ステップ 1: 販売者が支払い取引を開始する

お客様が購入を決定すると、販売者は PaymentRequest オブジェクトを作成して支払い取引を開始します。このオブジェクトには、取引に関する重要な情報が含まれています。

  • 利用可能なお支払い方法と、取引を処理するためのデータ。
  • 合計金額(必須)や商品に関する情報などの詳細。
  • 販売者が配送先住所や配送オプションなどの配送情報をリクエストできるオプション。
  • 販売者は、請求先住所、支払人の名前、メールアドレス、電話番号をリクエストすることもできます。
  • 販売者は、PaymentRequest にオプションの配送タイプ(shipping、delivery、pickup)を含めることもできます。決済アプリは、これをヒントとして使用して、UI に正しいラベルを表示できます。
const request = new PaymentRequest([{
  supportedMethods: 'https://bobpay.xyz/pay',
  data: {
    transactionId: '****'
  }
}], {
  displayItems: [{
    label: 'Anvil L/S Crew Neck - Grey M x1',
    amount: { currency: 'USD', value: '22.15' }
  }],
  total: {
    label: 'Total due',
    amount: { currency: 'USD', value : '22.15' }
  }
}, {
  requestShipping: true,
  requestBillingAddress: true,
  requestPayerEmail: true,
  requestPayerPhone: true,
  requestPayerName: true,
  shippingType: 'delivery'
});
トランザクション ID を含める

一部の決済ハンドラでは、販売者が事前に発行した取引 ID を取引情報の一部として提供することが求められる場合があります。一般的な統合では、販売者のサーバーと決済ハンドラのサーバー間の通信で合計金額を予約します。これにより、悪意のある顧客が価格を操作して、取引の最後に検証を行う販売者をだますことを防ぐことができます。

販売者は、PaymentMethodData オブジェクトの data プロパティの一部としてトランザクション ID を渡すことができます。

トランザクション情報が提供されると、ブラウザは、お支払い方法の識別子に基づいて、PaymentRequest で指定された決済アプリの検出プロセスを実行します。これにより、販売者が取引を続行する準備が整うとすぐに、ブラウザは起動する決済アプリを決定できます。

検出プロセスの詳細については、お支払い方法の設定をご覧ください。

ステップ 2: 販売者が支払いボタンを表示する

販売者は多くのお支払い方法をサポートできますが、お客様が実際に使用できるお支払い方法のボタンのみを表示する必要があります。使用できない支払いボタンを表示すると、ユーザー エクスペリエンスが低下します。PaymentRequest オブジェクトで指定された支払い方法がお客様に機能しないことが予測される場合、販売者は代替ソリューションを提供するか、そのボタンをまったく表示しないようにすることができます。

販売者は、PaymentRequest インスタンスを使用して、お客様が決済アプリを利用できるかどうかをクエリできます。

お客様は決済アプリを利用できますか?

PaymentRequest の canMakePayment() メソッドは、お客様のデバイスで決済アプリが利用可能な場合に true を返します。「利用可能」とは、お支払い方法をサポートする決済アプリが検出され、プラットフォーム固有の決済アプリがインストールされているか、ウェブベースの決済アプリが登録可能であることを意味します。

const canMakePayment = await request.canMakePayment();
if (!canMakePayment) {
  // Fallback to other means of payment or hide the button.
}

ステップ 3: ユーザーが支払いボタンを押す

お客様が支払いボタンを押すと、販売者は PaymentRequest インスタンスの show() メソッドを呼び出し、支払い UI の起動をすぐにトリガーします。

最終的な合計金額が動的に設定される場合(サーバーから取得される場合など)、販売者は合計金額が判明するまで支払い UI の起動を遅らせることができます。

支払い UI の起動を遅らせる

最終的な合計金額が確定するまで支払い UI を遅らせるデモをご覧ください。

支払い UI を遅らせるために、販売者は show() メソッドに Promise を渡します。ブラウザは、Promise が解決され、トランザクションを開始できるようになるまで、読み込みインジケーターを表示します。

const getTotalAmount = async () => {
  // Fetch the total amount from the server, etc.
};

try {
  const result = await request.show(getTotalAmount());
  // Process the result…
} catch(e) {
  handleError(e);
}

show() の引数として Promise が指定されていない場合、ブラウザはすぐに支払い UI を起動します。

ステップ 4: ブラウザが決済アプリを起動する

ブラウザは、プラットフォーム固有の決済アプリまたはウェブベースの決済アプリを起動できます(Chrome が起動する決済アプリを決定する方法をご覧ください)。

決済アプリの構築方法は、ほとんどの部分がデベロッパーに委ねられていますが、販売者との間で送受信されるイベントと、それらのイベントとともに渡されるデータの構造は標準化されています。

決済アプリが起動すると、ステップ 1 で PaymentRequest オブジェクトに渡された取引情報を受け取ります。これには、以下が含まれます。

  • お支払い方法のデータ
  • 合計金額
  • 支払い方法

決済アプリは、取引情報を使用して UI にラベルを付けます。

ステップ 5: お客様の対応に応じて販売者が取引明細を更新する方法

お客様は、決済アプリでお支払い方法や配送オプションなどの取引明細を変更できます。お客様が変更を行うと、販売者は変更イベントを受け取り、取引明細を更新します。

販売者が受け取ることができるイベントには、次の 4 種類があります。

  • お支払い方法の変更イベント
  • 配送先住所の変更イベント
  • 配送オプション変更イベント
  • 販売者検証イベント

お支払い方法の変更イベント

決済アプリは複数のお支払い方法に対応しており、販売者は、お客様の選択に応じて特別な割引を提供できます。このユースケースに対応するため、お支払い方法の変更イベントで新しいお支払い方法を販売者に通知し、販売者が割引を適用した合計金額を更新して決済アプリに返すことができます。

request.addEventListener('paymentmethodchange', e => {
  e.updateWith({
    // Add discount etc.
  });
});

配送先住所の変更イベント

決済アプリは、必要に応じてお客様の配送先住所を提供できます。これは、お客様がフォームに詳細を手動で入力する必要がなく、複数の異なる販売者のウェブサイトではなく、お好みの決済アプリに配送先住所を保存できるため、便利です。

取引の開始後に、お客様が決済アプリで配送先住所を更新すると、'shippingaddresschange' イベントが販売者に送信されます。このイベントにより、販売者は新しい住所に基づいて送料を決定し、合計金額を更新して、お支払いアプリに返すことができます。

request.addEventListener('shippingaddresschange', e => {
  e.updateWith({
    // Update the details
  });
});

販売者が更新された住所に配送できない場合は、決済アプリに返される取引明細にエラー パラメータを追加することで、エラー メッセージを表示できます。

配送オプション変更イベント

販売者は、複数の配送オプションをお客様に提示し、その選択を決済アプリに委任できます。配送オプションは、お客様が選択できる料金とサービス名のリストとして表示されます。次に例を示します。

  • 通常便 - 無料
  • 速達配送 - 5 米ドル

お客様が決済アプリで配送オプションを更新すると、'shippingoptionchange' イベントが販売者に送信されます。販売者は、送料を決定し、合計金額を更新して、決済アプリに返すことができます。

request.addEventListener('shippingoptionchange', e => {
  e.updateWith({
    // Update the details
  });
});

販売者は、お客様の配送先住所に基づいて配送オプションを動的に変更することもできます。これは、販売者が国内と海外のお客様に異なる配送オプションを提供する場合に便利です。

販売者検証イベント

セキュリティを強化するため、決済アプリは、支払いフローに進む前に販売者の検証を行うことができます。検証メカニズムの設計は決済アプリによって異なりますが、販売者検証イベントは、販売者が自身を検証するために使用できる URL を販売者に通知する役割を果たします。

request.addEventListener('merchantvalidation', e => {
  e.updateWith({
    // Use `e.validateURL` to validate
  });
});

ステップ 6: 販売者が支払いを検証し、取引を完了する

お客様が支払いを承認すると、show() メソッドは PaymentResponse に解決される Promise を返します。PaymentResponse オブジェクトには次の情報が含まれています。

  • 支払い結果の詳細
  • 配送先住所
  • 配送オプション
  • 連絡先情報

この時点では、ブラウザの UI に読み込みインジケーターが表示され、トランザクションがまだ完了していないことを示している場合があります。

支払いの失敗またはエラーが原因で決済アプリが終了した場合、show() から返された Promise は拒否され、ブラウザは支払い取引を終了します。

支払いの処理と検証

PaymentResponse の details は、決済アプリから返される支払い認証情報オブジェクトです。販売者は、この認証情報を使用して支払いを処理または検証できます。この重要なプロセスの仕組みは、決済ハンドラによって異なります。

トランザクションの完了または再試行

販売者は、取引が成功したか失敗したかを判断した後、次のいずれかを行うことができます。

  • .complete() メソッドを呼び出して、取引を完了し、読み込みインジケーターを閉じます。
  • retry() メソッドを呼び出して、お客様が再試行できるようにします。
async function doPaymentRequest() {
  try {
    const request = new PaymentRequest(methodData, details, options);
    const response = await request.show();
    await validateResponse(response);
  } catch (err) {
    // AbortError, SecurityError
    console.error(err);
  }
}

async function validateResponse(response) {
  try {
    const errors = await checkAllValuesAreGood(response);
    if (errors.length) {
      await response.retry(errors);
      return validateResponse(response);
    }
    await response.complete("success");
  } catch (err) {
    // Something went wrong…
    await response.complete("fail");
  }
}
// Must be called as a result of a click
// or some explicit user action.
doPaymentRequest();

次のステップ