Cash App Pay on file

Overview

Cash App Pay on file allows customers to save their Cash App accounts with specific merchants. This makes it easy for merchants to take Cash App Pay payments and for buyers to make Cash App Pay payments.

Merchants can take a payment with the customer’s prior approval. Customers can authorize merchants to charge them in the future, without having to go through a Cash App payment flow.

This setup allows for smooth, more convenient payment experiences and enables various use-cases such as frequent purchases or recurring subscriptions. See the Overview of Cash App Pay on file below.

Terminology

• Cash App Pay: A digital payment method where customers can make payments with their Cash App account

• Grant: A payment token associated with a specific customer that merchants can use to initiate payments. Grants can be scoped to different payment methods (Afterpay, Cash App Pay) and can be consumed one or more times (one-time, on file)

• $Cashtag: A publicly-accessible, unique identifier (username) for individuals and businesses using Cash App. $Cashtags can be changed up to three times for each Cash App account

• Customer ID: A non-public, unique identifier for developers to identify Cash App accounts. Customer ID is not accessible to Cash App customers and will not change if the associated $cashtag is updated

Common Uses of Cash App Pay on file

There are many common uses of Cash App Pay on file, several include:

• Ecommerce Retailers: Ecommerce merchants offer Cash App Pay on file to facilitate faster checkouts and enable more delightful payment experiences for their customers. It can also reduce cart abandonment, increase average transaction value, and boost sales

• Subscription Services: These are for merchants who offer goods and services that need regular payments, such as monthly subscriptions or recurring orders. You can use Cash App Pay on file to receive a customer payment during each billing cycle. This setup reduces the need for a manual payment each time, which allows for uninterrupted service and improved cash flow

• Pre-orders: Pre-orders allow customers to order products before they are released or restocked. Cash App Pay on file provides flexibility for merchants and empowers them to decide when and how to charge customers after a customer has placed a pre-order

• Hospitality and Rentals: Hospitality and rental merchants typically use Cash App Pay on file to cover advanced reservations and incidental charges such as room service

Overview of Cash App Pay on file

Here is an overview of the Cash App Pay on file process:

1. Storing Cash App Pay on file: First, customers must successfully link their Cash App account and authorize merchants to store Cash App Pay on file on their behalf. Once successfully completed, merchants have access to a Cash App Pay on file grant and the customer’s associated $cashtag and customer ID.

2. Taking Payments with Cash App Pay on file: Once a Cash App Pay on file grant is approved and active, merchants can use the grant to initiate Cash App Pay payments on behalf of the customer.

3. Managing Cash App Pay on file: After a customer successfully links their Cash App account with a specific merchant, they may take specific actions. These actions include updating their $cashtag or revoking their Cash App Pay on file grant. When these actions occur, it is important for merchants to get these updates and update relevant Cash App Pay on file details for customers.

Pros and Cons of Cash App Pay on file

Storing Cash App Pay on file is standard practice for many merchants, but there are benefits and drawbacks to consider:

Pros

• Increased Customer Convenience: Merchant checkout is quicker and easier for returning customers as they can save Cash App Pay on file once and use it for subsequent payments. This can lead to more sales opportunities, lower cart abandonment, increased average transaction value, and more

• Improved Customer Transparency: Customers can track and manage merchants they have linked their Cash App account with directly within Cash App. Specifically, customers can unlink Cash App Pay on file tokens with specific merchants to prevent future unwanted payments. Fewer unwanted payments mean fewer refunds and chargebacks

• Stronger Integration Resilience: Cash App Pay on file customers only link to their Cash App account once, whereas one-time payments require customers to link their Cash App account for each payment. Integration issues that affect the Cash App linking process will not affect customers who have already successfully stored Cash App Pay on file with a particular merchant

Cons

• Managing Cash App Pay Updates: Merchants need to keep track of Cash App Pay on file expirations and updates. Failing to update Cash App Pay information on time can lead to declined payments and interrupted service. This may affect customer relationships

Suggested copy for Cash App Pay on file disclaimer

For best practice, Cash App recommends you add the following disclaimer wherever customers can store 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.

Integration guide

Store Cash App Pay on file without a payment

Use this flow when a customer links Cash App Pay outside checkout, such as from a payment methods page or wallet view. AfterPay.initializeForCashAppOnFileGrant requests only an on-file grant. It does not create or process a payment.

1. Call the Retrieve Mapping endpoint to retrieve your Cash App Pay brand ID. The response calls the brand ID externalBrandId.

   Example response:

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

