Gumroad

You are integrating Gumroad as the payment layer for a [Django / Next.js / FastAPI / etc.] app selling [digital products / memberships / licensed software]. Gumroad is a Merchant of Record — it collects payment, handles global VAT/sales tax, and absorbs chargeback liability — so your job is NOT to process cards, but to (1) let customers reach Gumroad checkout, (2) receive verified server-to-server notifications when a sale completes, and (3) grant access or deliver license keys on your side.

Requirements:

1. **Checkout flow.** Do NOT build a custom card form. Gumroad's checkout URL is the product's public Gumroad link (e.g. https://{creator}.gumroad.com/l/{product_id}). Either redirect users to it or embed the Gumroad overlay widget (GumroadOverlay JS). Card PCI liability stays with Gumroad — never attempt to collect raw card data yourself.

2. **Ping (webhook) receiver.** In Gumroad Settings → Advanced → Ping endpoint, register a single URL pointing to your server (HTTPS required). Gumroad sends POST form-encoded payloads on `sale`, `refund`, `dispute`, `cancellation`, `subscription_updated`, etc. Implement an endpoint (e.g. `/webhooks/gumroad/`) that:
   - Reads the raw request body.
   - Verifies the `X-Gumroad-Signature` header using HMAC-SHA256 with your webhook secret. Reject anything that doesn't match in constant time (`hmac.compare_digest`).
   - Parses `sale` events to persist `sale_id`, `email`, `product_id`, `price_cents`, `license_key`, `subscription_id` (if present), `purchaser_id`.
   - Acknowledges with HTTP 200 only AFTER the DB write commits. Otherwise Gumroad will retry and you'll double-grant access.
   - Idempotency: key off `sale_id`; ignore duplicates.

3. **License verification (for software / paid APIs).** On client-side activation, POST to `https://api.gumroad.com/v2/licenses/verify` with `product_id` and `license_key`. Check the response: `success=true`, `purchase.refunded=false`, and `purchase.chargebacked=false`. Cache the verification result for a bounded window (e.g. 24h) — don't hit the API on every request. Increment the `uses` counter only on genuine first activations.

4. **Subscription / membership state.** For memberships, react to `subscription_ended`, `subscription_updated`, and `cancellation` pings by updating the subscriber's access flag in your DB. Do not infer expiry from a timer — always confirm via Gumroad's event stream or by polling `GET /v2/subscribers/{id}` with a Bearer token.

5. **Security best practices for Gumroad specifically:**
   - Store the webhook HMAC secret and API access token in environment variables — never in client code.
   - Use OAuth 2.0 access tokens (created at https://app.gumroad.com/api) with the narrowest scope needed.
   - Trust `email` from Ping only for notification; for account linking use `sale_id` as the primary join key because emails can be spoofed on the thank-you-page side.
   - Log all webhook payloads with PII redacted for audit.

6. **Edge cases to handle (all are real and community-reported):**
   - Refunds: Gumroad returns its 10% platform fee but you will NOT be refunded the underlying Stripe/PayPal processing fee; your refund handler should downgrade access, not fail silently.
   - Chargebacks: treat as a full revoke + suspension trigger; Gumroad MoR status absorbs the chargeback, but you must still pull access to the digital good.
   - Account suspensions (Iffy): if your Gumroad account is suspended, all product links 404. Build a static backup page for customers explaining how to re-reach you, so you aren't trapped.
   - Self-test purchases: do NOT buy your own product from the same account — Gumroad's fraud rules will flag it. Use Gumroad's test mode / a second account.

7. **Local development.** Use a tunnel (ngrok, Cloudflare Tunnel) to receive Ping events. Gumroad offers a 'Send test ping to URL' button — exercise it before the first real sale.

Reference endpoints:
- REST API base: `https://api.gumroad.com/v2`
- Products: `GET /products`, `GET /products/{id}`
- Sales: `GET /sales` (paginated, supports `after` cursor)
- Subscribers: `GET /subscribers/{id}`
- License verify: `POST /licenses/verify`
- Auth: Bearer token in `Authorization` header, OR OAuth 2.0 authorization-code flow for multi-creator apps.

Deliver: a Ping webhook handler, a license-verify helper, and a thin client for the REST API v2 covering products/sales/subscribers. Include HMAC verification tests and an idempotency test. Do not build a custom checkout page.