Payhip

You are integrating Payhip as the payment / storefront layer for a [Django / Next.js / FastAPI / etc.] app selling [digital downloads / online courses / memberships / licensed software]. Payhip is NOT a full Merchant of Record — it is MoR for digital EU VAT and UK VAT only. For US, Canadian, and Australian sales tax the seller remains liable. Payhip also does not hold funds centrally: money settles directly into your connected Stripe/PayPal/Mollie/Paystack/etc. account on that processor's own schedule. Your job is to (1) let customers reach Payhip's hosted checkout, (2) receive webhook notifications for paid / refunded / subscription events, and (3) grant or revoke access (including verifying software license keys) on your side.

Requirements:

1. **Checkout flow.** Do NOT build a custom card form. Use either the hosted product link (e.g. https://payhip.com/b/{short_id}) as a redirect target or embed Payhip's buy button / overlay on your site. PCI liability stays with the underlying processor (Stripe, PayPal, Mollie, etc.). Never attempt to collect raw card data yourself.

2. **Webhook receiver.** In Settings → Developer, register your webhook endpoint and subscribe to the 4 events you need: `paid`, `refunded`, `subscription.created`, `subscription.deleted`. Your handler (e.g. `/webhooks/payhip/`) must:
   - Parse the JSON body.
   - Compare the `signature` property inside the payload against `hashlib.sha256(API_KEY.encode()).hexdigest()` using `hmac.compare_digest` for constant-time comparison. IMPORTANT: Payhip's 'signature' is a static sha256 of the API key and does NOT include the payload body — treat it as a shared-secret gate, not a tamper-proof HMAC. For high-value actions (license activation, access grants) also re-verify out of band via `GET /api/v2/license/verify` before granting access.
   - Persist the transaction: `id` (transaction ID — your idempotency key), `email`, `currency`, `price` (in cents), `items[]`, `payment_type`, `date`. Prices are always in cents — 10 USD arrives as 1000.
   - Return HTTP 200 only AFTER the DB write commits. Non-200 responses trigger retries at 1-hour intervals for up to 3 hours, then the event is dropped permanently — do not rely on retries for correctness.
   - Idempotency: key on the `id` field; ignore duplicates.

3. **License verification (for software / paid APIs).** Use the v2 license system (the legacy one is deprecated). On activation, call `GET https://payhip.com/api/v2/license/verify?product_id={id}&license_key={key}` with the `product-secret-key` header set to your product's secret key (NOT your account API key). Check that the response indicates the key is enabled and unrevoked; optionally increment uses via the enable/disable endpoints. Cache successful verifications for a bounded window (e.g. 24h) — don't hit the API on every request.

4. **Subscription / membership state.** React to `subscription.created` by granting access and to `subscription.deleted` by revoking it. Payhip does NOT currently expose a subscription read endpoint in the public API (v2 covers only coupons and licenses) — you cannot poll for expiry. Persist the `date_subscription_deleted` field from the `subscription.deleted` payload as your authoritative end-of-access timestamp, and rely on the event stream rather than polling.

5. **Security best practices for Payhip specifically:**
   - Store the API key, product secret key, and webhook secret in environment variables — never in client code.
   - Because the webhook signature is a static digest of the API key, treat key leakage as 'all previously-sent webhooks are spoofable' — rotate immediately in the Developer settings if you suspect exposure.
   - Do NOT trust `email` from webhook alone for account linking — Payhip does not authenticate the buyer. Use the transaction `id` or a cryptographic claim code you mint yourself.
   - Log all webhook payloads with PII (email, name) redacted for audit.

6. **Edge cases to handle (all are real and community-reported):**
   - **Partial MoR.** Payhip collects EU/UK VAT for you but NOT US state, Canadian GST/HST, or Australian GST. If you have US nexus, integrate a separate tax-remittance service (TaxJar, Avalara) or migrate to a full MoR (Paddle, Lemon Squeezy, FastSpring, Polar).
   - **Refunds via processor.** A refund is issued in Stripe or PayPal first and then reflected in Payhip — your `refunded` webhook handler should downgrade access regardless of whether you initiated the refund from Payhip or the processor.
   - **Chargebacks.** Treat a chargeback as a full revoke plus flag-for-review. The underlying processor handles the dispute; Payhip does not shield you from chargeback liability (it is NOT a full MoR).
   - **Account closure for copyright.** Payhip enforces its acceptable-use policy aggressively on resold/derivative/AI-generated content. Keep a customer communication fallback (email list) outside Payhip so you can reach buyers if your store is taken down mid-flight.
   - **Affiliate payouts are manual.** If you run affiliates, Payhip tracks but does not pay — budget for bookkeeping effort.

7. **Local development.** Use a tunnel (ngrok, Cloudflare Tunnel) to receive webhooks. Payhip retries only 3 times at 1-hour intervals, so you cannot reproduce missed-delivery issues after the fact — instrument your endpoint and keep raw bodies for at least 7 days during integration.

Reference endpoints:
- REST API base: `https://payhip.com/api/v2`
- Coupons: `POST /coupon/create`, `GET /coupon/list`, `GET /coupon/retrieve`
- Licenses: `GET /license/verify`, `POST /license/enable`, `POST /license/disable`, `POST /license/usage/increase`, `POST /license/usage/decrease`
- Auth: `payhip-api-key` header for general endpoints, `product-secret-key` header for license operations.

Deliver: a webhook handler covering the 4 events, a license-verify helper, and a thin client for the v2 API (coupons + licenses). Include a signature-comparison test and an idempotency test keyed on transaction `id`. Do not build a custom checkout page.