> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ionicfi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet setup for platforms

> Enable Apple Pay and Google Pay on platform payment domains and track setup for each connected account.

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](/guides/platform-payment-domains) 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:

```text theme={null}
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.

```bash theme={null}
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:

```typescript theme={null}
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,
});
```

## What's next

<CardGroup cols={2}>
  <Card title="Add the Wallet Block" icon="mobile-screen" href="/guides/wallet-block">
    Mount Apple Pay and Google Pay next to the card form.
  </Card>

  <Card title="Accept payments" icon="building" href="/guides/connect-blocks">
    Collect card payments for connected accounts with Ionic Blocks.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.