K

Custom API Integration

Use our flexible API to integrate Revshare with any payment provider. Whether you use Paddle, Lemon Squeezy, Gumroad, Razorpay, or a custom payment solution, our API works seamlessly with your existing setup.

Emil Klitmose

Written by Emil Klitmose

Updated recently

Overview

The Custom API integration allows you to track affiliate sales with any payment provider. The Custom API gives you complete control over when and how commissions are recorded.

This integration works with Paddle, Lemon Squeezy, Gumroad, Razorpay, PayPal, Polar, Dodo, and any custom payment solution. As long as your payment provider supports webhooks or payment confirmations, you can integrate with Revshare.

How It Works

The integration follows a simple flow:

  1. Visitor clicks affiliate link — When someone clicks an affiliate link (e.g., yoursite.com?ref=john123), our tracking script captures the referral code and stores it in a cookie.
  2. Pass referral to checkout — When opening your payment provider's checkout, pass the referral code from window.revshare_metadata.ref_code to your payment provider's custom data, metadata, or notes field.
  3. Customer makes purchase — When a customer completes a purchase, your payment provider sends a webhook to your backend.
  4. Extract referral data — In your webhook handler, extract the referral code and sale details from the webhook payload.
  5. Call Revshare API — Make a POST request to our Referral API endpoint with the sale details (amount, currency, transaction ID, referral code).
  6. Commission recorded — Revshare calculates and records the commission based on your program settings. The affiliate can see the sale in their dashboard.

Setup Steps

Follow these steps to set up the Custom API integration:

  1. Add Tracking Script — Copy the tracking script from your Revshare dashboard and add it to your website's HTML, typically in the <head> section. This script automatically captures affiliate referral codes from URLs.
  2. Pass Referral to Checkout — When opening your payment provider's checkout, pass the referral code from window.revshare_metadata.ref_code to your payment provider's custom data/metadata fields. The exact field name depends on your provider (e.g., custom_data for Paddle, custom for Lemon Squeezy).
  3. Get Your API Key — Find your API key in Dashboard → Account & Billing. The same key works for all your programs. Keep this key secure and never expose it in client-side code.
  4. Create Webhook Handler — Set up a webhook endpoint in your backend that receives payment confirmations from your payment provider. Verify the webhook signature to ensure requests are legitimate.
  5. Call Revshare API — When a payment is confirmed, extract the referral code and sale details from the webhook payload, then call our Referral API endpoint. Only call the API if there's a referral code present (not all sales will have one).
  6. Test Integration — Make a test purchase through an affiliate link and verify the commission appears in your dashboard. Check that the amount, currency, and affiliate are correct.

Security Note: Always call the Revshare API from your backend server, never from client-side code. This keeps your API key secure and prevents unauthorized access.

API Reference

The Referral API endpoint accepts sale data and records affiliate commissions:

Endpoint: POST https://www.revshare.so/api/referral

Header: x-api-key: YOUR_API_KEY

Content-Type: application/json

{
  "ref_code": "john123",           // required: affiliate referral code
  "program_id": "YOUR_PROGRAM_ID", // required: your program ID
  "spent_amount": 5000,            // required: amount in cents
  "currency": "USD",                // optional: defaults to USD
  "transaction_id": "order_123",  // required: unique per transaction
  "customer_id": "cust_456"        // optional: for recurring tracking
}

Request Parameters

ref_code string, required — affiliate referral code from tracking script

program_id string, required — your Revshare program ID

spent_amount integer, required — sale amount in cents (e.g., $50.00 = 5000)

transaction_id string, required — unique identifier for this transaction

currency string, optional — ISO currency code (defaults to USD)

customer_id string, optional — customer identifier for recurring revenue tracking

Recurring Revenue: Include customer_id to track recurring payments. Revshare uses this to distinguish first purchases from repeat customers. See our Recurring Revenue Guide for details.

Examples

Here's a generic webhook handler pattern that works with any payment provider:

// Generic webhook handler (Next.js example)
export async function POST(req) {
  const event = await req.json();
  
  // 1. Verify webhook signature (provider-specific)
  // 2. Check if payment is successful
  // 3. Extract referral code from custom_data/metadata
  // 4. Extract sale amount, currency, transaction ID, customer ID
  
  if (event.status === 'completed' && event.ref_code) {
    await fetch('https://www.revshare.so/api/referral', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.REVSHARE_API_KEY,
      },
      body: JSON.stringify({
        ref_code: event.ref_code,
        program_id: event.program_id,
        spent_amount: event.amount,  // convert to cents if needed
        currency: event.currency,
        transaction_id: event.id,
        customer_id: event.customer_id,  // optional, for recurring
      }),
    });
  }
  
  return Response.json({ received: true });
}

The exact implementation depends on your payment provider. For provider-specific examples (Paddle, Lemon Squeezy, Gumroad, etc.), see our complete Integration Guide with detailed code examples for each provider.

Common Provider Patterns

Paddle: Extract from event.data.custom_data

Lemon Squeezy: Extract from event.data.attributes.custom_data

Gumroad: Extract from product metadata or custom fields

Razorpay: Extract from payment notes or metadata