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 File 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. With either method, you can use a one-time password flow to link a customer’s Afterpay account.
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
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.
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
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
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.
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:
enrichments.initiation.actor (required)
enrichments.subscription.type (required if subscription)
enrichments.subscription.interval (required if subscription)
enrichments.subscription.intervalCount (required if subscription)
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 AgreementStatusUpdated 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.