JVZoo Integration Specialist

Expert guidance for building production-ready JVZoo integrations that handle purchases, license management, and account creation.

Overview

JVZoo integration involves three core components:

•IPN (Instant Payment Notification) - Real-time webhook from JVZoo when purchases occur
•License Management - Generate, validate, and track software licenses
•Account Creation - Automatically create user accounts from purchase data

IPN Setup & Security

IPN Endpoint Requirements

Your IPN endpoint must:

•Accept POST requests from JVZoo servers
•Respond within 10 seconds with HTTP 200
•Validate authenticity using secret key
•Handle idempotent processing (duplicates possible)
•Log all requests for debugging

IPN Verification

Always verify IPN authenticity using SHA-1 hash:

code

Verification Hash = SHA1(secretKey + "|" + transactionId + "|" + amount + "|" + productId)

Compare this hash with the cverify parameter sent by JVZoo. Never process unverified IPNs.

Essential IPN Parameters

Transaction Info:

•ctransaction - Transaction ID (use as idempotency key)
•ctransaction_type - SALE, RFND (refund), CGBK (chargeback), INSTAL (recurring), CANCEL-REBILL
•ctransreceipt - JVZoo receipt number
•cproditem - Product ID (your product identifier)
•cprodtype - STANDARD, RECURRING, etc.

Customer Info:

•ccustemail - Customer email (primary identifier)
•ccustname - Customer full name
•ccustcc - Customer country code
•ccuststate - Customer state/region

Financial Info:

•ctransamount - Sale amount
•ctransaffiliate - Affiliate commission
•ctransvendor - Your earnings

Verification:

•cverify - SHA-1 hash for verification

Account Creation Workflow

Step 1: Verify IPN

javascript

function verifyIPN(ipnData, secretKey) {
  const { ctransaction, ctransamount, cproditem, cverify } = ipnData;
  const hash = crypto
    .createHash('sha1')
    .update(`${secretKey}|${ctransaction}|${ctransamount}|${cproditem}`)
    .digest('hex')
    .toUpperCase();
  
  return hash === cverify.toUpperCase();
}

Step 2: Check for Duplicate Processing

javascript

async function isDuplicateTransaction(transactionId) {
  // Query database for existing transaction
  const existing = await db.transactions.findOne({ 
    jvzoo_transaction_id: transactionId 
  });
  return !!existing;
}

Step 3: Create or Update User Account

javascript

async function processNewSale(ipnData) {
  const { ccustemail, ccustname, cproditem, ctransaction } = ipnData;
  
  // Find or create user
  let user = await db.users.findOne({ email: ccustemail });
  
  if (!user) {
    user = await db.users.create({
      email: ccustemail,
      name: ccustname,
      created_via: 'jvzoo',
      jvzoo_transaction: ctransaction
    });
  }
  
  return user;
}

Step 4: Generate License Key

javascript

function generateLicenseKey(userId, productId, transactionId) {
  const timestamp = Date.now();
  const data = `${userId}:${productId}:${transactionId}:${timestamp}`;
  const hash = crypto
    .createHash('sha256')
    .update(data + process.env.LICENSE_SECRET)
    .digest('hex');
  
  // Format: XXXX-XXXX-XXXX-XXXX
  return hash.substring(0, 16).toUpperCase().match(/.{1,4}/g).join('-');
}

Step 5: Store License & Send Access

javascript

async function createLicense(userId, productId, ipnData) {
  const licenseKey = generateLicenseKey(
    userId, 
    productId, 
    ipnData.ctransaction
  );
  
  const license = await db.licenses.create({
    user_id: userId,
    product_id: productId,
    license_key: licenseKey,
    jvzoo_transaction: ipnData.ctransaction,
    jvzoo_receipt: ipnData.ctransreceipt,
    status: 'active',
    purchase_date: new Date(),
    transaction_type: ipnData.ctransaction_type
  });
  
  // Send email with license key and login details
  await sendWelcomeEmail(userId, licenseKey);
  
  return license;
}

Transaction Type Handling

SALE (New Purchase)

javascript

