Integration Guide
Go live in hours, not weeks
Average integration time
From signup to production
Developer support
Integration Overview
Integrating RibiRewards into your platform takes less than 2 hours. You'll be able to send gifts programmatically, receive webhook notifications, and provide white-labeled experiences to your users.
RESTful API
Standard HTTP methods, JSON payloads
Sandbox Environment
Test without sending real gifts
Real-Time Webhooks
Get notified on gift status changes
White-Label Support
Recipients see your branding
Get Your API Key
Sign up for a RibiRewards account and generate your API key from the dashboard.
Steps:
- 1Go to dashboard.ribirewards.com and create an account
- 2Navigate to Settings → API Keys
- 3Click "Generate New Key"
- 4Copy and securely store your API key (shown only once)
Important Security Notes
- • Never commit API keys to version control
- • Store keys in environment variables
- • Use separate keys for sandbox and production
- • Rotate keys if compromised
Your API keys will look like this:
Production: live_sk_1a2b3c4d5e6f7g8h9i0j
Sandbox: test_sk_9i8h7g6f5e4d3c2b1a0jMake Your First API Call
Test your integration by sending a gift in the sandbox environment. No real gifts are sent and no charges are made.
Choose Your Language:
1. Install the HTTP client (if needed)
npm install node-fetch2. Send a test gift
const fetch = require('node-fetch');
const sendTestGift = async () => {
try {
const response = await fetch('https://sandbox-api.ribirewards.com/v1/choice-cards', {
method: 'POST',
headers: {
'Authorization': 'Bearer test_sk_YOUR_SANDBOX_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
category: 'coffee',
amount: 50,
recipients: [
{
email: 'test@example.com',
name: 'Test User'
}
],
branding: {
company_name: 'Your Company',
from_email: 'rewards@yourcompany.com',
message: 'Enjoy your gift!'
}
})
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const data = await response.json();
console.log('Success! Order ID:', data.order_id);
console.log('Status:', data.status);
console.log('Recipient link:', data.recipient_links[0].redemption_url);
} catch (error) {
console.error('Error:', error.message);
}
};
sendTestGift();Expected Response
You should receive a 200 OK response with an order_id and redemption_url.
{
"order_id": "RG-CC-2026-TEST-001",
"status": "sent",
"recipient_links": [...]
}Configure Webhooks
Webhooks notify you in real-time when gifts are sent, redeemed, or expired. Set up a webhook endpoint to receive these events.
Available Events:
gift.sentGift email sent to recipient
gift.redeemedRecipient redeemed their gift
gift.expiredGift expired without redemption
order.completedAll recipients have redeemed
Example Webhook Handler:
const express = require('express');
const app = express();
app.use(express.json());
app.post('/webhooks/ribirewards', (req, res) => {
const event = req.body;
console.log('Received webhook:', event.event);
switch(event.event) {
case 'gift.sent':
console.log(`Gift sent to ${event.data.recipient_email}`);
// Update your database
break;
case 'gift.redeemed':
console.log(`Gift redeemed by ${event.data.recipient_email}`);
console.log(`Products selected:`, event.data.products_selected);
// Trigger analytics event
break;
case 'gift.expired':
console.log(`Gift expired for ${event.data.recipient_email}`);
// Send reminder email?
break;
case 'order.completed':
console.log(`Order ${event.data.order_id} fully redeemed!`);
// Mark campaign as successful
break;
}
// Always respond with 200 to acknowledge receipt
res.status(200).json({ received: true });
});
app.listen(3000, () => {
console.log('Webhook server running on port 3000');
});Register Your Webhook URL:
- 1Go to Settings → Webhooks in your dashboard
- 2Add your webhook URL (must be HTTPS in production)
- 3Select which events you want to receive
- 4Save and copy your webhook secret for signature verification
Webhook Security
Verify webhook signatures using your webhook secret to ensure requests are from RibiRewards. See API docs for signature verification.
Configure White-Labeling
Make the recipient experience look like it's from your platform, not RibiRewards. Customize branding for every gift.
Branding Options:
{
"branding": {
"company_name": "Merit Incentives",
"logo_url": "https://yourcompany.com/logo.png",
"from_email": "rewards@meritincentives.com",
"reply_to_email": "support@meritincentives.com",
"primary_color": "#2563eb",
"message": "Congratulations on your achievement!",
"email_footer": "Questions? Contact us at support@meritincentives.com"
}
}What Gets Branded:
From your company name and email
Your logo, colors, and messaging
Recipients see your branding throughout
Order confirmations from your email
Custom Domain (Optional):
Use Your Own Domain
Set up a CNAME record to serve redemption pages from your domain (e.g., gifts.yourcompany.com)
Contact dev@ribirewards.com for CNAME setup instructions.
Go Live
You've tested in sandbox, configured webhooks, and set up branding. Now switch to production and start sending real gifts!
Pre-Launch Checklist:
Switch to Production:
- 1Generate a production API key (starts with
live_) - 2Update your base URL from
sandbox-apitoapi - 3Update your webhook URL to production endpoint
- 4Send a small test gift to a real email address to verify
- 5Monitor the dashboard for successful delivery
You're Live! 🎉
Congratulations! You can now send gifts across 10 African countries programmatically.