WooshPayment Guide

WooshPayment replaces the standard Shopify checkout with a one-page checkout branded with your domain (e.g. checkout.yoursite.com). Apple Pay and Google Pay work natively, up to +18% mobile conversion in our pilot tests.

The 4 steps to go live

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 the live checkout.
2. Connect Shopify. Generate an Admin API token from your Shopify Admin and paste it into Dashboard → Integrations. Detailed guide in Article 2.
3. Customize the checkout. Colors, logo, copy — Dashboard → Checkout. See Article 3.
4. Install the script tag. From the Integrations page click "Install script tag". One click only, WooshPayment handles the rest.

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

1. Open the custom app panel in Shopify

1. Go to Shopify Admin
2. Open Settings → Apps and sales channels
3. Click Develop apps (if it's your first time you'll need to enable it)
4. Click Create an app, give it a name (e.g. "WooshPayment")

2. Configure the Admin API scopes

In the Configuration tab, Admin API integration section, enable these scopes:

• 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. Install the app and generate the token

1. API credentials tab → Install app
2. Confirm — Shopify generates an Admin API access token (starts with shpat_)
3. Copy it immediately! Shopify shows it only once. If you lose it, you'll have to uninstall and reinstall the app.

4. Paste into the WooshPayment dashboard

Open Dashboard → Integrations, Shopify section. Paste the token and your store domain (e.g. my-store.myshopify.com) and click Save and verify. The dashboard makes a test call: if it succeeds you see the green "Connected" badge.

Troubleshooting

• "Missing scopes": go back to Shopify Admin → Configuration, add the missing scope, click Save, then Install again. Generate a new token and re-paste it.
• "Invalid access token": you probably uninstalled and reinstalled the app. The old token is dead, generate a new one.
• "Store domain not found": use the .myshopify.com domain, not your store's custom domain.

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. Usually online in 10-30 minutes. 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 support@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)
• Shopify: cancels the order and marks it as "refunded"
• Inventory: products are automatically restocked (restock = true)
• 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 Shopify, 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 instant from our point of view
• Customer bank side: 5-10 business days to see the credit back on the card
• Confirmation email: within 5 minutes of the action

"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. For new merchants this is automatic (Sprint 4). For legacy merchants you might need manual setup: contact us and we'll register the domain in a few minutes, or consult the internal runbook work/docs/apple-pay-manual.md.

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 does).

"The customer clicks Check out on Shopify and nothing opens"

1. Go to Dashboard → Integrations, check that the Script tag on Shopify badge is green "Installed".
2. If not, click Install script tag. If it's installed but doesn't work, click Reinstall (removes any duplicates).
3. If the problem persists, check the browser Console (F12) on your store: JS errors there often indicate a theme blocking the script tag.

"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 Shopify"

1. Go to the order in the WooshPayment dashboard and check the webhook status
2. If you see "Failed" or "Pending", the issue is that the Shopify token may have expired. Generate a new one (Article 2) and re-enter it.
3. Also check that the write_orders scopes are active on the Shopify app

"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 support@wooshpayment.com with the order ID and we'll reply the same day.

"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"
  }'

pageHelp.articles.apiReference.createResponse

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 support@wooshpayment.com.