Wallet setup for platforms

Enable wallets in Connect → Domains: select View setup in the domain’s Wallets column. Choose Apple Pay, Google Pay, or both for each domain and mode. The setting applies to existing and future connected accounts; each account has independent readiness. There is no repeated registration step when you connect another merchant. Adding a platform payment domain authorizes Blocks requests from that exact origin. Wallet setup is an additional step. Payments continue to belong to the receiving connected account.

Apple Pay

Download the verification file from the wallet setup dialog. Host its unchanged contents at:

https://pay.your-platform.com/.well-known/apple-developer-merchantid-domain-association

Use valid public HTTPS and return HTTP 200 directly. Do not require a login, redirect the request, return your application’s HTML fallback, or place the file behind a bot challenge. Keep the file available after setup. Every different hostname or subdomain needs its own file endpoint. Select Enable Apple Pay. Ionic checks the file and registers the hostname for each eligible receiving connected account. If you fix a failed setup, select Verify file and retry setup. Registration is asynchronous; connecting a merchant and taking card payments do not wait for it. The file status appears separately from merchant readiness, so you can finish verification before connecting your first merchant. Apple uses the bare hostname. For an authorized Blocks origin of https://pay.your-platform.com:8443, the file still belongs at the HTTPS address above on the default port. Blocks authorization continues to match the full origin, including :8443. Platforms do not supply payment credentials or register connected accounts manually. Ionic handles the registration. Separate Apple Merchant ID or certificate onboarding is not part of this flow.

Google Pay

Select Enable Google Pay for the domain. Our wallet integration does not require Apple’s verification file or an Apple-style domain-registration request for Google Pay. Google readiness remains independent if Apple setup needs attention.

Understand readiness

Status	Meaning
Disabled	The platform has disabled this wallet on this domain.
Setting up	Waiting for the receiving account’s payment setup or the domain registration to finish.
Ready	Domain and payment setup is complete.
Action needed	Fix the indicated file or registration issue, then retry.
Unavailable	Current account, connection, platform access, or registration service cannot support setup.

The dialog shows counts across all connected accounts and a paginated status list. The connected account overview shows the same statuses for a selected payment domain. Readers can inspect setup; changing settings or retrying requires web_domains:write. Ready describes setup. Displaying a wallet also requires payment eligibility, supported buyer/browser behavior, and the Wallet Block integration. Domain registration alone does not display a button or create a payment. A payment still needs correct country, currency, amount and merchant labeling. Test and live settings are separate. Turning off a wallet or removing a domain revokes local readiness immediately. Ionic keeps the domain registration so a concurrently connected account or another integration cannot lose its setup. A retained registration does not authorize Blocks requests or enable a disabled wallet.

Manage setup through the API

Use the platform’s own secret key. Do not send Ionic-Account. Mode comes from the key; connected account IDs are status filters, not credential owners.

curl https://api.ionicfi.com/v1/web_domains/wd_REPLACE_WITH_ID/wallets \
  -H "Authorization: Bearer $IONIC_PLATFORM_SECRET_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"apple_pay":true,"google_pay":true}'

Both booleans are required. POST /web_domains/{id}/wallets returns 202 with the saved policy and current counts. It does not wait for verification.

GET /web_domains/{id}/wallets: current policy and full-directory counts.
GET /web_domains/{id}/wallets/merchants: merchant status, with limit (1–100), merchant_id, and starting_after filters. Pass next_cursor to fetch the next page.
POST /web_domains/{id}/wallets/retry: request another asynchronous Apple setup attempt. This does not enable a disabled wallet.

The server SDK exposes the same operations:

import { Ionic } from '@ionicfi/sdk';

const ionic = new Ionic({ token: process.env.IONIC_PLATFORM_SECRET_KEY });
const domainId = 'wd_REPLACE_WITH_ID';
const connectedMerchantId = 'mer_REPLACE_WITH_ID';

await ionic.domainWallets.update({
  id: domainId,
  apple_pay: true,
  google_pay: true,
});
const setup = await ionic.domainWallets.get({ id: domainId });
const merchant = await ionic.domainWallets.listMerchants({
  id: domainId,
  merchant_id: connectedMerchantId,
});

Connect

Onboard merchants

Set up your platform

Accept payments

After the payment

Launch

Wallet setup for platforms

Apple Pay

Google Pay

Understand readiness

Manage setup through the API

What’s next

Add the Wallet Block

Accept payments

​Apple Pay

​Google Pay

​Understand readiness

​Manage setup through the API

​What’s next

Add the Wallet Block

Accept payments

Apple Pay

Google Pay

Understand readiness

Manage setup through the API

What’s next