# Payhip
> Expert guide and integration toolkit for Payhip e-commerce platform (help.payhip.com). Use when setting up or managing Payhip stores, products (digital downloads, courses, memberships, physical, coaching, bundles), custom domains, embed buttons/modals, direct checkout links, license keys API, webhooks, affiliate marketing, EU/UK VAT compliance, or building custom developer integrations with Payhip.
- Skill: `shaashiekumha/payhip` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add shaashiekumha/payhip`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shaashiekumha/payhip/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: shaashiekumha (https://skillmd.com/u/shaashiekumha)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/shaashiekumha/payhip
---
# Payhip Expert Skill
A complete reference and operational guide for selling digital goods, courses, memberships, physical products, and coaching on [Payhip](https://payhip.com) based on the official [Payhip Help Center](https://help.payhip.com/) and Developer APIs.
---
## Table of Contents
1. [Platform Overview & Core Architecture](#1-platform-overview--core-architecture)
2. [Product Setup & Monetization Models](#2-product-setup--monetization-models)
3. [Storefront Embeds & `payhip.js` SDK](#3-storefront-embeds--payhipjs-sdk)
4. [Direct Checkout Links & Metadata](#4-direct-checkout-links--metadata)
5. [Public API & Software License Keys](#5-public-api--software-license-keys)
6. [Webhooks & Real-Time Event Handling](#6-webhooks--real-time-event-handling)
7. [Payment Gateways & Direct Payouts](#7-payment-gateways--direct-payouts)
8. [EU/UK VAT & Global Sales Tax](#8-euuk-vat--global-sales-tax)
9. [Marketing, Affiliates & Growth Engines](#9-marketing-affiliates--growth-engines)
10. [Troubleshooting & Best Practices](#10-troubleshooting--best-practices)
---
## 1. Platform Overview & Core Architecture
Payhip is an e-commerce platform designed for creators, software developers, educators, and merchants. Key architectural highlights:
- **Instant Direct Payouts**: Unlike marketplaces that hold merchant balances for weeks, payments process directly into your connected Stripe, PayPal, Paystack, or Mercado Pago accounts.
- **Built-in Merchant of Record for EU/UK VAT**: Automatically calculates, collects, and remits digital EU and UK VAT to tax authorities without extra merchant paperwork.
- **Tiered Pricing Structure**:
- **Free Forever**: $0/month + 5% transaction fee (+ standard gateway processing fees).
- **Plus**: $29/month + 2% transaction fee.
- **Pro**: $99/month + 0% transaction fee.
- **Zero-Storage/Bandwidth Restrictions**: Generous file size allowances (up to 5GB per file, multiple files per product).
---
## 2. Product Setup & Monetization Models
Payhip supports 7 distinct product types:
### A. Digital Products & Downloads
- **File Distribution**: Upload e-books, software, audio, presets, templates, or archives up to 5GB.
- **PDF Stamping**: Protects digital books by automatically stamping buyer details (buyer email, order date) onto PDF pages to deter piracy.
- **Download Limits**: Restrict download attempts per customer (e.g., maximum 3 downloads) and set link expiry windows.
- **Variants**: Deliver different files based on options selected (e.g., EPUB vs. MOBI vs. PDF, Standard vs. Extended License).
### B. Courses
- **Curriculum Architecture**: Sections, lessons, video hosting, downloadable resources, assignments, and quizzes.
- **Video Player**: High-performance, anti-piracy video player with adaptive bitrate streaming.
- **Drip Content**: Release lessons on specific dates or X days after enrollment.
- **Prerequisites & Certificates**: Lock advanced lessons until prior quizzes/sections are completed; award branded completion certificates.
### C. Memberships & Subscriptions
- **Flexible Tiers**: Multiple membership levels with monthly, annual, or custom recurring intervals.
- **Content Gating**: Restrict posts, video streams, downloads, or Discord communities to active subscribers.
- **Trial Periods & Setup Fees**: Configure free trials (e.g., 7 or 14 days) or upfront initiation fees.
### D. Software & License Keys
- **Two Generation Engines**:
- *Autogenerated*: Payhip generates cryptographically unique keys for every order.
- *Pre-generated*: Upload up to 10,000 keys per batch (from your custom license server, Steam, etc.).
- **License Enforcement**: Verify activations and manage seat counts via Payhip v2 API.
### E. Physical Products
- **Inventory & SKU Management**: Track stock levels per variant (sizes, colors).
- **Shipping Rules**: Configure flat-rate, weight-based, or country-specific shipping zones.
### F. Coaching Services
- **Client Onboarding**: Intake questionnaires and client scheduling integrations (direct sync with Calendly or Zoom).
- **Milestone Tracking**: Manage 1-on-1 consultations, homework check-ins, and session files.
### G. Bundles & Collections
- Group multiple standalone products into a discounted bundle with single-click checkout.
---
## 3. Storefront Embeds & `payhip.js` SDK
Integrate Payhip checkout into any website (WordPress, Webflow, Squarespace, Wix, Shopify, or custom static sites) using `payhip.js`.
### Step 1: Include the Script
Add to the `` of your website:
```html
```
### Step 2: Global Configuration
Configure cart drawer behavior and positions:
```html
```
### Step 3: Embed Buttons & Triggers
#### Modal Checkout Button:
```html
Buy Now
```
#### Add to Cart Button:
```html
Add to Cart
```
#### Open Slide-Out Cart:
```html
```
#### Pay What You Want (PWYW) Input:
```html
```
### Supported Data Attributes for Buy Buttons
| Attribute | Type | Description |
|-----------|------|-------------|
| `data-product` | `string` | Unique product alphanumeric key (e.g. `BaFxk`). Can be comma-separated. |
| `data-theme` | `string` | Button theme: `"green"`, `"blue"`, `"grey"`, or `"none"` (for custom CSS). |
| `data-method` | `string` | `"overlay"` (default modal), `"fallback_window"` (popup), or `"inline"`. |
| `data-iframe-target` | `string` | CSS selector for container when `data-method="inline"`. |
| `data-success-callback` | `string` | Name of window function invoked on successful transaction. |
| `data-close-callback` | `string` | Name of window function invoked when checkout modal closes. |
| `data-success-url` | `string` | Redirect URL after successful order. |
| `data-metadata` | `string` | JSON string or encoded string passed directly to webhooks. |
| `data-subscription-plan`| `string` | Specific tier plan ID for memberships. |
| `data-target-variant` | `string` | Specific pre-selected variant key. |
---
## 4. Direct Checkout Links & Metadata
Skip product landing pages and send visitors straight to checkout or bundle checkout.
### Single Product Direct Checkout:
```
https://payhip.com/buy?link=BaFxk
```
*(If using a custom domain, use `https://store.yourdomain.com/buy?link=BaFxk`)*
### Multi-Product Cart Checkout:
```
https://payhip.com/buy?cart_links[]=BaFxk&cart_links[]=RGsF
```
### Checkout URL Metadata (Passthrough to Webhooks):
Attach custom tracking parameters (such as `user_id`, `referral_code`, `session_id`) that Payhip passes directly into webhook payloads:
```
https://payhip.com/buy?link=BaFxk&metadata[user_id]=usr_94821&metadata[campaign]=summer_sale
```
- **Max metadata pairs**: 20 key-value pairs.
- **Key limit**: 40 characters (forbidden characters: `[`, `]`, `<`, `>`).
- **Value limit**: 500 characters (forbidden characters: `<`, `>`).
---
## 5. Public API & Software License Keys
Payhip provides a REST API for programmatic coupon management and license key verification.
### API v2 Software License Keys
For software products, verify and manage activations securely without exposing merchant credentials.
#### 1. Verify a License Key:
```bash
curl -X GET "https://payhip.com/api/v2/license/verify?license_key=WTKP4-66NL5-HMKQW-GFSCZ" \
--header "product-secret-key: YOUR_PRODUCT_SECRET_KEY"
```
**Response (Success):**
```json
{
"data": {
"enabled": true,
"product_link": "BaFxk",
"license_key": "WTKP4-66NL5-HMKQW-GFSCZ",
"buyer_email": "customer@example.com",
"uses": 1,
"date": "2026-03-15T10:14:00+00:00"
}
}
```
#### 2. Increase License Usage Count (Activation):
```bash
curl -X PUT "https://payhip.com/api/v2/license/usage" \
--header "product-secret-key: YOUR_PRODUCT_SECRET_KEY" \
-d "license_key=WTKP4-66NL5-HMKQW-GFSCZ"
```
#### 3. Decrease License Usage Count (Deactivation):
```bash
curl -X PUT "https://payhip.com/api/v2/license/decrease" \
--header "product-secret-key: YOUR_PRODUCT_SECRET_KEY" \
-d "license_key=WTKP4-66NL5-HMKQW-GFSCZ"
```
#### 4. Disable / Revoke a Key:
```bash
curl -X PUT "https://payhip.com/api/v2/license/disable" \
--header "product-secret-key: YOUR_PRODUCT_SECRET_KEY" \
-d "license_key=WTKP4-66NL5-HMKQW-GFSCZ"
```
---
## 6. Webhooks & Real-Time Event Handling
Subscribe to real-time store events from **Account > Settings > Developer**.
### Event Types
1. `paid`: Fired whenever a customer completes a purchase or recurring charge.
2. `refunded`: Fired whenever a payment is fully or partially refunded.
3. `subscription.created`: Fired when a customer signs up for a recurring plan.
4. `subscription.deleted`: Fired when a subscription is cancelled or terminated.
### Security & Signature Verification
Every webhook request includes a `signature` property in the JSON body. Verify it by computing the SHA-256 hash of your Payhip API Key:
```
signature == hash("sha256", API_KEY)
```
> [!IMPORTANT]
> The hash is computed on the secret API key alone (`sha256(apiKey)`), not an HMAC over the payload body.
### Webhook Delivery Rules
- Your endpoint must return HTTP status code `200`.
- If non-200 is returned, Payhip retries once an hour for up to 3 hours.
- Amounts and prices are in **cents/pennies** (e.g., `$10.00` is represented as `1000`).
---
## 7. Payment Gateways & Direct Payouts
Connect one or more payment gateways under **Account > Settings > Payment Details**:
1. **Stripe**: Credit/debit cards, Apple Pay, Google Pay, iDEAL, Giropay, Bancontact, Sofort.
2. **PayPal**: PayPal wallet, Pay in 4, PayPal Credit.
3. **Paystack**: Leading African payment provider (Nigeria, Ghana, South Africa, Kenya).
4. **Mercado Pago**: Latin American payment gateway (Brazil, Mexico, Colombia, Argentina, Chile).
### Direct Deposit Benefit
Funds flow directly from customer to your merchant account immediately; Payhip deducts its platform fee (5% on Free, 2% on Plus, 0% on Pro) automatically at transaction time.
---
## 8. EU/UK VAT & Global Sales Tax
Under **Account > Settings > Taxes**:
### Automatic EU & UK Digital VAT
- Payhip acts as the legal **Seller/Merchant of Record** for digital goods in the EU and UK.
- It identifies customer geolocation via IP and payment billing address.
- Computes the appropriate local VAT rate (e.g., 20% UK, 19% Germany, 21% Spain).
- Collects and remits VAT directly to HMRC and EU MOSS/One Stop Shop (OSS).
### Pricing Strategies for Tax:
1. **Add VAT on top of price** (Recommended): Customer pays `$10.00 + 20% VAT = $12.00`. Your net revenue remains unchanged.
2. **Include VAT in price**: Customer pays `$10.00` total; the tax is deducted from your earnings (`$10 / 1.20 = $8.33 net`).
---
## 9. Marketing, Affiliates & Growth Engines
Payhip includes comprehensive growth tooling built right into the platform:
- **Coupons & Promotional Codes**: Percentage or fixed discounts, expiry dates, redemption limits, or restriction to specific products.
- **Affiliate System**:
- Run your own affiliate network with custom percentage commissions.
- Set custom cookie duration (e.g., 30, 60, or 90 days).
- Public or private affiliate registration pages.
- **Cross-Selling**: Offer related add-ons with a discount when a user adds a product to cart.
- **Upgrade Discounts / Upsells**: Offer a higher-tier product at checkout when viewing a lower-tier product.
- **Social Discounts**: Automatically apply a discount if the buyer tweets or shares the product URL.
- **Referral Programs**: Incentivize existing customers with cash or credit when their friends purchase.
- **Email Marketing Sync**: Seamless auto-sync of customer emails with Mailchimp, ConvertKit, ActiveCampaign, Drip, AWeber, or GetResponse (supports GDPR double opt-in).
---
## 10. Troubleshooting & Best Practices
1. **Custom Domain Issues**:
- Create a `CNAME` record pointing to `domains.payhip.com` (for subdomains like `store.example.com`).
- For root domains (`example.com`), create an `A` record pointing to Payhip's designated IP.
- SSL certificates generate automatically within 24 hours of DNS propagation.
2. **PayPal Checkout Blockers**:
- Ensure the PayPal account is upgraded to a **Business Account**.
- Verify that your PayPal email is confirmed and API permissions are granted.
3. **Webhook Failures**:
- Ensure your server returns a fast `200 OK` response before processing asynchronous tasks.
- Check firewall or Cloudflare rules that might block Payhip's POST requests.
4. **License Key Depletion Alert**:
- When selling pre-generated license keys, always enable **"Limit the number of products sold"** to match your uploaded inventory so buyers aren't issued blank keys.
---
## References & Companion Files
- Detailed API & Webhook Specifications: [api-webhooks.md](file:///C:/Users/Admin/.agents/skills/payhip/references/api-webhooks.md)
- Complete Embeds & JavaScript SDK Reference: [embeds-sdk.md](file:///C:/Users/Admin/.agents/skills/payhip/references/embeds-sdk.md)
- Tax & Compliance Rules: [taxes-compliance.md](file:///C:/Users/Admin/.agents/skills/payhip/references/taxes-compliance.md)
- Node.js Express Webhook Server: [webhook-server.js](file:///C:/Users/Admin/.agents/skills/payhip/examples/webhook-server.js)
- Python License Key Validator: [license-validator.py](file:///C:/Users/Admin/.agents/skills/payhip/examples/license-validator.py)