BYOS SETUP GUIDE

Set Up Bring Your Own Stripe

Connect your Stripe account, enable Apple Pay, map your products, and start processing payments — all in about 15 minutes.

Connect Your Stripe Apple Pay Setup

Prerequisites

Before you begin, make sure you have the following:

  • A ZeroSettle account (sign up free)
  • A Stripe account on the Standard plan (not Express)
  • At least one iOS app registered in ZeroSettle with products synced from App Store Connect
  • Your App Store Connect API key uploaded in ZeroSettle Settings
1

Connect Your Stripe Account

Link your existing Stripe Standard account to ZeroSettle via OAuth.

  1. Open the ZeroSettle Dashboard and go to Settings
  2. Under Stripe Integration, click Switch to Self-Managed (or connect for the first time)
  3. You'll be redirected to Stripe to authorize the connection
  4. After authorizing, you'll be returned to the dashboard with a green "Connected — Self-Managed" badge
Note: The OAuth connection only grants ZeroSettle access to your live Stripe environment. Sandbox mode automatically uses a mirrored copy of your live product data — no separate sandbox Stripe account is needed.
2

Enable Apple Pay

Register ZeroSettle's checkout domain so Apple Pay works in the web checkout sheet. Without this, the Apple Pay button will not appear and customers will only see card entry.

  1. Open Payment method domains in your Stripe Dashboard
  2. Click Add new domain
  3. Enter checkout.zerosettle.io and save
  4. Verify it appears in the registered domains list
Why is this needed? During OAuth, ZeroSettle automatically registers this domain on your connected account. But Apple Pay requires the domain to also be registered on your own Stripe Dashboard (the platform side). Both registrations are required for Apple Pay to work end-to-end.
3

Map Your Products

Link your App Store Connect products to Stripe products so the SDK knows which Stripe price to charge at checkout.

  1. Go to your app in the ZeroSettle Dashboard
  2. Open the Stripe Catalog tab
  3. ZeroSettle will auto-match products from your Stripe account to your App Store products based on name and metadata
  4. Review the auto-matched mappings and confirm they're correct
  5. For any unmatched products, manually select the corresponding Stripe product/price
  6. Set your web checkout price — this can differ from the App Store price
Tip: Products only appear in the checkout if they have an active Stripe mapping with a valid price. If a product shows "No Stripe mapping," it will fall back to StoreKit automatically.
4

Integrate the SDK

Add ZeroSettleKit to your iOS app. The SDK automatically routes purchases to web checkout (Stripe) or StoreKit based on product mapping and regional compliance.

  1. Add ZeroSettleKit via Swift Package Manager
  2. Configure with your publishable key from the Dashboard
  3. Fetch products and call purchase(product) — the SDK handles routing automatically
Full documentation: See the SDK docs for detailed integration guides, code samples, and API reference.

Sandbox & Live

ZeroSettle has two environments you can toggle between in the dashboard:

  • Sandbox — Uses test API keys (zs_pk_test_*). No real charges. Product and price data is automatically mirrored from your live Stripe catalog. BYOS sandbox payments process against the ZeroSettle platform account (since OAuth only connects to live).
  • Live — Uses production API keys (zs_pk_live_*). Real transactions process directly through your connected Stripe account. Requires email verification and ASC credentials.

Toggle between modes using the switch in the dashboard top bar. The SDK automatically uses the correct environment based on which key you configure.

Common Issues

Apple Pay button not showing?

The most common cause is that checkout.zerosettle.io is not registered as an Apple Pay domain in your Stripe Dashboard. Follow Step 2 above. Both the connected account registration (done automatically during OAuth) and the platform-side registration (done by you in your Stripe Dashboard) are required.

"No Stripe mapping found" for a product?

This means the product doesn't have an active mapping to a Stripe product/price. Go to the Stripe Catalog tab in your app dashboard, find the product, and either confirm an auto-match or manually map it to the correct Stripe product.

Price not updating in checkout?

After changing a default price on a Stripe product, it may take a moment to propagate. If you've just updated a price, wait 30 seconds and try again. Also confirm that the default price on the Stripe product is the one you intend to charge — additional prices are ignored unless explicitly mapped.

Sandbox purchases going through the ZeroSettle account?

This is expected. The OAuth connection is live-only, so sandbox BYOS falls back to the ZeroSettle platform Stripe account. Your live purchases will go through your own Stripe account as expected.

Ready to go?

Connect your Stripe account and start saving on iOS payments in minutes.

Connect Your Stripe Read the Docs