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

# Register Payment Method Domain

> Register your checkout domain with Stripe so Apple Pay and Google Pay appear in the Payment Element.

# Register Payment Method Domain

Registers the domain that hosts your checkout page as a Stripe **payment method domain**. This is required for **Apple Pay** to appear in the Stripe Payment Element rendered from a [Create Charge](/api-reference/payments/create-charge) `client_secret`. Google Pay does not require domain registration, but registering keeps its status visible alongside Apple Pay.

Registration runs on **every Stripe account that can render the Payment Element for you**:

* The Khaime US and UK platform accounts (platform-routed charges)
* Your business's own Stripe connected account (direct charges)
* Every active sub-merchant's connected account, if you operate a marketplace (marketplace charges are created **on** the sub-merchant's account, so the domain must be registered there too)

The response reports the result per account, so a partial failure on one account never blocks the others.

<Warning>
  **Before calling this endpoint**, host Stripe's Apple Pay domain association file at:

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

  Download the file from [Stripe's docs](https://docs.stripe.com/payments/payment-methods/pmd-registration). If the file isn't live when you register, Apple Pay validation fails — fix the file, then call this endpoint again to re-validate.
</Warning>

## Request Body

<ParamField body="domain_name" type="string" required>
  The bare domain that hosts your checkout page, e.g. `checkout.example.com`. Protocols, paths, and ports are stripped automatically (`https://checkout.example.com/pay` → `checkout.example.com`). Subdomains must be registered individually — registering `example.com` does **not** cover `checkout.example.com`.
</ParamField>

## Response

<ResponseField name="domain_name" type="string">
  The normalized domain that was registered.
</ResponseField>

<ResponseField name="environment" type="string">
  `live` or `sandbox`, derived from your API key.
</ResponseField>

<ResponseField name="results" type="array">
  One entry per Stripe account the domain was registered on.

  <Expandable title="Result fields">
    <ResponseField name="target" type="string">
      Which account this result is for: `platform_us`, `platform_uk`, `business_<id>` (your own connected account), or `merchant_<id>` (a sub-merchant's connected account).
    </ResponseField>

    <ResponseField name="stripe_account_id" type="string | null">
      The connected account ID, or `null` for platform accounts.
    </ResponseField>

    <ResponseField name="success" type="boolean">
      Whether registration succeeded on this account.
    </ResponseField>

    <ResponseField name="apple_pay_status" type="string | null">
      Stripe's Apple Pay validation status for the domain: `active` or `inactive`. `inactive` usually means the association file wasn't reachable — fix it and re-register.
    </ResponseField>

    <ResponseField name="google_pay_status" type="string | null">
      Stripe's Google Pay status for the domain (typically `active` immediately).
    </ResponseField>

    <ResponseField name="error" type="string">
      Present when `success` is `false`.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.khaime.com/api/v1/partner/payment-method-domains \
    -H "X-API-Key: pk_live_your_key" \
    -H "Content-Type: application/json" \
    -d '{
      "domain_name": "checkout.example.com"
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Success theme={null}
  {
    "success": true,
    "message": "Domain registered for wallet payments on all Stripe accounts.",
    "data": {
      "domain_name": "checkout.example.com",
      "environment": "live",
      "results": [
        {
          "target": "platform_us",
          "stripe_account_id": null,
          "success": true,
          "apple_pay_status": "active",
          "google_pay_status": "active"
        },
        {
          "target": "platform_uk",
          "stripe_account_id": null,
          "success": true,
          "apple_pay_status": "active",
          "google_pay_status": "active"
        },
        {
          "target": "merchant_2454",
          "stripe_account_id": "acct_1ABC...",
          "success": true,
          "apple_pay_status": "active",
          "google_pay_status": "active"
        }
      ]
    }
  }
  ```
</ResponseExample>

## Enabling wallets end-to-end

Registering the domain is one of three steps. To actually show Apple Pay / Google Pay on your checkout:

<Steps>
  <Step title="Host the association file, then register your domain">
    Serve the domain association file at the well-known path above, then call this endpoint. Confirm every result shows `apple_pay_status: "active"` (use the [status endpoint](/api-reference/payments/payment-method-domain-status) to re-check later).
  </Step>

  <Step title="Render the Payment Element (not a card-only element)">
    Wallets only appear in the unified **Payment Element**. Mount it with the `client_secret` and `publishable_key` from [Create Charge](/api-reference/payments/create-charge).

    **Critical for marketplace/direct charges:** when the charge response includes `stripe_account_id`, you must pass it when initializing Stripe.js — otherwise the wallet validation on the connected account is never picked up:

    ```javascript theme={null}
    const stripe = Stripe(publishable_key, {
      stripeAccount: stripe_account_id, // from the Create Charge response
    });
    const elements = stripe.elements({ clientSecret: client_secret });
    elements.create('payment').mount('#payment-element');
    ```
  </Step>

  <Step title="Serve checkout over HTTPS and test in a wallet-capable browser">
    Apple Pay renders only in Safari (macOS/iOS) with a card in Apple Wallet; Google Pay renders in Chrome with a saved card. Not seeing a wallet button in other browsers is expected behavior, not a configuration error.
  </Step>
</Steps>

<Note>
  Wallets appear on **one-time charges only**. Subscription charges are intentionally card-only because renewals require a reusable card payment method.
</Note>