付款交易的生命周期

了解商家如何集成付款应用，以及付款交易如何与 Payment Request API 协同运作。

Eiji Kitamura
米利卡·米哈吉利亚 (Milica Mihajlija)
Milica Mihajlija
X GitHub 首页

Web Payments API 是首次内置于浏览器中的专用付款功能。借助 Web Payments，商家与付款应用的集成变得更简单，同时客户体验得到了简化且更加安全。

如需详细了解使用 Web Payments 的好处，请参阅使用 Web Payments 为付款应用赋能。

本文将引导您完成商家网站上的付款交易，并帮助您了解付款应用集成的工作原理。

该过程包括 6 个步骤：

  1. 商家发起付款交易。
  2. 商家显示付款按钮。

  3. 客户按下付款按钮。

    奶酪店网站的示意图，包含 BobPay（付款应用）按钮。

  4. 浏览器启动付款应用。

    奶酪店网站的示意图，其中以模态模式启动了 BobPay 应用。该模态窗口会显示运费选项和总费用。

  5. 如果客户更改了任何详细信息（例如运费选项或地址），则商家会更新交易详细信息以反映更改。

    显示客户在 BobPay 应用模态中选择其他配送选项的示意图。第二张图显示商家更新 BobPay 中显示的总费用。

  6. 客户确认购买后，商家会验证付款并完成交易。

    一张示意图，显示了客户按下

第 1 步：商家发起付款交易

当客户决定购买时，商家将通过构造 PaymentRequest 对象来启动付款交易。此对象包含有关交易的重要信息：

  • 用于处理交易的可接受的付款方式及其数据。
  • 详细信息，例如总价（必填）和商品相关信息。
  • 商家可以请求提供配送信息（例如送货地址和运费选项）的选项。
  • 商家还可以索取账单邮寄地址、付款人姓名、电子邮件地址和电话号码。
  • 商家还可以在 PaymentRequest 中添加可选的配送类型（shipping、delivery 或 pickup）。付款应用可据此提示在其界面中显示正确的标签。
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 作为交易信息的一部分。典型的集成包括商家与付款处理程序的服务器之间的通信以预留总价。这可以防止恶意客户操纵价格，并通过在交易结束时进行验证来欺骗商家。

商家可以将交易 ID 作为 PaymentMethodData 对象的 data 属性的一部分传递。

获得交易信息后，浏览器将根据付款方式标识符完成 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() 方法，该方法会立即触发付款界面的启动。

如果最终总价是动态设置的（例如，从服务器检索），商家可以推迟发布付款界面，直到知道总价。

延迟发布付款界面

观看推迟付款界面演示，直到确定最终总价。

为了延迟付款界面，商家会将 promise 传递给 show() 方法。浏览器将显示加载指示器，直到 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 作为参数，浏览器将立即启动付款界面。

第 4 步：浏览器启动付款应用

浏览器可以启动特定于平台的付款应用，也可以启动基于网络的付款应用。（您可以详细了解 Chrome 如何确定要启动的付款应用。）

付款应用的构建方式主要由开发者决定，但从商家发出和向商家发出的事件以及与这些事件一起传递的数据的结构都是标准化的。

付款应用启动时，它会接收在第 1 步中传递给 PaymentRequest 对象的交易信息，其中包括：

  • 付款方式数据
  • 总价
  • 付款方式

付款应用使用交易信息为其界面添加标签。

第 5 步：商家如何根据客户操作更新交易详情

客户可以选择在付款应用中更改交易详情，例如付款方式和运费选项。在客户进行更改时，商家会收到更改事件并更新交易详情。

商家可以接收四种类型的事件：

  • 付款方式更改事件
  • 送货地址更改事件
  • 运费选项更改事件
  • 商家验证事件

付款方式更改事件

付款应用可以支持多种付款方式，商家可能会根据客户的选择提供特别折扣。为了涵盖此用例，付款方式更改事件可以将新的付款方式告知商家，以便商家根据折扣更新总价并将其返回给付款应用。

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

送货地址更改事件

付款应用可以选择提供客户的送货地址。这对客户来说非常方便，因为他们不必在表单中手动输入任何详细信息，并且可以将送货地址存储在首选的付款应用中，而不是存储在多个不同的商家网站上。

如果客户在交易发起后在付款应用中更新了送货地址，系统会向商家发送 'shippingaddresschange' 事件。此事件有助于商家根据新地址确定运费、更新总价，并将其返回给付款应用。

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

如果商家无法配送到更新后的地址，可以通过向返回给付款应用的交易详情添加 error 参数来提供错误消息。

运费选项更改事件

商家可以为客户提供多种配送选项，并且可以将这种选择委托给付款应用。运费选项显示为可供客户选择的价格和服务名称列表。例如：

  • 标准配送 - 免运费
  • 快递 - 5 美元

当客户更新付款应用中的运费选项时，系统会向商家发送 'shippingoptionchange' 事件。然后，商家可以确定运费，更新总价，并将其返回给付款应用。

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

商家也可以根据客户的送货地址动态修改运费选项。如果商家希望为国内和国际客户提供一组不同的配送选项，这会非常有用。

商家验证事件

为了提高安全性，付款应用可以在继续付款流程之前执行商家验证。验证机制的设计由付款应用决定，但商家验证事件用于告知商家可以使用哪个网址来验证自己。

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

第 6 步：商家验证付款并完成交易

当客户成功对付款授权后，show() 方法会返回一个解析为 PaymentResponse 的 promise。PaymentResponse 对象包含以下信息：

  • 付款结果详细信息
  • 送货地址
  • 配送选项
  • 联系信息

此时，浏览器界面可能仍会显示加载指示器，表示事务尚未完成。

如果付款应用因付款失败或错误而终止，从 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();

后续步骤