2. Pass the brand ID to AfterPay.initializeForCashAppOnFileGrant as cashAppBrandId in cashAppPayOnFileOptions.

3. After the customer approves the request, read the following values from the onComplete callback:

   • grantId: The on-file grant ID for future payments
   • expiresAt: The on-file grant expiration date
   • cashtag: The customer’s $cashtag
   • id: The Cash App customer ID

4. Store grantId, expiresAt, cashtag, and id for future use. To take a payment later, create a new checkout and pass the stored grantId when you call Auth or Direct Capture.

Example code:

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://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
}

Taking Payments with Cash App Pay on file

To initiate a Cash App Pay on-file payment, follow these steps:

Step 1: Create a Checkout

Call the Create Checkout endpoint (/v2/checkouts) with the isCashAppPay: true parameter. This provides Afterpay with order and customer information.

Request

1
{
2
    "amount": {
3
        "amount": "100.00",
4
        "currency": "USD"
5
    },
6
    "consumer": {
7
        "givenNames": "Joe",
8
        "surname": "Consumer",
9
        "email": "test@example.com"
10
    },
11
    "merchant": {
12
        "redirectConfirmUrl": "https://example.com/checkout/confirm",
13
        "redirectCancelUrl": "https://example.com/checkout/cancel"
14
    },
15
    "merchantReference": "merchant-order-123",
16
    "isCashAppPay": true
17
}

Response

1
{
2
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
3
    "expires": "2025-07-23T18:39:58.634Z",
4
    "redirectCheckoutUrl": "https://portal.afterpay.com/us/checkout/?token=005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2"
5
}

Step 2: Process the Payment

Once you have the checkout token, use it along with the Cash App Pay on-file grant ID to process the payment. You can choose one of the following methods:

Option A: Auth (then Capture later)

Call the Auth endpoint (/v2/payments/auth) to authorize the payment. Include the grantId in the request body. You can then capture the payment separately.

Request

1
{
2
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
3
    "grantId": "002.xxxxxxxxxx",
4
    "merchantReference": "merchant-order-123"
5
}

Option B: Direct Capture

Call the Direct Capture endpoint (/v2/payments/capture) to authorize and capture the payment in a single step. Include the grantId in the request body.

Request

1
{
2
    "token": "005.2fkv5o963b132z8ppa34srlh60987y87d55re237wsg9tr4q2",
3
    "grantId": "002.xxxxxxxxxx",
4
    "merchantReference": "merchant-order-123"
5
}

Store Cash App Pay on file during checkout

Use this flow when a customer links Cash App Pay to a merchant for the first time during checkout. With includeOnFileGrant: true, the customer approves both the current one-time payment and an on-file grant for future payments in the same Cash App Pay flow.

1. Call the Create Checkout endpoint with isCashAppPay: true.

2. Pass the checkout token to AfterPay.initializeForCashAppPay. Set includeOnFileGrant: true in cashAppPayOptions. You can optionally provide an accountReferenceId for the customer.

3. After the customer approves the request and Afterpay validates the payment grant, read the following values from the onComplete callback:

   • status: The result of payment grant validation
   • orderToken: The checkout token for the current payment
   • onFileGrant.grantId: The on-file grant ID for future payments
   • onFileGrant.expiresAt: The on-file grant expiration date
   • cashtag: The customer’s $cashtag

4. If status is SUCCESS, process the current checkout by calling Auth or Direct Capture. Set the request’s token to orderToken. Do not include onFileGrant.grantId in the Auth or Direct Capture request for this checkout.

   Example Direct Capture request for the current checkout:

   1
   {
   2
     "token": "CURRENT_ORDER_TOKEN",
   3
     "merchantReference": "current-order-123"
   4
   }

5. After the initial payment returns an APPROVED status, store onFileGrant.grantId, onFileGrant.expiresAt, and cashtag for future payments.

6. For a future payment, call Create Checkout to create a new checkout and receive a new checkout token. Then call Auth or Direct Capture with the new token and the stored onFileGrant.grantId.

   Example Direct Capture request for a future checkout:

   1
   {
   2
     "token": "NEW_ORDER_TOKEN",
   3
     "grantId": "ON_FILE_GRANT_ID",
   4
     "merchantReference": "future-order-456"
   5
   }

The onComplete callback confirms that the customer approved the Cash App Pay request and that Afterpay validated the one-time payment grant. The payment is complete only after the Auth or Direct Capture endpoint returns an APPROVED status. If the payment is declined, show the decline to the customer and call AfterPay.restartCashAppPay() before starting another Cash App Pay request.

