Request Afterpay On File during express checkout

You can request an Afterpay On File grant while a customer completes express checkout. The customer approves the purchase and saves Afterpay as a payment method in the same Afterpay checkout flow.

Create an express checkout with an On File grant

When you call the Create Checkout endpoint:

• Set mode to express.
• Include grants with type set to ON_FILE.
• For a popup integration, set merchant.popupOriginUrl to the origin that launches Afterpay checkout.

{
  "amount": {
    "amount": "100.00",
    "currency": "USD"
  },
  "consumer": {
    "givenNames": "Joe",
    "surname": "Consumer",
    "email": "joe@example.com"
  },
  "merchant": {
    "popupOriginUrl": "https://example.com"
  },
  "merchantReference": "merchant-order-123",
  "mode": "express",
  "grants": [
    {
      "type": "ON_FILE",
      "merchantReference": "merchant-grant-123"
    }
  ]
}

Return the checkout token to onCommenceCheckout as described in the integrated shipping or deferred shipping guide. Afterpay displays the On File approval information in the express checkout flow.

Offer On File as an option

Express checkout doesn’t include a separate control that lets the customer decline On File and continue the same checkout. If you want On File to be optional, collect the customer’s choice on your site before you create the checkout token:

• If the customer opts in, include the grants array in the Create Checkout request.
• If the customer doesn’t opt in, omit grants to create a one-time express checkout.

This choice determines which type of checkout you request. The customer approves the On File grant within Afterpay checkout. Create the checkout after the customer makes their selection. A checkout token represents one of these request types and shouldn’t be reused for the other.

Create the grant and complete the payment

When onComplete returns a SUCCESS status:

1. Call the Create Grant endpoint with the checkout token. Store the returned grant ID for future payments.
2. Capture or authorize the payment using the same checkout token.

Create the grant before you capture or authorize the payment. The grant can’t be created after the purchase is finalized.

For the Create Grant request and instructions for future On File payments, see Afterpay On File.