Skip to content

Apple Pay and Google Pay setup

Flint-hosted checkout and payment links run on Flint's domain, so Apple Pay and Google Pay work there with no setup. When checkout runs on your own domain, as in Embedded payments or Build your own checkout, Stripe Elements shows wallet buttons only on hostnames you have registered with Flint.

Registration controls whether the buttons render, not which wallets you offer. The order's payment_collection.stripe.elements.payment_options lists apple_pay and google_pay from your payment options whether or not the current hostname is registered.

Before you start#

Use an administrative key. Registering needs payments.payment_method_domains.write, which also covers reads. Keep it on a separate key from the one your checkout backend uses for orders.

Finish payment onboarding. Until the environment's payment account is ready, registration returns MERCHANT_NOT_READY with reason onboarding_required.

Serve checkout over HTTPS. Wallets do not render on plain HTTP, including http://localhost.

On the web, including Flint-hosted checkout, you do not need an Apple Merchant ID, a certificate signing request, or a domain association file. Flint registers the hostname with Stripe on your payment account, and Stripe handles Apple merchant validation.

Apple Pay inside a native iOS app isn't supported yet. An iOS app can offer Apple Pay through hosted checkout in SFSafariViewController, as Payments in mobile apps describes.

Register each hostname#

Register every hostname that shows a wallet button. example.com, www.example.com, and shop.example.com are three separate registrations. Send the bare hostname: no scheme, path, port, IP address, or wildcard. Write internationalized hostnames in Punycode.

cURL
curl -X POST https://api.withflintpay.com/v1/payment-method-domains \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Idempotency-Key: pmd-shop-example-com" \
  -d '{"domain_name": "shop.example.com"}'
JSON
{
  "data": {
    "payment_method_domain_id": "pmdom_1kmn0aExample",
    "version": 1,
    "domain_name": "shop.example.com",
    "status": "active",
    "validation_status": "active",
    "payment_option_statuses": [
      {"payment_option": "apple_pay", "status": "active"},
      {"payment_option": "google_pay", "status": "active"}
    ],
    "created_at": "2026-09-22T12:00:00Z",
    "updated_at": "2026-09-22T12:00:00Z"
  },
  "request_id": "req_..."
}

A registration belongs to the environment of the key that made it. A sandbox key registers the hostname in that sandbox only, so register again with a live key before going live.

Retrying with the same Idempotency-Key returns the original registration. Registering a hostname that already exists in the environment returns 409 ALREADY_EXISTS, and details[0].current_resource names the existing payment_method_domain.

If your payment form runs in an iframe on a different hostname from the page around it, register both hostnames and add allow="payment" to the iframe.

With the CLI, send the same body from a file:

Shell
flint payment-method-domains create --input request.json

Check each hostname#

Read the registration's validation_status for the overall answer, and payment_option_statuses, which reports each wallet's domain status as active, inactive, or unavailable:

  • active: the registration is on, and Apple Pay and Google Pay are both ready on this hostname.
  • action_required: the registration is inactive, or at least one wallet is not active. Check payment_option_statuses.
  • unavailable: Flint could not read a wallet's status, for example while the environment's payment account is not ready. Check onboarding, then re-check the hostname.

List every registration in the environment to audit your hostnames:

cURL
curl "https://api.withflintpay.com/v1/payment-method-domains?page_size=100" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY"

To check one hostname, filter by domain_name:

cURL
curl "https://api.withflintpay.com/v1/payment-method-domains?domain_name=shop.example.com" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY"

domain_name matches the whole registered hostname, so example.com doesn't find shop.example.com. Flint trims surrounding whitespace and lowercases it first, so Shop.Example.com finds the same registration. It follows the registration rules: one ASCII hostname, with internationalized hostnames in Punycode. A URL, port, IP address, wildcard, comma-separated list, repeated key, or empty value returns 400 INVALID_REQUEST with param: domain_name. A hostname you haven't registered in the environment returns an empty data array.

Reads return the result of the most recent check and do not run it again. After you fix a hostname, run the check again by setting the registration's status to active. Send the registration's version as expected_version:

cURL
curl -X PATCH https://api.withflintpay.com/v1/payment-method-domains/pmdom_1kmn0aExample \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "Idempotency-Key: pmd-shop-example-com-recheck-1" \
  -d '{"expected_version": 1, "status": "active"}'

Setting status to inactive turns wallet buttons off on that hostname.

version increases each time a change to the registration is recorded, including a check you run with PATCH. Reads don't change it. expected_version is optional. A stale value returns 409 VERSION_CONFLICT with the current version in details[0].current_version, and Flint doesn't contact Stripe: read the registration again, check whether the change you wanted already happened, and send a new request with the new version and a new Idempotency-Key if it still needs to.

If a wallet stays inactive after a live check, confirm the registered hostname matches the browser's address bar exactly, run the check again, and ask Flint Help with the payment_method_domain_id if it is still inactive. There is no file to fix: Stripe activates wallets on registration. If every status is active and the button still does not appear, the cause is in your checkout page or the device. See Verified, but still no button.

Test the buttons#

Warning: A sandbox check is not a live check

A sandbox registration reports active right away, even for a hostname that does not exist. It confirms your integration, not your domain. The live registration is the first real check of the hostname.

Test locally through a tunnel. Run a tunnel such as ngrok or cloudflared to get an HTTPS hostname for your local checkout, then register that hostname in your sandbox. Tunnel hostnames often change between sessions, and each new one needs its own registration.

Apple Pay renders in Safari on an Apple device with a card in Apple Wallet. Wallet does not accept test card numbers, so add a real card and pay with a sandbox key.

Google Pay renders in a browser signed in to a Google account with a saved card, such as Chrome. Save a real card to the account and pay with a sandbox key.

A sandbox payment runs in test mode, so the real card is not charged. Use the test cards to exercise declines and 3D Secure through the card form.

Headless Chrome, Playwright, Puppeteer, and CI browsers have no wallet, so the buttons never render there. Test wallets on a real device.

Before you go live:

  1. Register every live checkout hostname with a live key, including both www and the apex domain if checkout runs on both.
  2. Confirm each one returns validation_status: "active".
  3. Load checkout on a real Apple device and in Chrome, and confirm both buttons appear.

Common errors#

  • HTTP 400
    domain_name is invalid. Send one exact hostname, such as shop.example.com, with no scheme, path, port, IP address, or wildcard
  • HTTP 409
    The hostname is already registered in this environment. Use the payment method domain in details[0].current_resource
  • HTTP 409
    Reason onboarding_required. Complete payment onboarding for this environment, then register again
  • HTTP 409
    VERSION_CONFLICTRefresh, then retry
    The registration changed after you read it. Read it again and decide whether to send the change with the new version
  • HTTP 409
    CONCURRENT_MODIFICATIONRetry the same request
    Another change to this registration was starting, and nothing changed. Send the same request again with the same Idempotency-Key
  • HTTP 409
    OPERATION_IN_PROGRESSRetry the same request
    Another registration change is running. Wait for Retry-After, then retry the same request with the same Idempotency-Key
  • HTTP 500
    Flint can't safely recover an earlier change to this registration. Read the registration, then follow the read for each route before you submit another change
  • HTTP 503
    SERVICE_UNAVAILABLERetry the same request
    Flint couldn't finish the registration change. It resumes the original change when you retry with the same Idempotency-Key

Was this helpful?