case 'SALE':
  await processNewSale(ipnData);
  await createLicense(user.id, ipnData.cproditem, ipnData);
  break;

RFND (Refund)

javascript

case 'RFND':
  await db.licenses.update(
    { jvzoo_transaction: ipnData.ctransaction },
    { status: 'refunded', refunded_at: new Date() }
  );
  await revokeAccess(user.id);
  break;

CGBK (Chargeback)

javascript

case 'CGBK':
  await db.licenses.update(
    { jvzoo_transaction: ipnData.ctransaction },
    { status: 'chargeback', chargeback_at: new Date() }
  );
  await revokeAccess(user.id);
  break;

INSTAL (Recurring Payment)

javascript

case 'INSTAL':
  await db.licenses.update(
    { jvzoo_transaction: ipnData.ctransaction },
    { 
      status: 'active',
      last_payment: new Date(),
      payment_count: { $inc: 1 }
    }
  );
  break;

CANCEL-REBILL (Subscription Cancelled)

javascript

case 'CANCEL-REBILL':
  await db.licenses.update(
    { jvzoo_transaction: ipnData.ctransaction },
    { 
      status: 'cancelled',
      cancelled_at: new Date()
    }
  );
  // Grace period before revoking access
  await scheduleAccessRevocation(user.id, 30); // 30 days
  break;

License Validation API

Build an API endpoint your software calls to validate licenses:

javascript

// POST /api/validate-license
async function validateLicense(req, res) {
  const { license_key, email } = req.body;
  
  const license = await db.licenses.findOne({
    license_key: license_key,
    status: 'active'
  });
  
  if (!license) {
    return res.json({ valid: false, error: 'Invalid license' });
  }
  
  const user = await db.users.findById(license.user_id);
  
  if (user.email !== email) {
    return res.json({ valid: false, error: 'Email mismatch' });
  }
  
  // Update last validation timestamp
  await db.licenses.update(
    { _id: license._id },
    { last_validated: new Date() }
  );
  
  return res.json({
    valid: true,
    license: {
      product_id: license.product_id,
      expiry_date: license.expiry_date,
      features: license.features
    }
  });
}

Database Schema Recommendations

Users Table

sql

CREATE TABLE users (
  id UUID PRIMARY KEY,
  email VARCHAR(255) UNIQUE NOT NULL,
  name VARCHAR(255),
  created_via VARCHAR(50),
  jvzoo_transaction VARCHAR(255),
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Licenses Table

sql

CREATE TABLE licenses (
  id UUID PRIMARY KEY,
  user_id UUID REFERENCES users(id),
  product_id VARCHAR(100) NOT NULL,
  license_key VARCHAR(50) UNIQUE NOT NULL,
  jvzoo_transaction VARCHAR(255) UNIQUE NOT NULL,
  jvzoo_receipt VARCHAR(255),
  status VARCHAR(50) NOT NULL, -- active, refunded, chargeback, cancelled
  purchase_date TIMESTAMP NOT NULL,
  expiry_date TIMESTAMP,
  last_validated TIMESTAMP,
  transaction_type VARCHAR(50),
  refunded_at TIMESTAMP,
  chargeback_at TIMESTAMP,
  cancelled_at TIMESTAMP,
  payment_count INTEGER DEFAULT 1,
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

Transactions Table (Audit Log)

sql

CREATE TABLE jvzoo_transactions (
  id UUID PRIMARY KEY,
  jvzoo_transaction_id VARCHAR(255) UNIQUE NOT NULL,
  transaction_type VARCHAR(50) NOT NULL,
  product_id VARCHAR(100) NOT NULL,
  customer_email VARCHAR(255) NOT NULL,
  amount DECIMAL(10,2),
  raw_ipn_data JSONB,
  processed BOOLEAN DEFAULT FALSE,
  processed_at TIMESTAMP,
  created_at TIMESTAMP DEFAULT NOW()
);

Product ID Mapping

Map JVZoo product IDs to your internal product identifiers:

javascript

const PRODUCT_MAPPING = {
  '123456': {
    name: 'AI Ranker Pro - Basic',
    features: ['feature1', 'feature2'],
    internal_id: 'ai-ranker-basic'
  },
  '123457': {
    name: 'AI Ranker Pro - Premium',
    features: ['feature1', 'feature2', 'feature3', 'feature4'],
    internal_id: 'ai-ranker-premium'
  },
  '123458': {
    name: 'Callfluent AI - Starter',
    features: ['100-calls', 'basic-voices'],
    internal_id: 'callfluent-starter'
  }
};

function getProductConfig(jvzooProductId) {
  return PRODUCT_MAPPING[jvzooProductId] || null;
}

Security Best Practices

Environment Variables

Never hardcode credentials:

bash

JVZOO_SECRET_KEY=your_secret_key_here
LICENSE_SECRET=separate_key_for_license_generation
DATABASE_URL=your_database_connection
SMTP_API_KEY=email_service_key

Rate Limiting

Protect your IPN endpoint from abuse:

javascript

const rateLimit = require('express-rate-limit');

const ipnLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // Max 100 requests per IP
  message: 'Too many requests from this IP'
});

