> This page is for Afterpay Online Developer, version Chinese.
> For other versions, use one of these documentation indexes:
> - Main (default): https://developers.afterpay.com/afterpay-online-developer/main/llms.txt
> - v1: https://developers.afterpay.com/afterpay-online-developer/v-1/llms.txt
> - Chinese: https://developers.afterpay.com/afterpay-online-developer/chinese/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.afterpay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.afterpay.com/_mcp/server.

# 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-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](https://developers.cash.app/docs/merchant/reference/configuration/operations/list-v-2-configuration-mappings) 接口完成此任务：

#### 示例响应

```JavaScript
[ 
  { 
    "name": "default", 
    "externalBrandId": "BRAND_xxxxxxxxxx" 
  } 
]
```

> **注意**
>
> Retrieve Mapping API 响应中将Brand ID 称为 `externalBrandId`，而在下面的前端 JavaScript 中，`externalBrandId` 被称为 `cashAppBrandId`。

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

**示例代码：**

```JavaScript
function initializeForCashAppOnFileGrant() { 
  var cashAppPayOnFileOptions = { 
    button: false, // set to false if using custom button 
    onComplete: function(event) { 
      const { cashtag, expiresAt, grantId, id } = event.data; 
      console.log("Data object: ", event.data); 
      console.log("Cashtag: ", cashtag); 
      console.log("ExpiresAt: ", expiresAt); 
      console.log("GrantId: ", grantId); 
      console.log("Id: ", id); }, 
    redirectUrl: "https://www.example.com", // where mobile customers should be redirected to 
    cashAppBrandId: "BRAND_xxxxxxxxxx" 
  } 

  AfterPay.initializeForCashAppOnFileGrant({ 
    countryCode: "US", 
    cashAppPayOnFileOptions 
  }); 
}
```

当客户成功链接其 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 通过直接捕获或授权接口授权新支付。

> **注意**
>
> 一旦生成on file grant并状态是active，客户无需为新支付再走一遍结账流程。

## 在结账流程中存储 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](https://developers.cash.app/docs/merchant/reference/payments/operations/create-a-v-2-payment-auth)或[Direct Capture](https://developers.cash.app/docs/merchant/reference/payments/operations/create-a-v-2-payment-capture)接口，并确保在请求中包含 Cash App Pay on file grant。

示例代码：

```javascript
function initAfterPay() { 
  var cashAppPayOptions = { 
    requestOnFileGrant: true, 
    button: { size: 'small', // "medium" | "small" width: 'full', // "full" | "static" theme: 'dark', // "dark" | "light" shape: 'round' // "round" | "semiround" }, 
    redirectUrl: window.location.href, // where mobile customers should be redirected to
    onComplete: function(event) { 
      const { cashtag, expiresAt, grantId, id, token } = event.data; 
      console.log("Data object: ", event.data); 
      console.log("Cashtag: ", cashtag); 
      console.log("ExpiresAt: ", expiresAt); 
      console.log("GrantId: ", grantId); 
      console.log("Id: ", id); 
      console.log("Token: ", token); }, /* Optional event listeners for merchants to track customer behavior and listen for transaction events in the lifecycle */ 
  eventListeners: { 
    "CUSTOMER_INTERACTION": ({ isMobile }) => { 
      console.log(`CUSTOMER_INTERACTION`) 
      if (isMobile) { // captureMobileMetrics() } 
      else { // captureDesktopMetrics() } }, 
        "CUSTOMER_REQUEST_DECLINED": () => { console.log(`CUSTOMER_REQUEST_DECLINED`) }, 
        "CUSTOMER_REQUEST_APPROVED": () => { console.log(`CUSTOMER_REQUEST_APPROVED`) }, 
        "CUSTOMER_REQUEST_FAILED": () => { console.log(`CUSTOMER_REQUEST_FAILED`) } } } ​ 
  AfterPay.initializeForCashAppPay({ countryCode: "US", token: "ORDER_TOKEN_PLACEHOLDER", cashAppPayOptions }); 
}
```

## 管理 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**](../../reference/Grants.v2.yaml/paths/~1v2~1grants~1revoke/post)接口撤销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 Updated**](../../reference/Grants.v2.yaml/components/schemas/grant.status.updated)webhook 删除在 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 Updated**](../../reference/Grants.v2.yaml/components/schemas/grant.status.updated)webhook 订阅与特定 Cash App Pay on file grant相关的 Cash App Pay 更新

  * 使用[**Retrieve Grant**](../../reference/Grants.v2.yaml/paths/~1v2~1grants~1retrieve/post)接口检索 Cash App Pay on file grant的当前状态