Afterpay On File

Afterpay On File allows customers to save 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 Afterpay.
• Faster checkout: Once a customer links their Afterpay account, they’re not required to input their Afterpay account details for future 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 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 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 an Afterpay order confirmation email, regardless of whether the payment is customer-initiated or merchant-initiated.

Set up Afterpay On File

There are two ways to implement Afterpay On File: customers can save their Afterpay details in a virtual wallet outside the checkout flow, or they can save their Afterpay details during the checkout process itself. With either method, you can use a one-time password flow to link a customer’s Afterpay account.

Add Afterpay to a virtual wallet

Create an 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 Afterpay with customer information, grant information, and the URL to direct the customer to when they complete the 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
    "merchantReference": "merchant-approval-1234",
13
    "grants": [
14
        {
15
            "type": "ON_FILE",
16
            "merchantReference": "ref"
17
        }
18
    ]
19
}

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, 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
         "merchantReference": "ref"
5
}

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": "ref",
8
        "email": "tes***@s***.com",
9
        "consumerReference": "90b2a80866ed0e7dd7f99305d3bcd8521bfad0a1eb32c63206ff11f04045d5ba"
10
    }
11
}

Save Afterpay details during checkout

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

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": "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, 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
         "merchantReference": "ref"
5
}

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": "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).

• Immediate capture: Call the Capture Full Payment endpoint (/v2/payments/capture), following the instructions here.
• Deferred capture: Call the Auth endpoint (/v2/payments/auth), following the instructions here.

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
}

Link Afterpay account with a one-time password

You can use a one-time password flow to allow customers to link their Afterpay accounts either during the checkout process or within a virtual wallet. The API calls are the same for each location in your user interface.

Step 1: Create a grant using a one-time password

Start the account linking process by calling the Start Grant Link Flow endpoint (/v2/grants/start). This API request sends a one-time password to the mobile number or email address of an Afterpay customer, which starts the grant creation process.

Request

1
{
2
  "requestId": "request-12345",
3
  "alias": "user@example.com"
4
}

If successful, a grant token is created. Note that all requests with a valid payload receive a success response. If an Afterpay account doesn’t exist with the given email address or mobile number, the token returned may not be linked to an actual Afterpay customer and a one time code may not be sent.

Response

1
{
2
  "token": "token-123",
3
  "requestId": "request-12345",
4
  "expiresAt": "2024-01-01T00:00:00.000Z"
5
}

Step 2: Create grant

Once the customer enters their one-time password and confirms they want to link their Afterpay account to your website, create the grant. Call the Create Grant endpoint (/v2/grants) using the customer’s grant token. This endpoint creates a grant and returns a grant ID. Save this ID for your customer’s future transactions.

Create an on file payment

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

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

Afterpay checks the customer’s eligibility at order creation, so we recommend making this call at the beginning of your checkout process if 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 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).

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 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 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": "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 Afterpay app. Merchants should subscribe to the AgreementStatusUpdated webhook.

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

Considerations

1. Customers should be able to revoke grants (unlink 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 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.