Cash App Pay on file

概述

Cash App Pay on file 允许客户将其 Cash App 账户信息保存在商户账号中。这使得商家能够更方便接受 Cash App Pay 支付，买家也能快捷使用 Cash App Pay 付款。

商家可以在获得客户事先批准的情况下接受支付。客户可以授权商家向其收费，而客户无需再次进行 Cash App 支付流程。

这种设置可以实现更顺畅、更便捷的支付体验，并支持各种使用场景，如频繁购买或定期订阅。详见下方的 Cash App Pay on file 概述。

术语

• Cash App Pay： 一种数字支付方式，客户可以使用其 Cash App 账户进行支付

• Grant： 与特定客户关联的支付令牌，商家可用于发起支付。Grant可以针对不同的支付方式（Cash App Afterpay、Cash App Pay），并且可以单次或多次使用（一次性、on file）

• **[$Cashtag:](https://cash.app/help/3123-what-is-a-cashtag)** 使用 Cash App 的个人和企业的公开可访问的唯一标识符（用户名）。每个 Cash App 账户的$Cashtags 最多可更改三次

• customer ID： 开发者用于识别 Cash App 账户的非公开唯一标识符。customer ID 对 Cash App 客户不可见，且在关联的 $cashtag 更新时不会改变

Cash App Pay on file 的常见用途

Cash App Pay on file 有许多常见用途，包括：

• 电子商务零售商： 电子商务商家提供 Cash App Pay on file 以便快速结账，为客户提供更方便快捷的支付体验。它还可以减少购物车放弃率，提高平均交易额，并促进销售

• 订阅服务： 适用于需要定期付款的商品和服务商家，如月度订阅或定期订单。您可以使用 Cash App Pay on file 在每个账单周期收取客户付款。这种设置减少了每次手动付款的需求，从而确保服务不中断并改善现金流

• 预订： 预订允许客户在产品发布或补货前下单。Cash App Pay on file 为商家提供灵活性，让他们可以在客户下预订单后决定何时以及如何向客户收费

• 酒店和租赁： 酒店和租赁商家通常使用 Cash App Pay on file 来支付预付订金和额外费用，如客房服务

Cash App Pay on file 概述

以下是 Cash App Pay on file 流程概述：

1. 存储 Cash App Pay on file： 首先，客户必须成功关联其 Cash App 账户，并授权商家代表他们去存储 Cash App Pay on file。完成后，商家可以访问 Cash App Pay on file grant 以及客户关联的 $cashtag 和customer ID。

2. 使用 Cash App Pay on file 支付： 一旦 Cash App Pay on file grant 获得批准并是active状态，商家可以使用该grant代表客户发起 Cash App Pay 支付。

3. 管理 Cash App Pay on file： 客户成功将其 Cash App 账户与特定商家关联后，可以执行特定操作。这些操作包括更新其 $cashtag 或撤销其 Cash App Pay on file grant。当这些操作发生时，商家需要获取这些更新并更新客户相关的 Cash App Pay on file 详细信息。

Cash App Pay on file 的优缺点

对许多商家来说，存储 Cash App Pay on file 是很常见的操作，但需要考虑以下优点和缺点：

优点

• 提高客户便利性： 对回头客来说，商家结账更快更容易，因为他们只需保存一次 Cash App Pay on file 即可用于后续支付。这可能带来更多销售机会、降低购物车放弃率、提高平均交易额等

• 提升客户透明度： 客户可以直接在 Cash App 中跟踪和管理已关联 Cash App 账户的商家。具体来说，客户可以解除与特定商家的 Cash App Pay on file 令牌链接，以防止未来不必要的付款。减少不必要的付款意味着减少退款和拒付

• 增强集成稳定性： Cash App Pay on file 客户只需链接一次 Cash App 账户，而一次性支付则要求客户每次支付都要链接 Cash App 账户。这些 Cash App 链接的技术问题不会影响已成功存储 Cash App Pay on file 的客户进行下单操作

缺点

• 管理 Cash App Pay 状态更新： 商家需要跟踪 Cash App Pay on file 是否过期和状态更新。未能及时更新 Cash App Pay 信息可能导致支付被拒绝和服务中断。这可能影响客户体验

Cash App Pay on file 详细工作原理

只存储 Cash App Pay on file

要存储 Cash App Pay on file，商家首先需要检索其 Cash App Pay Brand ID。使用 Retrieve Mapping 接口完成此任务：

示例响应

1
[ 
2
  { 
3
    "name": "default", 
4
    "externalBrandId": "BRAND_xxxxxxxxxx" 
5
  } 
6
]

获取Brand ID 后，商家应初始化 Afterpay.js 以请求 Cash App on file grant。cashAppBrandId 设置为之前检索的Brand ID。

示例代码：

1
function initializeForCashAppOnFileGrant() { 
2
  var cashAppPayOnFileOptions = { 
3
    button: false, // set to false if using custom button 
4
    onComplete: function(event) { 
5
      const { cashtag, expiresAt, grantId, id } = event.data; 
6
      console.log("Data object: ", event.data); 
7
      console.log("Cashtag: ", cashtag); 
8
      console.log("ExpiresAt: ", expiresAt); 
9
      console.log("GrantId: ", grantId); 
10
      console.log("Id: ", id); }, 
11
    redirectUrl: "https://www.example.com", // where mobile customers should be redirected to 
12
    cashAppBrandId: "BRAND_xxxxxxxxxx" 
13
  } 
14
15
  AfterPay.initializeForCashAppOnFileGrant({ 
16
    countryCode: "US", 
17
    cashAppPayOnFileOptions 
18
  }); 
19
}

当客户成功链接其 Cash App 账户后，onComplete 回调会返回 Cash App Pay on file grant，以及关联客户的 $cashtag 和customer ID。商家应存储这些数据以供将来使用。

Cash App Pay on file 免责声明建议文案

Cash App 建议您在客户存储 Cash App Pay on file 的地方添加以下免责声明：

By continuing, you authorize {{Merchant Name}} to debit your Cash App account for this payment and future payments in accordance with {{Merchant Name}}’s terms, until this authorization is revoked. You can change this authorization anytime in your Cash App Settings.

使用 Cash App Pay on file 支付

1. 要发起 Cash App Pay on file 支付，商家必须使用有效的 Cash App Pay on file grant，并创建带有 isCashAppPay: true 参数的新 Cash App Afterpay 结账。

2. 使用创建结账接口生成结账令牌。然后使用此结账令牌和grant ID 通过直接捕获或授权接口授权新支付。

在结账流程中存储 Cash App Pay on file

如果客户在完成商家的结账流程的同时尝试存储其 Cash App Pay on file，更适用这个流程。该流程使商家能够以更简化的方式完成存储 Cash App Pay on file 并使用 Cash App Pay on file 支付。执行以下操作：

1. 调用 创建结账 接口并添加 isCashAppPay: true 参数。

2. 将令牌与标准结账流程结合使用，但调用 AfterPay.initializeForCashAppPay 而不是 Cash App Afterpay。在 Afterpay.initializeForCashAppPay 的 cashAppPayOptions 中包含 requestOnFileGrant: true。

3. 存储在 onComplete 回调中返回的 Cash App Pay on file grant、$cashtag 和customer ID。

4. 调用Auth或Direct Capture接口，并确保在请求中包含 Cash App Pay on file grant。

示例代码：

1
function initAfterPay() { 
2
  var cashAppPayOptions = { 
3
    requestOnFileGrant: true, 
4
    button: { size: 'small', // "medium" | "small" width: 'full', // "full" | "static" theme: 'dark', // "dark" | "light" shape: 'round' // "round" | "semiround" }, 
5
    redirectUrl: window.location.href, // where mobile customers should be redirected to
6
    onComplete: function(event) { 
7
      const { cashtag, expiresAt, grantId, id, token } = event.data; 
8
      console.log("Data object: ", event.data); 
9
      console.log("Cashtag: ", cashtag); 
10
      console.log("ExpiresAt: ", expiresAt); 
11
      console.log("GrantId: ", grantId); 
12
      console.log("Id: ", id); 
13
      console.log("Token: ", token); }, /* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */ 
14
  eventListeners: { 
15
    "CUSTOMER_INTERACTION": ({ isMobile }) => { 
16
      console.log(`CUSTOMER_INTERACTION`) 
17
      if (isMobile) { // captureMobileMetrics() } 
18
      else { // captureDesktopMetrics() } }, 
19
        "CUSTOMER_REQUEST_DECLINED": () => { console.log(`CUSTOMER_REQUEST_DECLINED`) }, 
20
        "CUSTOMER_REQUEST_APPROVED": () => { console.log(`CUSTOMER_REQUEST_APPROVED`) }, 
21
        "CUSTOMER_REQUEST_FAILED": () => { console.log(`CUSTOMER_REQUEST_FAILED`) } } } ​ 
22
  AfterPay.initializeForCashAppPay({ countryCode: "US", token: "ORDER_TOKEN_PLACEHOLDER", cashAppPayOptions }); 
23
}

管理 Cash App Pay on file

一旦客户授权了 Cash App Pay on file grant，商家应确保实施以下功能。这些功能确保 Cash App Pay on file 功能的最佳运行：

• 在商家侧撤销 Cash App Pay on file grant： 客户能直接在商家账户设置或商家结账流程中撤销其 Cash App Pay on file grant。这确保客户不再需要时，能停用 on file grants。它建立了客户信任，因为客户可以直接在商家方管理其支付方式，而不是在 Cash App 中进行更改

  • 当客户解除其 Cash App Pay on file 链接时，使用Revoke Grant接口撤销active的 Cash App Pay on file grant

• 通过 Cash App 撤销 Cash App Pay on file grant： 客户可以在其 Cash App 设置中撤销与特定商家的 Cash App Pay on file grant。因此，商家应订阅这些更新，并为在 Cash App 中选择撤销 on file grant的客户，做 Cash App Pay on file 解绑

  • 使用Event: Grant Updatedwebhook 删除在 Cash App 中解除链接的 Cash App Pay on file grant

• Cash App Pay 更新： 客户可以更改其 Cash App 账户详细信息，如更新其 $cashtag。此外，on file grant在 10 年后过期。因此，商家订阅 Cash App Pay grant状态更新并保持其记录更新很重要

  • 使用Event: Grant Status Updatedwebhook 订阅与特定 Cash App Pay on file grant相关的 Cash App Pay 更新

  • 使用Retrieve Grant接口检索 Cash App Pay on file grant的当前状态