API reference
Endpoint REST WooshPayment per integrazioni custom. Oggi prevalentemente endpoint server-to-server interni; API pubblica per merchant in roadmap.
API pubblica per merchant: roadmap Q3. Oggi WooshPayment espone endpoint REST usati dal nostro frontend e dallo script tag, autenticati via JWT di sessione (cookie-based o Authorization: Bearer <jwt>). Non esiste ancora un sistema di API key custom per merchant generabili dalla dashboard. Quando sarà pronto, lo annunceremo via email.
Sotto trovi gli endpoint effettivamente esposti oggi dal nostro backend (https://api.wooshpayment.com). Sono utili per debugging, integrazioni headless e script custom.
Base URL
https://api.wooshpayment.com
Autenticazione
I JWT vengono emessi al login (POST /api/auth/login o POST /api/auth/register) e firmati con JWT_SECRET. Devi passarli come:
Authorization: Bearer <jwt>
I JWT contengono { merchantId, shopDomain } come claim e durano 30 giorni. Quasi tutti gli endpoint marcati requireAuth qui sotto richiedono questo header.
Rate limit
- Login: 10 / 15 min per IP
- Register: 5 / 15 min per IP
- Checkout create: limiter dedicato
- Init payment: limiter dedicato
- Discount validation: limiter dedicato
Oltre limite → 429.
Endpoint principali
Auth
| Metodo | Path | Note |
|---|---|---|
| POST | /api/auth/register | Crea merchant (email, password, shopName) → JWT |
| POST | /api/auth/login | Login email/password → JWT, con timing-equalize |
| POST | /api/auth/password/reset-request | Manda email reset password |
| POST | /api/auth/password/reset-confirm | Imposta nuova password con token |
| GET | /api/auth/shopify/install | Avvia OAuth Shopify (con handoff token JWT) |
| GET | /api/auth/shopify/callback | Callback OAuth: salva accessToken + installa ScriptTag |
Merchant
| Metodo | Path | Auth |
|---|---|---|
| GET | /api/merchant/me | Sì |
| GET | /api/merchant/config/:identifier | No (public per checkout) |
| PATCH | /api/merchant/config | Sì |
| PATCH | /api/merchant/account | Sì |
| PATCH | /api/merchant/slug | Sì |
| POST | /api/merchant/slug/regenerate | Sì |
| GET | /api/merchant/subdomain | Sì |
| PATCH | /api/merchant/shop | Sì |
| GET | /api/merchant/stats | Sì |
| GET | /api/merchant/stats/funnel | Sì |
| POST | /api/merchant/domain | Sì — aggiunge checkout.tuostore.com |
| GET | /api/merchant/domain/status | Sì |
| POST | /api/merchant/domain/verify | Sì — innesca verifica DNS |
| DELETE | /api/merchant/domain | Sì |
| GET | /api/merchant/whop | Sì |
| POST | /api/merchant/whop/connect | Sì — body { apiKey } |
| DELETE | /api/merchant/whop | Sì |
| GET | /api/merchant/woocommerce | Sì |
| POST | /api/merchant/woocommerce/connect | Sì |
| DELETE | /api/merchant/woocommerce | Sì |
| GET | /api/merchant/script-tag/status | Sì |
| POST | /api/merchant/script-tag/install | Sì — reinstall manuale |
| POST | /api/merchant/preview | Sì — render preview checkout |
Checkout (public, no auth)
| Metodo | Path | Note |
|---|---|---|
| POST | /api/checkout/create | Crea session da carrello Shopify/Woo |
| GET | /api/checkout/session/:token | Stato sessione |
| GET | /api/checkout/session-bundle/:token | Bundle completo (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-fetch stato Whop |
| POST | /api/checkout/:token/init-payment | Init pagamento Whop |
| POST | /api/checkout/:token/pay | Finalizza pagamento |
| POST | /api/checkout/:token/complete-cod | Conferma COD |
| POST | /api/checkout/:token/validate-discount | Valida codice sconto |
Checkout merchant (auth)
| Metodo | Path | Note |
|---|---|---|
| GET | /api/checkout/merchant/orders | Lista ordini del merchant |
| GET | /api/checkout/merchant/orders/:token | Detail singolo |
| POST | /api/checkout/merchant/orders/:token/refund | Refund totale |
| POST | /api/checkout/merchant/orders/:token/backfill-status | Forza sync stato Whop |
Platform billing
| Metodo | Path | Note |
|---|---|---|
| GET | /api/platform-billing/plans | Catalogo piani public |
| GET | /api/platform-billing/current | Sub corrente del merchant |
| POST | /api/platform-billing/subscribe | Upgrade piano via Whop |
| POST | /api/platform-billing/cancel | Cancella sub, downgrade a Starter |
Webhook in entrata (sui nostri server)
| Metodo | Path | Note |
|---|---|---|
| POST | /webhooks/whop/payment-update | Whop firma HMAC-SHA256 |
| POST | /webhooks/shopify/* | Shopify (uninstall, customers, ecc.) |
Vedi Webhook.
Formato risposta
Le risposte di successo sono JSON con shape variabile per endpoint (non sempre { ok, data }).
Errori standard:
{
"error": "Messaggio leggibile",
"code": "INVALID_INPUT"
}Codici principali: INVALID_INPUT, INVALID_WHOP_KEY, WHOP_TIMEOUT, EMAIL_EXISTS, DOMAIN_EXISTS, INVALID_CREDENTIALS, RATE_LIMITED, INVALID_SLUG, SLUG_COLLISION.
Body limits
Body massimo per request: 1 MB. Oltre → 413.
CORS
Allowlist:
https://wooshpayment.comhttps://*.wooshpayment.com(tutti i subdomain)https://{custom_domain}se il merchant ha un dominio custom verificato (auto-detect dell'apex)https://{shop}.myshopify.comper script tag
Origini non in allowlist → 403.
SDK
- Node/TypeScript: roadmap (npm
@wooshpayment/sdk) - PHP / Python: oggi nessun client ufficiale
Per ora: chiama l'API direttamente con fetch / axios / requests — è REST standard.
Versioning
Endpoint stabili. Modifiche backward-compatible (campi aggiunti) non sono breaking. Breaking change avrà prefix versione + 6 mesi di warning.