WooshPayment Guide

WooshPayment replaces the standard Shopify or WooCommerce checkout with a one-page checkout branded with your domain (e.g. checkout.yoursite.com). Card payments run through Whop; wallets appear only when Whop, the checkout domain, browser and device are eligible.

The 4 steps before traffic

1. Create an account. Go to wooshpayment.com/signup, confirm your email. Demo mode is free: configure everything and only pay €99/month when you activate checkout interception.
2. Connect the store. Shopify: create a dev app in your Shopify Dev Dashboard, paste Client ID + Secret into Dashboard → Settings, and authorize the install. WooCommerce: install the official plugin, generate read/write REST API keys, and connect the store from Dashboard → Integrations. Shopify guide in Article 2, Woo guide in the docs.
3. Customize the checkout. Colors, logo, copy — Dashboard → Checkout. See Article 3.
4. Verify the checkout interceptor. Verify from an incognito store session that clicking Checkout opens WooshPayment: on Shopify check OAuth/ScriptTag from Dashboard → Settings or Script tag debug; on WooCommerce check the official plugin is active and the latest intercepted checkout appears in Dashboard → Integrations.

To activate marketing pixels (Meta CAPI, TikTok, GA4) read Article 4. For a custom domain like checkout.yoursite.com, see Article 5.

1. Create a dev app in the Shopify Dev Dashboard

1. Go to Shopify Admin → Settings → Apps
2. Open Develop apps and click Build apps in Dev Dashboard
3. Click Create app, choose Start from Dev Dashboard and name it WooshPayment
4. Open Versions → Create version

2. Configure URLs and scopes

In URLs set App URL to https://wooshpayment.com. In Access, paste these scopes into the Scopes textarea:

• read_orders — read existing orders
• write_orders — create the order on Shopify after payment
• read_checkouts and write_checkouts — manage carts
• read_products — retrieve cart products
• read_customers — link the order to an existing customer if already registered
• write_script_tags and read_script_tags — install the script that intercepts the checkout

3. Copy Client ID + Client Secret

1. Go to the dev app Settings tab
2. Copy the Client ID
3. Reveal and copy the Client Secret. If you lost it, use Rotate secret.

4. Paste into WooshPayment and authorize

Open Dashboard → Settings, Shopify section. Paste domain, Client ID and Client Secret, then click Open Shopify authorization. Shopify shows the Install screen: confirm and you return to WooshPayment with the ScriptTag installed.

Troubleshooting

• HMAC / wrong secret: rotate the Client Secret in the dev app and paste the new one into WooshPayment.
• Wrong Redirect URL: it must be exactly https://api.wooshpayment.com/auth/shopify/callback.
• App not released: create and release a version before clicking Connect store.

All customization lives in Dashboard → Checkout. Changes are immediate: you save and the next customer already sees your choices.

Brand color

