Enable digital wallets

13 min

Apple Pay and Google Pay are enabled per account. Contact Jetpay support to turn them on.

Let customers pay with a digital wallet in the payment form you already embed at checkout. Currently supported:

Apple Pay

Google Pay

There are no changes to your API integration. Once wallets are enabled on your account, the buttons appear in the payment form automatically. You only need to update your iframe and, for Apple Pay in production, verify your domain.

Prerequisites

Getting your API KeyJetpay API Key

A checkout that embeds the Jetpay payment form in an iframe. If you haven't built this yet, start with Collect a payment method at checkoutCollect a payment method at checkout.

Apple Pay and Google Pay enabled on your account by Jetpay

Setup overview

sequenceDiagram
    autonumber
    participant Platform
    participant Jetpay

    Platform->>Jetpay: Ask support to enable Apple Pay and Google Pay
    Platform->>Platform: Add allow="payment" to the iframe
    Note over Platform,Jetpay: Demo is ready to test at this point
    Jetpay-->>Platform: Send the Apple domain association file
    Platform->>Platform: Host the file on each production checkout domain
    Platform->>Jetpay: Send your production domains
    Jetpay->>Jetpay: Register the domains with Apple Pay

Implementation details

Allow payments in your iframe

Safari won't show Apple Pay inside an iframe from another domain unless the iframe allows it. Add allow="payment" to the iframe that loads the payment form URL from POST /transaction/{identifier}/pay-debit/url.

<iframe
  src="<payment_form_url>"
  allow="payment"
  title="Payment form">
</iframe>

This is the only change you need to test in the demo environment.

Host the Apple domain association file (production)

For Apple Pay in production, Apple has to confirm you own the domain your customers see in the address bar. Jetpay sends you the domain association file.

Host it, unchanged, at this exact path on every domain where customers check out:

https://<your_domain>/.well-known/apple-developer-merchantid-domain-association

Check that the file is publicly reachable before you move on:

curl -i https://checkout.example.com/.well-known/apple-developer-merchantid-domain-association

You should get an HTTP 200 with the file's contents. Some hosting platforms don't publish folders whose names start with a dot, so if you get a 404, check your host's settings for .well-known.

Send us your domains (production)

Once the file is live, send each production checkout domain to Jetpay support. Include every subdomain separately, for example both example.com and checkout.example.com. We register them for Apple Pay, and the button starts showing on those domains.

Google Pay needs no extra steps from you.

Handling failures

The Apple Pay button doesn't appear. The payment form hides the button without showing an error. Check, in order:

The iframe has allow="payment".

You're testing in Safari.

In production, the domain association file loads at the exact path above on the domain in the address bar.

In production, you've sent us that exact domain, including its subdomain.

Domain registration fails. We can only register a domain once Apple can reach the file on it. Run the curl check above, fix any 404, and let us know so we can try again.

It works in demo but not in production. Demo only needs allow="payment". Production also needs the hosted file and a registered domain.

Testing

Test in the demo environment first:

Add allow="payment" to your iframe.

Open your checkout in Safari on a Mac or iPhone and confirm the Apple Pay button appears.

Open it in Chrome and confirm the Google Pay button appears.

You don't need the domain association file or a registered domain in demo. In browsers other than Safari, Apple Pay may show a QR code so the customer can finish on their iPhone instead.

Before you go live, run the curl check against each production domain.

Best practices

Add allow="payment" everywhere you embed the form. Ship it in every environment so demo and production behave the same.

Host the file before you send us a domain. Registration fails if Apple can't reach it.

Keep the file in place. Don't remove or change it after setup.

List every checkout domain. Staging, regional and white-label domains each need their own registration if customers pay there in production.

FAQ

Do I need to change my API calls? No. You use the same payment form URL. The wallet buttons appear in the form once they're enabled on your account.

Which domain do I register: mine or Jetpay's? Yours. Apple checks the domain shown in the customer's address bar, which is your checkout page, not the payment form inside the iframe.