Register checkout domains

Paddle only opens checkout on domains that are registered and approved. Before a seller can take live payments, register the domain their checkout is served from, verify Apple Pay for it, and set it as the seller's default payment link.

We recommend using your platform agent to register checkout domains.

Overview

Register a checkout domain in four steps:

1. Upload the Apple Pay domain-association file
   Host Paddle's verification file so Apple Pay can be verified.
2. Register the checkout domain
   Register the domain in live and wait for Paddle to approve it.
3. Check if a domain is verified
   Poll to see if a domain is approved, and resubmit if rejected.
4. Set the default payment link
   Point the seller's default checkout URL at the registered domain.

Upload the Apple Pay domain-association file

Layer

Your agent

Environment

Live

Apple requires domains to be verified to open Apple Pay. If this step isn't completed, sellers can still present customers with Apple Pay: Paddle opens a modal that then opens Apple Pay.

We recommend doing this step first, since Paddle automatically attempts to verify a domain for Apple Pay at the same time as Paddle domain verification. Both can be completed at the same time, saving a step.

To verify a domain for Apple Pay, Apple checks that a verification file exists on the domain.

Use your agent to host Paddle's Apple Pay domain-association file at:

.well-known/apple-developer-merchantid-domain-association

The file must be served directly over HTTPS, return a 200, and not redirect.

Register the checkout domain

Layer

Your agent

Authentication

Partner API key

Environment

Live

For security, domains must be registered and approved before you can open a live checkout on them. You can register multiple domains, so you can let sellers publish their apps to custom domains as well as your platform.

Send a request to the POST /checkout-domains endpoint with the domain the seller's checkout is served from. You only need to do this on live.

If successful, Paddle responds with a checkout domain entity. The domain starts in pending_review while Paddle reviews it asynchronously before moving to approved.

{
  "domain": "checkout.aeroedit.com"
}

{
  "data": {
    "id": "chedom_01j8z3k9m2n4p5q6r7s8t9v0w1",
    "domain": "checkout.aeroedit.com",
    "status": "pending_review",
    "payment_method_verification": {
      "apple_pay": {
        "status": "unverified"
      }
    },
    "created_at": "2026-06-30T10:00:00.000Z",
    "updated_at": "2026-06-30T10:00:00.000Z"
  },
  "meta": {
    "request_id": "10c8f1a2-3b4c-4d5e-9f70-8a9b0c1d2e3f"
  }
}

Check if a domain is verified and resubmit if rejected

Layer

Your agent

Authentication

Partner API key

Environment

Live

Domain review is automated and typically takes a few minutes. Poll the GET /checkout-domains/{checkout_domain_id} endpoint until status is approved.

{
  "data": {
    "id": "chedom_01j8z3k9m2n4p5q6r7s8t9v0w1",
    "domain": "checkout.aeroedit.com",
    "status": "approved",
    "payment_method_verification": {
      "apple_pay": {
        "status": "verified"
      }
    },
    "created_at": "2026-06-30T10:00:00.000Z",
    "updated_at": "2026-06-30T10:14:22.000Z"
  },
  "meta": {
    "request_id": "21d9a2b3-4c5d-4e6f-8a71-9b0c1d2e3f40"
  }
}

Fix and resubmit

If status is action_required, the domain didn't pass verification, but it can be fixed and retried.

To fix, check that:

• Pages are publicly accessible and not behind a login.
• Pricing is visible.
• Terms, privacy notice, and refund policy exist.
• Terms include a mention of Paddle as the merchant of record.

Use your platform agent to fix these, then resubmit with the POST /checkout-domains/{checkout_domain_id}/resubmit endpoint. The endpoint takes no request body — resubmitting returns the domain to pending_review and restarts verification. You only need to do this on live.

{
  "data": {
    "id": "chedom_01j8z3k9m2n4p5q6r7s8t9v0w1",
    "domain": "checkout.aeroedit.com",
    "status": "pending_review",
    "payment_method_verification": {
      "apple_pay": {
        "status": "unverified"
      }
    },
    "created_at": "2026-06-30T10:00:00.000Z",
    "updated_at": "2026-06-30T10:20:00.000Z"
  },
  "meta": {
    "request_id": "f1e8c2a7-4b93-4d51-9a6e-3c7d0b85f24a"
  }
}

Reverify for Apple Pay

Once the domain is approved and the file is hosted, start Apple Pay verification by sending a request to the POST /checkout-domains/{checkout_domain_id}/verify-payment-method endpoint. You only need to do this on live.

If successful, Paddle returns a 200 with the checkout domain entity. If payment_method_verification.apple_pay.status is verified, Apple Pay can be served directly from the seller's domain without a modal.

{
  "payment_method": "apple_pay"
}

{
  "data": {
    "id": "chedom_01j8z3k9m2n4p5q6r7s8t9v0w1",
    "domain": "checkout.aeroedit.com",
    "status": "approved",
    "payment_method_verification": {
      "apple_pay": {
        "status": "verified"
      }
    },
    "created_at": "2026-06-30T10:00:00.000Z",
    "updated_at": "2026-06-30T10:20:05.000Z"
  },
  "meta": {
    "request_id": "32eab3c4-5d6e-4f70-8b82-ac1d2e3f4051"
  }
}

Set the default payment link

Layer

Your agent

Authentication

Partner API key

Environment

Live

A default payment link is required for Paddle to open a checkout. It must be set on a registered checkout domain, so set it once the domain is approved.

You set the default payment link for sandbox during onboarding. Now set it for live by sending a request to the PATCH /settings/account endpoint with a default_checkout_url on the approved domain.

{
  "default_checkout_url": "https://example.com/checkout"
}

{
  "data": {
    "default_checkout_url": "https://example.com/checkout",
    "default_tax_mode": "location",
    "primary_checkout_color": "#f0f0f0",
    "saved_payment_methods_enabled": true
  },
  "meta": {
    "request_id": "8295b301-8306-436d-813a-55f6ed03ccf8"
  }
}