Use a hexadecimal color (e.g. #3b5bdb). It will be applied to:

• "Buy now" button
• Links and graphic accents
• Checkout header
• Spinner and loading states

Logo

• Format: PNG or SVG (preferred)
• Background: transparent — the checkout is on a white background
• Recommended size: at least 240px wide, max 1MB
• Height: it will be automatically resized to about 36px in the mobile header, 44px desktop

Customizable copy

You can override:

• Header — appears above the cart summary (e.g. "Free shipping over €50" or "Easy returns within 30 days")
• Footer — under the payment methods (e.g. info on free shipping or 30-day warranty)
• Trust badges — extra line of text next to "Secure payment"

Live preview

The right side panel in the dashboard shows the checkout in real time. Switch between Desktop and Mobile with the toggle at the top. Always test Mobile mode: over 70% of orders come from phones.

UX tips

• Use a transparent logo: colored backgrounds clash with the white checkout
• The brand color should contrast well with white (no yellow, no pastel light blue)
• Custom copy should be short — 1 line on mobile, max 2 on desktop
• Don't write promotional copy in the header unless it's true: it kills trust

All pixels are configured in Dashboard → Integrations, Pixel & Analytics section. Private keys are encrypted at rest and used only server-side: they are never sent to the customer's browser.

Meta (Facebook) Pixel + CAPI

What it's for: tracking InitiateCheckout and Purchase in your Business Manager for Ads.

• Pixel ID (public): 15-16 digits, you find it in Events Manager → Data sources → your pixel → ID
• CAPI Access Token (advanced): Events Manager → Settings → Conversions API → Generate access token. Keep it secret, it's a key.

TikTok Pixel + Events API

What it's for: optimizing TikTok Ads campaigns based on real purchases.

• Pixel ID (public): TikTok Events Manager → Tools → Pixel → Pixel Code → 19-20 characters like CXXXXXXXXXXXXXXXXXX
• Events API Access Token (advanced): on the same page, "Events API" tab

Google Analytics 4

What it's for: the bread & butter of analytics. begin_checkout and purchase events.

• Measurement ID (public): GA4 → Admin → Data Streams → Web → your stream → ID (format G-XXXXXXXXXX)
• API Secret (optional, server-side via Measurement Protocol): same page, "Measurement Protocol API secrets" section

Why it's worth it

Having the checkout on checkout.yoursite.com instead of your-slug.wooshpayment.com:

• Increases customer trust (they stay on "your" site)
• Conversions +5-15% on average (internal WooshPayment data)
• Improves first-party cookie attribution (fewer issues with iOS 14+ and Safari ITP)

Setup in 4 steps

1. Go to Dashboard → Settings → Custom domain and enter the subdomain you want to use (e.g. checkout.yoursite.com).
2. Open your registrar's DNS panel (GoDaddy, Cloudflare, Aruba, OVH...) and add a CNAME record:

   Type:   CNAME
   Host:   checkout
   Points to: cname.vercel-dns.com
   TTL:    3600 (or auto)

3. Go back to the dashboard and click Verify. If you see "DNS detected", you're almost ready.
4. The SSL certificate (Let's Encrypt) is issued automatically within a few minutes. When the status becomes "Active", the domain is live.

Troubleshooting

• Slow DNS propagation: normal, can take up to 24h. Do not send traffic until the domain is verified and the pilot order passes. Check with dig checkout.yoursite.com CNAME from terminal.
• TTL too high: if you had an old record with a 24h TTL, you'll have to wait. Next time use TTL 3600 or auto.
• "Domain already in use": someone else has already claimed it on Vercel. Write to us at hello@wooshpayment.com.
• SSL doesn't activate after 1h: probably a CAA record error on the apex domain blocking Let's Encrypt. Add 0 issue "letsencrypt.org".

How to refund

1. Go to Dashboard → Orders
2. Click on the order you want to refund
3. In the top right click Refund
4. Confirm in the modal. The button is disabled while the operation is in progress.

What happens behind the scenes

• Whop: issues the refund to the customer's card (full refund)
• Store: cancels the order on Shopify or WooCommerce when the integration is connected
• Inventory: stock alignment follows the order cancellation on the connected platform
• Customer email: the customer receives an automatic refund confirmation

Partial refund

Currently WooshPayment only supports full refunds. For a partial refund (e.g. only 1 product out of 3) proceed as follows:

1. Refund the entire order from WooshPayment
2. Open your store, recreate a manual order for the products the customer wants to keep
3. Send the customer the link to the new order if they want to repay

Timeline

• WooshPayment/Whop side: the refund is recorded after Whop confirms it
• Customer bank side: 5-10 business days to see the credit back on the card
• Confirmation email: accepted by the mail provider after the refund event

"Apple Pay is not visible on the checkout"

Apple Pay requires the domain of your checkout to be registered on Whop as a payment domain. The automatic attempt is best-effort: before sending traffic, verify in Whop dashboard → Settings → Checkout → Apple Pay for embedded checkout that your-slug.wooshpayment.com or the custom domain is present. If it is missing, add it manually using the Apple Pay guide.

Also check: the customer is using Safari on iOS/macOS or Chrome on macOS with Apple Pay configured. Apple Pay does not appear on Chrome Windows or Android; Google Pay may appear only when Whop, browser, device and domain support it.

"The customer clicks Check out on the store and nothing opens"

1. Shopify: open Dashboard → Settings and verify OAuth is complete; if redirect still fails, use Script tag debug. WooCommerce: open Dashboard → Integrations and verify the official plugin is active with a recent intercepted checkout.
2. Shopify: if the ScriptTag is not installed, complete authorization again or use the Script tag debug guide. WooCommerce: update the plugin, save the REST API keys again, and run a cart test.
3. If the problem persists, check the browser Console (F12) on your store: JS errors or cache/theme behavior can block the interceptor.

"The order confirmation email doesn't reach the customer"

• Ask the customer to check the spam/promotions folder
• Check that the customer's email is correct in Orders
• If multiple customers report the issue, it could be a DKIM/DMARC issue with our Resend provider. Write to us immediately, it's a platform issue and we'll fix it.

"The order doesn't sync to the store"

1. Go to the order in the WooshPayment dashboard and check webhook status, Store order, and latest sync attempt.
2. Shopify: check OAuth/ScriptTag and write_orders scopes from Dashboard → Settings. WooCommerce: check the official plugin, read/write REST API keys, and store URL in Dashboard → Integrations.
3. If Whop is amber or the webhook secret is missing, complete Integrations: without webhook signature verification, orders are not created in real time.

"Marketing pixels don't see events"

• Check that the Pixel ID is correct (public, not the pixel name)
• Use the provider's Test Event Manager (Meta, TikTok, etc.) to see if the event arrives
• Place a test order from incognito (adblock extensions skew the client-side test)
• For Meta CAPI and TikTok CAPI, double-check that the access token hasn't expired

"The amount charged to the customer is wrong"

This bug was fixed in Sprint 5: the price shown to the customer now always matches what's charged. If you still see discrepancies, it's urgent — write to us immediately at hello@wooshpayment.com with the order ID and we'll prioritize it.

"The order status is 'pending' for too long"

• Over 24h is anomalous. The payment went through but the Whop webhook missed it.
• Go to the order and click Refresh status to force a manual refresh via API.
• If still pending, write to us with the order ID.

Base URL: https://api.wooshpayment.com

POST /api/checkout/create

Creates a new checkout session. Doesn't require auth — protected by rate limit.

curl -s -X POST https://api.wooshpayment.com/api/checkout/create \
  -H "Content-Type: application/json" \
  -d '{
    "shop": "woopay-test-store.myshopify.com",
    "cartToken": "abc123",
    "items": [
      { "id": 1, "title": "T-shirt", "variant_id": 1, "quantity": 1, "price": 1000 }
    ],
    "totalPrice": 1000,
    "currency": "USD"
  }'

Responds with the token and url fields. The url is the link to the branded checkout where the customer should be redirected.

GET /api/checkout/session/:token

Retrieves the state of a session (used by the checkout frontend for polling).

curl -s https://api.wooshpayment.com/api/checkout/session/ch_xxx

POST /api/checkout/:token/refresh-status

Forces a status refresh of a session directly from Whop. Use it if you suspect a webhook was lost.

curl -s -X POST https://api.wooshpayment.com/api/checkout/ch_xxx/refresh-status

Merchant endpoints (authenticated)

All /api/merchant/* routes require a JWT in the header. You get the token from the dashboard login:

curl -s https://api.wooshpayment.com/api/merchant/me \
  -H "Authorization: Bearer <jwt>"

Rate limits

• Public endpoints: 60 requests/minute/IP
• Merchant endpoints: 300 requests/minute/merchant
• Inbound webhooks: no limit (validated with HMAC)

When you exceed the limit you receive 429 Too Many Requests.

Outbound webhooks

For the full list of endpoints, see the source in apps/api/src/routes/ (open source coming soon) or write to us at hello@wooshpayment.com.