Integrate any Payment Processor with your Program
This article details the manual integration steps for Rapid Affiliates when using a non‐Stripe payment processor, outlining how to install the tracking script and notify Rapid Affiliates of checkout, sale, and refund events. It provides clear, step-by-step instructions and code samples to ensure a seamless manual integration process.
Written by Adrian
Apr 11, 2025
When you choose a payment processor other than Stripe, a manual integration process ensures that your Rapid Affiliates program continues to track referrals and manage commissions effectively. This guide walks you through installing the vital tracking script and configuring your system to notify Rapid Affiliates when a checkout is initiated, a sale is completed, or a refund is processed.
Step 1: Installing the Tracking Script
The foundation of manual integration is our lightweight 1KB tracking script. This script captures critical referral data and generates a unique reference ID for each customer session. To integrate it:
Direct HTML Implementation:
<script
src="https://rapidaff.io/scripts/ra.js"
async
data-rapidaff="<<YOUR_UNIQUE_ID>>">
</script>
If you are using a modern framework like Next.js, you can place the script in your Root layout file:
Using Next.js
import Script from "next/script";
export default function RootLayout({ children }) {
return (
<html lang="en">
<Script
strategy="afterInteractive"
src="https://rapidaff.io/scripts/ra.js"
async={true}
data-rapidaff="YOUR_UNIQUE_ID"
/>
<body>{children}</body>
</html>
);
}
This script is essential as it enables your system to capture a reference ID (if available) through window.rapidaff?.ref for later use in tracking referral events.
Step 2: Notifying on Checkout Session Creation
When a customer initiates a checkout, your application should attempt to retrieve the reference ID provided by the tracking script. If a reference ID exists, notify Rapid Affiliates by sending a POST request to our endpoint. This ensures that every referral is properly recorded.
const refId = window.rapidaff?.ref;
if (refId) {
fetch("https://rapidaff.io/api/script/manual/lead", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
secret_key: process.env.RAPIDAFF_SECRET_KEY, // Ensure your secret key is stored securely
customer_email: "[email protected]", // Replace with the customer’s email
ref_id: refId
})
});
}
This step is crucial for associating referral data with the correct customer journey within your program.
Step 3: Reporting a Successful Sale
After a transaction is completed, it’s important to report the sale details so that commissions can be calculated accurately. Including information such as the sale amount, currency, and invoice URL in your POST request will streamline commission management.
const RAPIDAFF_SECRET_KEY = process.env.RAPIDAFF_SECRET_KEY;
const customerEmail = "[email protected]"; // Replace with actual customer email
const saleCurrency = "USD"; // Use the ISO 4217 format for currency
const saleAmount = 1000; // Replace with the actual sale amount
const invoiceUrl = "https://example.com/invoice/123.pdf"; // Replace with the invoice URL
const fullName = "John Doe"; // Optional, customer’s full name
fetch("https://rapidaff.io/api/script/manual/sale", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
secret_key: RAPIDAFF_SECRET_KEY,
customer_email: customerEmail,
sale_currency: saleCurrency,
sale_amount: saleAmount,
invoice_url: invoiceUrl,
full_name: fullName
})
});
Reporting sales promptly ensures that referral credits and commission payouts remain accurate and up-to-date.
Step 4: Reporting Refunds
In situations where a refund (either full or partial) is processed, it is essential to update Rapid Affiliates so that commission adjustments can be made accordingly. Use the refund endpoint to send the necessary details, including the original invoice URL, refund amount, and currency.
const RAPIDAFF_SECRET_KEY = process.env.RAPIDAFF_SECRET_KEY;
const invoiceUrl = "https://example.com/invoice/123.pdf"; // Original sale invoice URL
const refundCurrency = "USD"; // Refund currency in ISO 4217 format
const refundAmount = 300; // Actual refund amount
fetch("https://rapidaff.io/api/script/manual/refund", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
secret_key: RAPIDAFF_SECRET_KEY,
invoice_url: invoiceUrl,
refund_currency: refundCurrency,
refund_amount: refundAmount
})
});
Timely updates about refunds help maintain the integrity of your affiliate data, ensuring proper commission recalculations.
Troubleshooting & Best Practices
- Secure Your Secret Key: Always store your secret key on the server side and avoid exposing it in client-side code.
- Verify Script Installation: If referral data isn’t being captured, double-check that the tracking script is correctly implemented and placed within the
<head>of your project. - Test in Staging: Before deploying to production, test each API call (lead, sale, and refund) in a staging environment to ensure data consistency.
- Review API Responses: Monitor responses from the API endpoints for any errors or discrepancies, and adjust your implementation as needed.
Final Thoughts
By following these manual integration steps, you can effortlessly integrate any payment processor with your Rapid Affiliates program. This approach provides maximum flexibility while ensuring that your referral tracking, sales reporting, and refund management all work in harmony. If you are using Stripe, consider referring to our dedicated Stripe integration guide for a more automated process using Stripe Connect.
For further assistance or questions, our support team is always here to help you ensure a smooth and effective setup.
