API DevelopmentAdditional Features

Cash App Afterpay On File

Cash App Afterpay On File allows customers to save Cash App Afterpay as a payment method on your website. Similar to storing a credit card on file, this simplifies future transactions and supports recurring payments like subscriptions.

Benefits include:

  • Payment flexibility: You can offer both one-time and recurring purchases to your customers using Cash App Afterpay.
  • Faster checkout: Once a customer links their Cash App Afterpay account, they’re not required to input their Cash App Afterpay account details for future Cash App Afterpay purchases. This reduces friction – which is especially important for mobile transactions and frequent purchases.
  • Improved conversion and retention: A simpler repeat purchase experience encourages customers to return, boosts conversion rates, and increases customer lifetime value.

Supported use cases:

  • Customer-initiated transaction (CIT): A payment initiated by the customer using their saved Cash App Afterpay account details, while the customer is present on your website.
    • Example: any one-off customer-initiated purchase on your website
  • Merchant-initiated transaction (MIT): A payment initiated by the merchant, while the customer is not present on your website. These payments can be fixed or variable amounts.
    • Example: regular and ongoing subscriptions and memberships.

When a customer saves Cash App Afterpay as a payment method, a grant is created. A grant is a payment token associated with a specific customer that merchants can use to initiate future payments. After any on file payments are processed, the customer receives a Cash App Afterpay order confirmation email, regardless of whether the payment is customer-initiated or merchant-initiated.

Important

On file payment functionality is available only in Australia, New Zealand, and the United States. It’s supported only on API v2.

You must be assessed and approved by Cash App Afterpay before you can make Cash App Afterpay On FFile available to your customers. Reach out to your Cash App Afterpay account manager for more information.

Set up Cash App Afterpay On File

There are two ways to implement Cash App Afterpay On File: customers can save their Cash App Afterpay details in a virtual wallet outside the checkout flow, or they can save their Cash App Afterpay details during the checkout process itself.

Add Cash App Afterpay to a virtual wallet

Create a Cash App Afterpay grant outside of a checkout flow, in a virtual wallet for your store.

Step 1: Start the approval process

Call the Create Grant Approval endpoint (/v2/grants/approvals). This provides Cash App Afterpay with customer information, grant information, and the URL to direct the customer to when they complete the Cash App Afterpay approval flow.

Request

1{
2    "consumer": {
3        "phoneNumber": "3526669673",
4        "givenNames": "John",
5        "surname": "Doe",
6        "email": "{{email}}"
7    },
8    "merchant": {
9        "redirectConfirmUrl": "https://www.afterpay-merchant.com/confirm",
10        "redirectCancelUrl": "https://www.afterpay-merchant.com/cancel"
11    },
12    "grants": [
13        {
14            "type": "ON_FILE",
15            "merchantReference": "merchant-internal-ref"
16        }
17    ]
18}

Response

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

Step 2: Redirect to checkout

Redirect the customer to checkout using the redirectCheckoutUrl returned from the Create Grant Approval call. See Create a Checkout for instructions on launching a checkout.

Step 3: Create on file grant

If the checkout is successful, Cash App Afterpay redirects the customer to the URL you specified in the Create Grant Approval call. Next, create the grant by calling the Create Grant endpoint (/v2/grants). This call creates a grant and returns a grant ID. Save this ID for your customer’s future transactions.

Request

1{  
2         "requestId": "{{$randomUUID}}",
3         "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h"
4}

Response

1{
2    "grant": {
3        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
4        "created": "2025-07-23T16:46:55.476Z",
5        "type": "ON_FILE",
6        "status": "ACTIVE",
7        "merchantReference": "merchant-internal-ref"
8        "email": "tes***@s***.com",
9        "consumerReference": "90b2a80866ed0e7dd7f99305d3bcd8521bfad0a1eb32c63206ff11f04045d5ba"
10    }
11}

Grants can be revoked by the customer or merchant at any time. We recommend subscribing to the AgreementStatusUpdated webhook.

Save Cash App Afterpay details during checkout

Create a Cash App Afterpay grant during the checkout flow. For example, a customer can purchase a monthly subscription and pay for the first installment.

