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:
Supported use cases:
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.
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 Afterpay before you can make Afterpay On FFile available to your customers. Reach out to your Afterpay account manager for more information.
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.
Create an Afterpay grant outside of a checkout flow, in a virtual wallet for your store.
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
Response
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.
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
Response
Grants can be revoked by the customer or merchant at any time. We recommend subscribing to the AgreementStatusUpdated webhook.
Create an 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.
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
Response
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
Response
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
Response
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).
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:
Request
Response
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
Customers can also revoke a grant within the Afterpay app. Merchants should subscribe to the GrantStatusUpdated webhook.
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.
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.
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.
Afterpay On File only supports Pay-in-4 (Pi4) — it does not support Pay Monthly (PM). Before showing the payment schedule widget or attempting to charge an on file grant, merchants should call the Get Configuration endpoint with include=paybyinstallment and include=consumerlending, and use the returned payByInstallment and consumerLending thresholds to determine which products the cart qualifies for:
The configuration response is cacheable and changes infrequently — call it on a scheduled background process (e.g. once per day) and reuse the cached thresholds to gate every cart.