Example code:

1
function initAfterPay() {
2
  const cashAppPayOptions = {
3
    includeOnFileGrant: true,
4
    button: {
5
      size: "small", // "medium" | "small"
6
      width: "full", // "full" | "static"
7
      theme: "dark", // "dark" | "light"
8
      shape: "round" // "round" | "semiround"
9
    },
10
    onComplete: function(event) {
11
      const { cashtag, onFileGrant, orderToken, status } = event.data;
12
      console.log("Data object: ", event.data);
13
      console.log("Status: ", status);
14
      console.log("Order token: ", orderToken);
15
      console.log("Cashtag: ", cashtag);
16
17
      if (status === "SUCCESS" && onFileGrant) {
18
        console.log("On-file grant ID: ", onFileGrant.grantId);
19
        console.log("On-file grant expiration: ", onFileGrant.expiresAt);
20
      }
21
    },
22
    eventListeners: {
23
      "CUSTOMER_INTERACTION": ({ isMobile }) => {
24
        console.log("CUSTOMER_INTERACTION");
25
      },
26
      "CUSTOMER_REQUEST_DECLINED": () => {
27
        console.log("CUSTOMER_REQUEST_DECLINED");
28
      },
29
      "CUSTOMER_REQUEST_APPROVED": () => {
30
        console.log("CUSTOMER_REQUEST_APPROVED");
31
      },
32
      "CUSTOMER_REQUEST_FAILED": () => {
33
        console.log("CUSTOMER_REQUEST_FAILED");
34
      }
35
    }
36
  };
37
38
  AfterPay.initializeForCashAppPay({
39
    countryCode: "US",
40
    token: "ORDER_TOKEN_PLACEHOLDER",
41
    cashAppPayOptions
42
  });
43
}

Deprecated: Request an on-file grant during checkout

Existing integrations can continue to set requestOnFileGrant: true in cashAppPayOptions. This legacy mode requests only an on-file grant. It does not request or validate a one-time payment grant.

The legacy onComplete callback returns grantId, expiresAt, cashtag, id, and token as top-level fields. To process the checkout associated with this flow, call Auth or Direct Capture with both token and grantId.

Do not set requestOnFileGrant and includeOnFileGrant to true in the same configuration. Afterpay.js calls onComplete with a CANCELLED status and an error when a configuration selects both modes.

1
function initLegacyAfterPayOnFile() {
2
  const cashAppPayOptions = {
3
    requestOnFileGrant: true,
4
    onComplete: function(event) {
5
      const { cashtag, expiresAt, grantId, id, token } = event.data;
6
7
      console.log("Checkout token: ", token);
8
      console.log("On-file grant ID: ", grantId);
9
      console.log("On-file grant expiration: ", expiresAt);
10
      console.log("Cashtag: ", cashtag);
11
      console.log("Customer ID: ", id);
12
    }
13
  };
14
15
  AfterPay.initializeForCashAppPay({
16
    countryCode: "US",
17
    token: "ORDER_TOKEN_PLACEHOLDER",
18
    cashAppPayOptions
19
  });
20
}

Managing Cash App Pay on file

Once a customer has authorized a Cash App Pay on file grant, merchants should ensure they implement the following features. These features ensure optimal Cash App Pay on file functionality:

• Revoke Cash App Pay on file grant via Merchant: Customers should be able to revoke their Cash App Pay on file grant directly within the merchant account settings or the merchant checkout flow. This ensures that on file grants are deactivated once they are no longer needed. It builds customer trust as customers can manage their payment method availability directly with the merchant, versus making changes within Cash App

  • Use the Revoke Grant endpoint to revoke an active Cash App Pay on file grant when a customer unlinks their Cash App Pay on file

• Revoke Cash App Pay on file grant via Cash App: Customers can revoke their Cash App Pay on file grants with specific merchants within their Cash App settings. Therefore, merchants should subscribe to these events and unlink Cash App Pay on file for customers who have unlinked their on file grants within Cash App

  • Use the Event: Grant Updated webhook to remove Cash App Pay on file grants that were unlinked within Cash App

• Cash App Pay Updates: Customers can make changes to their Cash App account details such as updating their $cashtag. Also, on file grants expire after 10 years. Therefore, it is important that merchants subscribe to Cash App Pay grant updates, and keep their own records up to date

  • Use the Event: Grant Status Updated webhook to subscribe to Cash App Pay updates associated with specific Cash App Pay on file grants

  • Use the Retrieve Grant endpoint to retrieve the current state of Cash App Pay on file grants