Create the grant before finalizing the purchase. If the purchase is finalized first, the grant can’t be created.

Step 1: Create a checkout

Create a checkout using the Create Checkout endpoint (/v2/checkouts) using the Grants object with type ON_FILE. See here for instructions on launching a checkout.

Request

1{
2    "amount": {
3        "amount": "15.00",
4       "currency" : "{{currency}}"
5    },
6    "consumer": {
7        "phoneNumber": "61450675141",
8        "givenNames": "",
9        "surname": "",
10        "email": "{{email}}"
11    },
12    "merchant": {
13        "redirectConfirmUrl": "https://www.afterpay-merchant.com/confirm",
14        "redirectCancelUrl": "https://www.afterpay-merchant.com/cancel"
15    },
16    "merchantReference": "merchantOrder-1234",
17    "grants": [
18        {
19        "type": "ON_FILE",
20        "merchantReference": "merchant-grant-internal-ref"
21        }
22    ]
23}

Response

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

Step 2: Create and store the on file grant

If the checkout is successful, Cash App Afterpay redirects the customer to the URL you specified in the Create Checkout call. Next, create the grant by calling the Create Grant endpoint (/v2/grants). This endpoint creates a grant and returns a grant ID. Save this ID for your customer’s future transactions.

Request

1{  
2         "requestId": "{{$randomUUID}}",
3         "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h"
4}

Response

1{
2    "grant": {
3        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
4        "created": "2025-07-23T16:46:55.476Z",
5        "type": "ON_FILE",
6        "status": "ACTIVE",
7        "merchantReference": "merchant-grant-internal-ref"
8        "email": "tes***@s***.com",
9        "consumerReference": "90b2a80866ed0e7dd7f99305d3bcd8521bfad0a1eb32c63206ff11f04045d5ba"
10    }
11}

Step 3: Capture payment

Now that you have a successful checkout pre-approval and an on file grant, choose when you want to capture the payment. You can either capture immediately or authorize and capture at a later time (authorizations last for 13 days before automatically expiring).

Request

1{
2  "requestid": "d22f5305-05f3-48a0-9131-a4e6e5f58b9a",
3  "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h",
4  "merchantReference": "merchant-order-123"
5}

Response

1{
2  "id": "300000016189",
3  "token": "001.euuugalpi1oj0kr34h9h0a72h6uqgq9ni6kcc6a0frrkpv1h",
4  "status": "APPROVED",
5  "created": "2024-03-11T20:11:42.487Z",
6  "originalAmount": {
7    "amount": "37.00",
8    "currency": "USD"
9  },
10  "openToCaptureAmount": {
11    "amount": "0.00",
12    "currency": "USD"
13  },
14  "paymentState": "AUTH_APPROVED",
15  "merchantReference": "updated-k6-reference-utaddnpx",
16  "refunds": [],
17  "orderDetails": {
18    "consumer": {},
19    "billing": {
20      "name": "Joe Customer",
21      "line1": "1004 New Avenue",
22      "postcode": "94121",
23      "countrycode": "US",
24      "phoneNumber": "2120000000"
25    },
26    "shipping": {
27      "name": "Joe Customer",
28      "line1": "1004 New Avenue",
29      "postcode": "94121",
30      "countrycode": "US",
31      "phoneNumber": "2120000000"
32    },
33    "courier": {
34      "shippedAt": "2024-01-01T08:00:00Z",
35      "name": "FedEx",
36      "tracking": "000 000 000 000",
37      "priority": "STANDARD"
38    },
39    "items": {
40      "name": "Blue Carabiner",
41      "sku": "12341234",
42      "quantity": 1,
43      "price": {
44        "amount": "40.00",
45        "currency": "USD"
46      }
47    },
48    "categories": {
49      "name": "Jeans",
50      "sku": "123412345",
51      "quantity": 1,
52      "price": {
53        "amount": "20.00",
54        "currency": "USD"
55      },
56      "categories": null
57    }
58  },
59  "discounts": [],
60  "shippingAmount": {
61    "amount": "10.00",
62    "currency": "USD"
63  },
64  "taxAmount": {
65    "amount": "0.00",
66    "currency": "USD"
67  },
68  "events": {
69    "id": "2dYbLXpOtEPQbg1DT7x9D8R4oCY",
70    "created": "2024-03-11T20:11:43.897Z",
71    "expires": null,
72    "type": "CAPTURED",
73    "amount": {
74      "amount": "37.00",
75      "currency": "USD"
76    },
77    "paymentEventMerchantReference": "k6-gsrdqspusf"
78  }
79}