app.post('/ipn', ipnLimiter, handleIPN);

Input Validation

Always validate and sanitize IPN data:

javascript

function sanitizeIPNData(data) {
  return {
    ctransaction: String(data.ctransaction || '').trim(),
    ccustemail: String(data.ccustemail || '').toLowerCase().trim(),
    ccustname: String(data.ccustname || '').trim(),
    cproditem: String(data.cproditem || '').trim(),
    ctransamount: parseFloat(data.ctransamount || 0),
    // ... sanitize all fields
  };
}

Error Handling

Always return 200 OK to prevent retries, but log errors:

javascript

app.post('/ipn', async (req, res) => {
  try {
    // Always acknowledge receipt
    res.status(200).send('OK');
    
    // Process asynchronously
    await processIPN(req.body);
  } catch (error) {
    // Log error but don't tell JVZoo about it
    console.error('IPN Processing Error:', error);
    await logError(error, req.body);
  }
});

Testing Your Integration

Test Mode

JVZoo provides test IPNs. Look for test indicators:

javascript

function isTestTransaction(ipnData) {
  return ipnData.ctransaction.toLowerCase().includes('test') ||
         ipnData.ccustemail.toLowerCase().includes('test');
}

Manual IPN Testing

Send test IPN to your endpoint:

bash

curl -X POST https://yoursite.com/ipn \
  -d "ctransaction=TEST123456" \
  -d "ccustemail=test@example.com" \
  -d "ccustname=Test User" \
  -d "cproditem=123456" \
  -d "ctransamount=97.00" \
  -d "ctransaction_type=SALE" \
  -d "cverify=YOUR_CALCULATED_HASH"

Validation Checklist

Common Implementation Frameworks

Node.js + Express

See references/nodejs-implementation.md for complete Express.js example with middleware, error handling, and database integration.

Python + FastAPI

See references/python-implementation.md for FastAPI implementation with async handling and Pydantic validation.

Next.js API Routes

See references/nextjs-implementation.md for serverless implementation using Next.js API routes with Supabase.

Troubleshooting

IPN not being received:

•Check JVZoo IPN URL configuration in product settings
•Verify endpoint is publicly accessible (not localhost)
•Check firewall/server logs
•Ensure endpoint responds within 10 seconds

Hash verification failing:

•Verify secret key matches JVZoo dashboard
•Check parameter order in hash calculation
•Ensure string concatenation uses pipes (|)
•Convert hash to uppercase for comparison

Duplicate accounts created:

•Implement idempotency check using ctransaction
•Use database constraints on transaction ID
•Log all IPN requests to audit table

License validation failing:

•Check license status in database
•Verify email matches purchase email
•Ensure license hasn't been refunded/charged back
•Check for expiry dates on time-limited licenses

Quick Start Template

For fastest implementation, use scripts/setup_ipn_endpoint.js to generate boilerplate IPN handler with your framework of choice (Express, FastAPI, Next.js).

See references/deployment-guide.md for production deployment considerations including SSL, monitoring, logging, and backup strategies.