Connecting Shopify with Dev Dashboard + OAuth

WooshPayment does not use the old "paste an Admin API token and call it done" path for new merchants. The supported path is a personal dev app in your Shopify Dev Dashboard, installed through the OAuth authorization-code grant as a standalone app.

You give us Client ID + Client Secret, and we run OAuth against YOUR admin to get the access token. Do not treat setup as complete until the app is authorized, the ScriptTag is verified and the real live-cart test has passed.

Prerequisites

• Owner access or staff enabled to manage apps on your Shopify store
• Your store domain (e.g. my-store.myshopify.com)
• An active WooshPayment account

---

1. Open the Dev Dashboard inside Shopify

1. Go to https://my-store.myshopify.com/admin
2. Click the ⚙ Settings icon at the bottom-left (or , on the keyboard)
3. In the left column, click Apps
4. Top-right, click App development
5. In the card Develop and manage apps in your Dev Dashboard, click the dark button Build apps in Dev Dashboard

The Shopify Dev Dashboard opens (in a new tab or overlay).

2. Create a new app in the Dev Dashboard

1. Inside the Dev Dashboard, click the Create app button in the top-right
2. You land on the dedicated "Create an app" page with two side-by-side cards:
   • Get started with the Shopify CLI tool (for advanced devs with the local Shopify CLI)
   • Get started from the Dev Dashboard (simpler, no CLI required) → pick this one
3. In the App name field type WooshPayment (or any name you recognize)
4. Click Create

You land on the newly-created app page. From the app sidebar you can access Monitoring, Logs, Versions, Settings.

3. Create a version: configure URLs and disable embed

From the Versions section of the app, click Create version. A dedicated Create version page opens (not a tab — a full page):

1. URLs section → App URL: paste https://wooshpayment.com
2. Right below, find the Embed app in Shopify admin checkbox — it's checked by default. UNCHECK IT.
3. Leave the Preferences URL field empty (optional)

4. Configure access scopes

Scroll down to the Access section:

1. Scopes: in the current Dev Dashboard this is a single textarea with scopes separated by commas (not individual checkboxes). Paste exactly:

   read_orders,write_orders,read_checkouts,write_checkouts,read_products,read_customers,read_script_tags,write_script_tags

   These are the 8 scopes and what they do:

   Technical scope	What for
   read_orders	Read existing orders
   write_orders	Create the order after payment confirmed
   read_checkouts	Read in-progress checkout session
   write_checkouts	Update the checkout session
   read_products	Read catalog, prices, variants
   read_customers	Auto-fill address for known customers
   read_script_tags	Verify the script tag
   write_script_tags	Install the script that intercepts the Checkout button

2. Optional scopes: leave empty

3. Use legacy install flow: leave UNCHECKED

4. Redirect URL (at the bottom of the form, still inside the Access section): paste https://api.wooshpayment.com/auth/shopify/callback

5. Release the version

1. At the bottom-right of the Create version page, click the Release button
2. The Release this app version? modal opens
3. (Optional) Fill Version name and Version message — you can leave both empty, Shopify auto-generates a name
4. Click the Release button in the modal

Wait for the confirmation toast. The new version becomes Active.

6. Copy Client ID + Secret

From the app sidebar, click Settings:

1. Find the Credentials card
2. Client ID: copy the value (visible in full, ~32 chars) by clicking the 📋 icon on the right
3. Secret: it's masked. Click the 👁 icon to reveal it, then 📋 to copy it
   • If asked and you've already used it, click the Rotate button to generate a new one (the old one becomes invalid)

7. Paste into WooshPayment and complete install

1. Open https://wooshpayment.com/onboarding in another tab
2. Step Platform → Shopify, scroll to sub-step 3 (Paste Client ID + Secret)
3. Fill:
   • Shopify domain: my-store.myshopify.com
   • Client ID: the Client ID copied at step 6
   • Client Secret: the Secret copied at step 6
4. Click Connect store

You're redirected to Shopify's Install app screen. You'll see a banner "This app hasn't been reviewed" — that's normal for dev-apps not in the App Store.

5. Click Install in the Shopify panel
6. You return automatically to WooshPayment on the Brand step of the onboarding

Returning to the Brand step confirms OAuth succeeded. It is not traffic approval yet: complete active plan, Whop/COD and at least one paid pilot order from the live cart before launching ads.

What WooshPayment does at this point

• 🔐 Stores Client ID + Secret encrypted (AES-256-GCM) on our DB
• 🔄 Receives the OAuth token and stores it (always encrypted)
• 📜 Installs the script tag on your active Shopify theme and requires a real live-cart test before traffic
• 🌐 Provisions your subdomain your-slug.wooshpayment.com (Vercel DNS + SSL)
• ✨ Takes you to complete onboarding (brand, shipping, payments)

After setup, verify from the published Shopify cart that the Checkout click redirects to your branded checkout your-slug.wooshpayment.com/checkout/.... If the live theme does not load ScriptTag or the channel is headless/custom, do not send traffic: support or a dedicated app embed is required. Orders paid through WooshPayment are created as real Shopify orders with financial_status: paid.

Troubleshooting

"Invalid Client ID or Secret"

Check in order:

1. Did you click Release at step 5? Without a released version, OAuth won't start.
2. Did you copy the Client ID in full? No spaces before/after.
3. Is the Secret correct? If you closed the tab without copying it, go to Settings → Credentials → Rotate to generate a new one.

The "Embed app in Shopify admin" checkbox is CHECKED by default

Yes, it can be on by default. You must manually uncheck it before releasing the version, or OAuth fails (Shopify tries to embed WooshPayment in an iframe and we're not an embedded app).

Shopify says "Embed app must be enabled"

You left the Embed app in Shopify admin checkbox checked at step 3. Open Versions → Create version, uncheck it, release a new version, then click Connect store again in the WooshPayment dashboard.

I only see "App URL" and "Redirect URL" separately, there's no "Access" section

That's normal. In the Dev Dashboard, Redirect URL lives at the bottom of the Create version form, inside the Access section, after the Scopes textarea — it's not in a separate section.

The "Install" button on Shopify doesn't activate

Usually missing scopes in the Scopes textarea. Open Versions → Create version, check that all 8 scopes are in the textarea comma-separated, release again, repeat step 7.

I want to remove the app

1. Go to Shopify Dev Dashboard → your WooshPayment app
2. Settings sidebar → at the bottom, Delete app button

The token becomes invalid immediately, the script tag is removed from the theme, the WooshPayment integration goes into the "not connected" state.

Can I use the old method (shpat_ token) instead?

Not for new WooshPayment connections. If you have an old connection that already works, you can leave it active; for new stores or reconnects use Dev Dashboard + OAuth.

---

Need a hand? Email hello@wooshpayment.com or use the chat at the bottom-right of the dashboard.