Create an on file payment

Once a grant is created, you can use the grant ID to place additional Cash App Afterpay orders.

To create an order with the grant, call the Orders API (/v2/orders) and include the stored grant ID in the request.

Cash App Afterpay checks the customer’s eligibility at order creation, so we recommend making this call at the beginning of your checkout process if Cash App Afterpay is the selected payment method. If the order amount changes before the on file payment is created, create a new order with the updated amount; the original order is automatically deleted by Cash App Afterpay.

Once you’ve successfully created an order, use the token from the response to call either the Auth endpoint (/v2/payments/auth) or the Capture Full Payment endpoint (/v2/payments/capture).

On file payments require extra metadata, such as payment initiation actor and subscription details, to ensure compliant usage and improve underwriting decisions. Required fields may include:

  • enrichments.initiation.actor (required)
  • enrichments.subscription.type (required if subscription)
  • enrichments.subscription.interval (required if subscription)
  • enrichments.subscription.intervalCount (required if subscription)

Request

1{  
2         "requestId": "{{$randomUUID}}",
3         "grantId": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
4         "amount": {
5            "amount": "125.00",
6            "currency": "USD"
7        },
8        "enrichments": {
9            "initiation": {
10                "actor": "CUSTOMER"
11            }
12        }
13}

Response

1{
2    "token": "001.1hrgccv8a6th0pklh7mqranu58tb1lllau9fhngl77i44rtk",
3    "expires": "2025-07-23T19:28:06.880Z"
4}

Manage existing grants

Once a grant has been created, you can use it to initiate new on file payments or retrieve the grant details using the Retrieve Grant endpoint (/v2/grants/{grantId}).

If a customer decides to remove Cash App Afterpay as a saved payment method on your website, use the Revoke Grant endpoint (/v2/grants/{grantId}/revoke) so that the grant ID can be deactivated by Cash App Afterpay.

Response

1{
2    "grant": {
3        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
4        "created": "2025-07-23T16:46:55.476Z",
5        "type": "ON_FILE",
6        "status": "CANCELLED",
7        "merchantReference": "merchant-internal-ref"
8        "cancelled": "2025-07-23T18:15:09.316Z",
9        "email": "tes***@s***.com",
10        "consumerReference": "90b2a80866ed0e7dd7f99305d3bcd8521bfad0a1eb32c63206ff11f04045d5ba"
11    }
12}

Customers can also revoke a grant within the Cash App Afterpay app. Merchants should subscribe to the GrantStatusUpdated webhook.

1{
2  "type": "on_file_grant.status.updated",
3  "eventId": "87f5ded7-2747-4e31-95ee-8993e0ae8663",
4  "createdAt": "2025-08-22T19:34:37.497Z",
5  "data": {
6    "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
7    "type": "ON_FILE_GRANT",
8    "object": {
9      "grant": {
10        "id": "001.nkqn2oag22ehaamdo71gq1il2nnlroo85i5rj6fir8818epm4m64rjf0n0chu6kq",
11        "created": "2025-07-23T16:46:55.476Z",
12        "type": "ON_FILE",
13        "status": "CANCELLED",
14        "cancelled": "2025-08-22T19:34:35.012Z"
15      }
16    }
17  }
18}

Merchants can use the consumerReference field associated with a grant ID to map to their own customer identifier. The email field, which is masked, can be used as a customer-facing identifier.

Considerations

  1. Customers should be able to revoke grants (unlink Cash App Afterpay as a saved payment method) on your website. Customers should also be notified of any price change to a subscription at least 30 days in advance, or in adherence to any applicable laws and legal requirements.
  2. Merchants are strongly encouraged to implement Cash App Afterpay’s checkout widget for grants, as it allows merchants to show the required disclosures and payment schedule details on their checkout page prior to customers finalizing their purchases.