curl -X POST https://api.khaime.com/api/v1/payment-method-domains \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"domain_name": "checkout.example.com"
}'
{
"success": true,
"message": "Domain registered for wallet payments on all merchant accounts.",
"data": {
"domain_name": "checkout.example.com",
"environment": "live",
"results": [
{
"target": "platform_us",
"merchant_account_id": null,
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
},
{
"target": "platform_uk",
"merchant_account_id": null,
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
},
{
"target": "merchant_2454",
"merchant_account_id": "acct_1ABC...",
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
}
]
}
}
Payments
Register Payment Method Domain
Register your checkout domain so Apple Pay and Google Pay appear in the Payment Element.
POST
/
payment-method-domains
curl -X POST https://api.khaime.com/api/v1/payment-method-domains \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"domain_name": "checkout.example.com"
}'
{
"success": true,
"message": "Domain registered for wallet payments on all merchant accounts.",
"data": {
"domain_name": "checkout.example.com",
"environment": "live",
"results": [
{
"target": "platform_us",
"merchant_account_id": null,
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
},
{
"target": "platform_uk",
"merchant_account_id": null,
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
},
{
"target": "merchant_2454",
"merchant_account_id": "acct_1ABC...",
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
}
]
}
}
Intro
Registers the domain that hosts your checkout page as a Stripe payment method domain. This is required for Apple Pay to appear in the embedded Payment Element rendered from a Create Chargeclient_secret. Google Pay does not require domain registration, but registering keeps its status visible alongside Apple Pay’s.
Context
This is a one-time (or re-run-on-change) setup step, not part of the per-charge flow. It only matters if your checkout uses the Stripe Payment Element returned by Create Charge’sclient_secret — Paystack, Flutterwave, and StartButton checkouts are unaffected. After registering, use Get Payment Method Domain Status to confirm validation succeeded or to diagnose why a wallet button isn’t rendering.
Hows
Registration runs on every merchant account that can render the Payment Element for you:- The Khaime US and UK platform accounts (platform-routed charges)
- Your business’s own 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)
Before calling this endpoint, host the Apple Pay domain association file at:
https://<your-domain>/.well-known/apple-developer-merchantid-domain-associationContact Khaime support to obtain this file. If the file isn’t live when you register, Apple Pay validation fails — fix the file, then call this endpoint again to re-validate.Request body
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.Response
string
The normalized domain that was registered.
string
live or sandbox, derived from your API key.array
One entry per merchant account the domain was registered on.
Show Result fields
Show Result fields
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).string | null
The connected account ID, or
null for platform accounts.boolean
Whether registration succeeded on this account.
string | null
Apple Pay validation status for the domain:
active or inactive. inactive usually means the association file wasn’t reachable — fix it and re-register.string | null
Google Pay status for the domain (typically
active immediately).string
Present when
success is false.curl -X POST https://api.khaime.com/api/v1/payment-method-domains \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{
"domain_name": "checkout.example.com"
}'
{
"success": true,
"message": "Domain registered for wallet payments on all merchant accounts.",
"data": {
"domain_name": "checkout.example.com",
"environment": "live",
"results": [
{
"target": "platform_us",
"merchant_account_id": null,
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
},
{
"target": "platform_uk",
"merchant_account_id": null,
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
},
{
"target": "merchant_2454",
"merchant_account_id": "acct_1ABC...",
"success": true,
"apple_pay_status": "active",
"google_pay_status": "active"
}
]
}
}
Enabling wallets end-to-end
Registering the domain is one of three steps. To actually show Apple Pay / Google Pay on your checkout:1
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 to re-check later).2
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.Critical for marketplace/direct charges: when the charge response includes merchant_account_id, you must pass it when initializing Khaime Payment SDK — otherwise the wallet validation on the connected account is never picked up:const khaime = Khaime(publishable_key, {
connectedAccount: merchant_account_id, // from the Create Charge response
});
const elements = khaime.elements({ clientSecret: client_secret });
elements.create('payment').mount('#payment-element');
3
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.
Wallets appear on one-time charges only. Subscription charges are intentionally card-only because renewals require a reusable card payment method.
Whys
Registration runs across the platform accounts, your connected account, and every active sub-merchant’s account in one call because a Payment Element can render on any of those accounts depending on how the charge routes — a domain registered only on the platform account would show wallets on platform-routed charges but silently fail to on direct or marketplace charges. Reporting per-account results (rather than a single pass/fail) means one connected account’s failure doesn’t block registration on the rest.Why nots
- This only affects Stripe checkouts — it has no effect on Paystack, Flutterwave, or StartButton redirect flows, which don’t use the Payment Element.
- It does not enable wallets by itself — you still need to render the unified Payment Element (not a card-only element) and, for connected-account charges, pass
stripeAccountwhen initializing Stripe.js. - It does not cover subdomains automatically —
checkout.example.comandpay.example.comeach need their own registration call. - Wallets never appear on subscription/recurring charges — only one-time charges support Apple Pay / Google Pay today.