Built for startups,
scaled for unicorns
Successfully submitted!
Error! Please try again
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.
Configure your PayPal account for programmatic payouts.
Before processing real money, validate your integration in PayPal's test environment.
Create an endpoint that receives GrowSurf reward events and initiates PayPal payouts.
PARTICIPANT_REACHED_REWARD webhook eventUse PayPal's Payouts API to send money to the referrer's PayPal account.
POST /v1/payments/payoutsMonitor payout delivery and handle cases where payouts fail.
Ensure your payout system complies with tax and financial regulations.
// 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 });
}
});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.
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.
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.
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.
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.
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.
Trusted by marketing and product teams at fast-growing B2C, fintech, and SaaS companies
