API reference
WooshPayment REST endpoints for custom integrations. Today primarily internal server-to-server endpoints; public merchant API on the roadmap.
Public merchant API: Q3 roadmap. Today WooshPayment exposes REST endpoints used by our frontend and script tag, authenticated via session JWT (cookie-based or Authorization: Bearer <jwt>). There is no system yet for custom merchant API keys generatable from the dashboard. We'll announce it by email when it's ready.
Below you'll find the endpoints actually exposed today by our backend (https://api.wooshpayment.com). They are useful for debugging, headless integrations and custom scripts.
Base URL
https://api.wooshpayment.com
Authentication
JWTs are issued at login (POST /api/auth/login or POST /api/auth/register) and signed with JWT_SECRET. You must pass them as:
Authorization: Bearer <jwt>
JWTs contain { merchantId, shopDomain } as claims and last 30 days. Almost every endpoint marked requireAuth below requires this header.
Rate limit
- Login: 10 / 15 min per IP
- Register: 5 / 15 min per IP
- Checkout create: dedicated limiter
- Init payment: dedicated limiter
- Discount validation: dedicated limiter
Over limit → 429.
Main endpoints
Auth
| Method | Path | Notes |
|---|---|---|
| POST | /api/auth/register | Creates merchant (email, password, shopName) → JWT |
| POST | /api/auth/login | Email/password login → JWT, with timing-equalize |
| POST | /api/auth/password/reset-request | Sends password reset email |
| POST | /api/auth/password/reset-confirm | Sets new password with token |
| GET | /api/auth/shopify/install | Starts Shopify OAuth (with handoff JWT token) |
| GET | /api/auth/shopify/callback | OAuth callback: saves accessToken + installs ScriptTag |
Merchant
| Method | Path | Auth |
|---|---|---|
| GET | /api/merchant/me | Yes |
| GET | /api/merchant/config/:identifier | No (public for checkout) |
| PATCH | /api/merchant/config | Yes |
| PATCH | /api/merchant/account | Yes |
| PATCH | /api/merchant/slug | Yes |
| POST | /api/merchant/slug/regenerate | Yes |
| GET | /api/merchant/subdomain | Yes |
| PATCH | /api/merchant/shop | Yes |
| GET | /api/merchant/stats | Yes |
| GET | /api/merchant/stats/funnel | Yes |
| POST | /api/merchant/domain | Yes — adds checkout.yourstore.com |
| GET | /api/merchant/domain/status | Yes |
| POST | /api/merchant/domain/verify | Yes — triggers DNS verification |
| DELETE | /api/merchant/domain | Yes |
| GET | /api/merchant/whop | Yes |
| POST | /api/merchant/whop/connect | Yes — body { apiKey } |
| DELETE | /api/merchant/whop | Yes |
| GET | /api/merchant/woocommerce | Yes |
| POST | /api/merchant/woocommerce/connect | Yes |
| DELETE | /api/merchant/woocommerce | Yes |
| GET | /api/merchant/script-tag/status | Yes |
| POST | /api/merchant/script-tag/install | Yes — manual reinstall |
| POST | /api/merchant/preview | Yes — renders checkout preview |
Checkout (public, no auth)
| Method | Path | Notes |
|---|---|---|
| POST | /api/checkout/create | Creates session from Shopify/Woo cart |
| GET | /api/checkout/session/:token | Session status |
| GET | /api/checkout/session-bundle/:token | Full bundle (cart + branding + shipping + pixels) |
| GET | /api/checkout/:token/upsells | Upsell config |
| GET | /api/checkout/:token/pixels | Pixel config |
| GET | /api/checkout/:token/order-bumps | Order bump config |
| POST | /api/checkout/:token/refresh-status | Re-fetches Whop status |
| POST | /api/checkout/:token/init-payment | Initiates Whop payment |
| POST | /api/checkout/:token/pay | Finalizes payment |
| POST | /api/checkout/:token/complete-cod | Confirms COD |
| POST | /api/checkout/:token/validate-discount | Validates discount code |
Merchant checkout (auth)
| Method | Path | Notes |
|---|---|---|
| GET | /api/checkout/merchant/orders | Lists merchant orders |
| GET | /api/checkout/merchant/orders/:token | Single order detail |
| POST | /api/checkout/merchant/orders/:token/refund | Full refund |
| POST | /api/checkout/merchant/orders/:token/backfill-status | Force Whop status sync |
Platform billing
| Method | Path | Notes |
|---|---|---|
| GET | /api/platform-billing/plans | Public plan catalog |
| GET | /api/platform-billing/current | Merchant's current subscription |
| POST | /api/platform-billing/subscribe | Plan upgrade via Whop |
| POST | /api/platform-billing/cancel | Cancels subscription, downgrades to Starter |
Incoming webhooks (to our servers)
| Method | Path | Notes |
|---|---|---|
| POST | /webhooks/whop/payment-update | Whop signs with HMAC-SHA256 |
| POST | /webhooks/shopify/* | Shopify (uninstall, customers, etc.) |
See Webhook.
Response format
Successful responses are JSON with shape varying per endpoint (not always { ok, data }).
Standard errors:
{
"error": "Human-readable message",
"code": "INVALID_INPUT"
}Main codes: INVALID_INPUT, INVALID_WHOP_KEY, WHOP_TIMEOUT, EMAIL_EXISTS, DOMAIN_EXISTS, INVALID_CREDENTIALS, RATE_LIMITED, INVALID_SLUG, SLUG_COLLISION.
Body limits
Maximum body per request: 1 MB. Over → 413.
CORS
Allowlist:
https://wooshpayment.comhttps://*.wooshpayment.com(all subdomains)https://{custom_domain}if the merchant has a verified custom domain (auto-detect of the apex)https://{shop}.myshopify.comfor the script tag
Origins not in allowlist → 403.
SDK
- Node/TypeScript: roadmap (npm
@wooshpayment/sdk) - PHP / Python: no official client today
For now: call the API directly with fetch / axios / requests — it's standard REST.
Versioning
Stable endpoints. Backward-compatible changes (added fields) are not breaking. Breaking changes will carry a version prefix + 6 months of warning.