← View All Guides
PayPal logo
Integration Guide

How to Pay Referral Rewards via PayPal with GrowSurf

Automate cash reward payouts to referral program participants using PayPal's Payouts API and GrowSurf webhooks.

Cash rewards are the most universally appealing referral incentive β€” everyone likes money. PayPal is the fastest and most accessible way to deliver cash rewards to referral participants worldwide. By connecting GrowSurf's reward events to PayPal's Payouts API, you can automatically send money to referrers' PayPal accounts when their referrals convert, with no manual processing required.

This guide covers setting up PayPal Payouts for your GrowSurf referral program, building the webhook handler that triggers payments, managing payout batches, handling international payments and currency conversion, and tracking payout history for accounting and tax compliance.

Integration Steps

Step 1: Set Up PayPal Business Account and API Access

Configure your PayPal account for programmatic payouts.

  • Ensure you have a PayPal Business account (personal accounts can't use the Payouts API)
  • Go to developer.paypal.com
  • Create a REST API app in Dashboard > My Apps & Credentials
  • Get your Client ID and Secret for both sandbox (testing) and live environments
  • Apply for Payouts API access β€” PayPal may require additional verification for Payouts

Step 2: Test Payouts in PayPal Sandbox

Before processing real money, validate your integration in PayPal's test environment.

  • Create sandbox buyer and seller accounts in the Sandbox > Accounts section
  • Use sandbox API credentials for development
  • Test single payouts and batch payouts to verify your code works
  • Verify that test emails are sent and balances update in sandbox accounts

Step 3: Build the Reward Payout Webhook Handler

Create an endpoint that receives GrowSurf reward events and initiates PayPal payouts.

  • Listen for GrowSurf's PARTICIPANT_REACHED_REWARD webhook event
  • Validate the participant's eligibility and the reward amount
  • Check if the participant has a PayPal email on file (may differ from their signup email)
  • Create a PayPal Payout using the Payouts API

Step 4: Process PayPal Payouts

Use PayPal's Payouts API to send money to the referrer's PayPal account.

  • Authenticate with PayPal's OAuth endpoint to get an access token
  • Create a payout using POST /v1/payments/payouts
  • Include: recipient email, amount, currency, and a unique sender_batch_id
  • Handle the response: check payout status (PENDING, SUCCESS, FAILED)
  • PayPal sends the money directly to the recipient's PayPal balance or linked bank

Step 5: Track Payout Status and Handle Failures

Monitor payout delivery and handle cases where payouts fail.

  • PayPal payouts can have statuses: PENDING, PROCESSING, SUCCESS, FAILED, UNCLAIMED
  • Set up PayPal webhooks to receive payout status updates
  • Handle FAILED payouts: notify your team and the participant, offer alternative payment methods
  • Handle UNCLAIMED payouts: the recipient doesn't have a PayPal account β€” send them instructions to create one or offer an alternative

Step 6: Manage Compliance and Tax Reporting

Ensure your payout system complies with tax and financial regulations.

  • In the US, issue 1099-NEC or 1099-MISC for participants earning $600+ annually
  • Collect tax information (SSN/EIN or W-9) from participants who exceed the threshold
  • Track all payouts in your accounting system with referral attribution for audit trails
  • Maintain records of: payout amount, date, recipient, referral ID, and PayPal transaction ID

Code Snippets

// PayPal Referral Reward Payout Handler
const paypal = require('@paypal/checkout-server-sdk');

// PayPal environment setup
const environment = process.env.NODE_ENV === 'production'
  ? new paypal.core.LiveEnvironment(process.env.PAYPAL_CLIENT_ID, process.env.PAYPAL_SECRET)
  : new paypal.core.SandboxEnvironment(process.env.PAYPAL_CLIENT_ID, process.env.PAYPAL_SECRET);
const paypalClient = new paypal.core.PayPalHttpClient(environment);

async function sendPayout(recipientEmail, amount, referralId) {
  const axios = require('axios');

  // Get PayPal access token
  const authResponse = await axios.post(
    `${process.env.PAYPAL_API_URL}/v1/oauth2/token`,
    'grant_type=client_credentials',
    {
      auth: {
        username: process.env.PAYPAL_CLIENT_ID,
        password: process.env.PAYPAL_SECRET
      }
    }
  );
  const accessToken = authResponse.data.access_token;

  // Create payout
  const payoutResponse = await axios.post(
    `${process.env.PAYPAL_API_URL}/v1/payments/payouts`,
    {
      sender_batch_header: {
        sender_batch_id: `growsurf-${referralId}-${Date.now()}`,
        email_subject: 'You received a referral reward!',
        email_message: 'Thanks for referring friends! Here is your reward.'
      },
      items: [{
        recipient_type: 'EMAIL',
        amount: { value: amount.toFixed(2), currency: 'USD' },
        receiver: recipientEmail,
        note: `Referral reward for referral ${referralId}`,
        sender_item_id: `ref-${referralId}`
      }]
    },
    { headers: { 'Authorization': `Bearer ${accessToken}` } }
  );

  return payoutResponse.data;
}

app.post('/webhooks/growsurf/payout', async (req, res) => {
  const { event, participant } = req.body;

  if (event !== 'PARTICIPANT_REACHED_REWARD') {
    return res.json({ skipped: true });
  }

  // Check idempotency
  const existing = await db.payouts.findByReferralId(participant.id);
  if (existing) return res.json({ message: 'Already processed' });

  const paypalEmail = participant.metadata?.paypalEmail || participant.email;
  const rewardAmount = 10.00; // $10 per referral

  try {
    const payout = await sendPayout(paypalEmail, rewardAmount, participant.id);
    await db.payouts.create({
      participantId: participant.id,
      paypalBatchId: payout.batch_header.payout_batch_id,
      amount: rewardAmount,
      status: 'pending'
    });
    res.json({ success: true, batchId: payout.batch_header.payout_batch_id });
  } catch (error) {
    console.error('Payout failed:', error);
    res.status(500).json({ error: error.message });
  }
});

Tips

Set a Minimum Payout Threshold

Don't process payouts for very small amounts. PayPal charges fees per payout, and a $1 reward with a $0.25 fee is inefficient. Set a minimum payout threshold (e.g., $5 or $10) and accumulate smaller rewards until the threshold is met. Communicate this clearly in your referral program terms.

Verify PayPal Emails Before First Payout

Ask participants to confirm their PayPal email address before sending the first payout. Their GrowSurf email may differ from their PayPal email. Store the verified PayPal email in GrowSurf participant metadata for accurate payouts.

Batch Payouts for Cost Efficiency

Instead of sending individual payouts for each reward event, batch payouts daily or weekly. PayPal's batch payout feature lets you send up to 15,000 payments in a single API call, and batch processing is more cost-effective than individual sends.

FAQ

What are PayPal's payout fees?

PayPal charges 2% per payout (capped at $20 USD per payout) for domestic US payouts. International payouts have higher fees. For Payouts through the API, you can choose whether the sender (your company) or the receiver pays the fee. Most referral programs absorb the fee as a cost of doing business.

What happens if the recipient doesn't have a PayPal account?

PayPal sends the recipient an email notifying them of the pending payout. They have 30 days to create a PayPal account and claim the funds. If unclaimed after 30 days, the money is returned to your PayPal balance. Your webhook handler should track unclaimed payouts and offer alternatives.

Can I send payouts in currencies other than USD?

Yes. PayPal Payouts supports 20+ currencies. Set the currency field in your payout item to the desired currency code (e.g., EUR, GBP, CAD). PayPal handles currency conversion automatically. Check current exchange rates and fees in your PayPal dashboard before offering multi-currency rewards.

Set up your refer a friend program with customer referral and affiliate program software that lowers your acquisition costs, increases customer loyalty, and saves you gobs of time.

Trusted by marketing and product teams at fast-growing B2C, fintech, and SaaS companies