Quickstart
This guide will help you make your first request to the Batchmates API within minutes. We'll walk through authentication, making requests, and handling responses.
This quickstart uses JWT authentication. For web admin interfaces using session-based auth, see the Authentication Guide.
Prerequisites
Before you start, you'll need:
- User Account - Register at batchmates-v2.revlv.com
- API Access - User accounts automatically have API access
- HTTP Client - Any tool that can make HTTP requests (curl, Postman, or programming language)
Step 1: Authentication
First, obtain a JWT token by authenticating with your credentials.
POST
/v1/mobile/auth/logincurl -X POST https://batchmates-v2.revlv.com/api/v1/mobile/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "your@email.com",
"password": "your-password"
}'
Response
{
"success": true,
"data": {
"access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"token_type": "bearer",
"expires_in": 3600,
"user": {
"id": 5,
"name": "Juan Dela Cruz",
"email": "your@email.com"
}
},
"message": "Login successful"
}
Store the access_token securely. You'll need it for all authenticated requests. The token expires in 1 hour (3600 seconds).
Step 2: Browse Active Campaigns
Now let's fetch active campaigns that accept donations.
GET
/v1/campaignscurl -G https://batchmates-v2.revlv.com/api/v1/campaigns \
-H "Authorization: Bearer {your_token_here}" \
-d "status=active" \
-d "per_page=5"
Response
{
"success": true,
"data": {
"current_page": 1,
"data": [
{
"id": 5,
"title": "Engineering Scholarship Fund",
"description": "Supporting bright engineering students...",
"goal_amount": "100000.00",
"raised_amount": "45000.00",
"progress_percentage": 45.0,
"status": "active",
"institution": {
"id": 1,
"name": "University of the Philippines"
}
}
],
"per_page": 5,
"total": 24
}
}
Step 3: Make a Donation
Let's make a donation to a campaign. This initiates the payment process.
POST
/v1/donationscurl -X POST https://batchmates-v2.revlv.com/api/v1/donations \
-H "Authorization: Bearer {your_token_here}" \
-H "Content-Type: application/json" \
-d '{
"campaign_id": 5,
"amount": 1000,
"payment_gateway": "maya",
"message": "Supporting education!"
}'
Response
{
"success": true,
"data": {
"redirectUrl": "https://checkout.maya.ph/v1/checkouts/...",
"transaction_id": "maya_abc123xyz",
"reference_number": "550e8400-e29b-41d4-a716-446655440000"
},
"message": "Payment initiated successfully"
}
Redirect the user to the redirectUrl to complete payment. After payment, they'll be redirected back to your app with the transaction status.
Step 4: Check Donation History
View your donation history and track payment status.
GET
/v1/donations/mycurl https://batchmates-v2.revlv.com/api/v1/donations/my \
-H "Authorization: Bearer {your_token_here}"
Response
{
"success": true,
"data": {
"current_page": 1,
"data": [
{
"id": 45,
"campaign_id": 5,
"amount": "1000.00",
"status": "completed",
"payment_method": "gcash",
"paid_at": "2024-02-06T10:30:00.000000Z",
"campaign": {
"id": 5,
"title": "Engineering Scholarship Fund"
}
}
],
"per_page": 20,
"total": 3
}
}
Error Handling
Always check for errors in API responses:
const response = await fetch(url, options);
const result = await response.json();
if (!result.success) {
console.error('API Error:', result.message);
// Handle validation errors
if (result.errors) {
Object.keys(result.errors).forEach(field => {
console.error(`${field}: ${result.errors[field].join(', ')}`);
});
}
return;
}
// Success - use result.data
console.log('Success:', result.data);
Common Errors
- Name
401 Unauthorized- Description
Token is missing, invalid, or expired - log in again
- Name
422 Validation Error- Description
Check
errorsobject for field-specific validation messages
- Name
429 Rate Limit- Description
Too many requests - wait before retrying
See Error Handling for complete documentation.
Complete Example
Here's a complete flow from authentication to donation:
class BatchmatesAPI {
constructor(baseURL = 'https://batchmates-v2.revlv.com/api/v1') {
this.baseURL = baseURL;
this.token = localStorage.getItem('auth_token');
}
async login(email, password) {
const response = await fetch(`${this.baseURL}/mobile/auth/login`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ email, password })
});
const result = await response.json();
if (result.success) {
this.token = result.data.access_token;
localStorage.setItem('auth_token', this.token);
}
return result;
}
async getCampaigns(params = {}) {
const query = new URLSearchParams({ status: 'active', ...params });
const response = await fetch(`${this.baseURL}/campaigns?${query}`, {
headers: { 'Authorization': `Bearer ${this.token}` }
});
return response.json();
}
async createDonation(campaignId, amount, gateway = 'maya') {
const response = await fetch(`${this.baseURL}/donations`, {
method: 'POST',
headers: {
'Authorization': `Bearer ${this.token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
campaign_id: campaignId,
amount: amount,
payment_gateway: gateway
})
});
return response.json();
}
async getMyDonations() {
const response = await fetch(`${this.baseURL}/donations/my`, {
headers: { 'Authorization': `Bearer ${this.token}` }
});
return response.json();
}
}
// Usage
const api = new BatchmatesAPI();
// Login
await api.login('your@email.com', 'your-password');
// Browse campaigns
const { data: campaigns } = await api.getCampaigns();
console.log('Active campaigns:', campaigns.data);
// Make donation
const donation = await api.createDonation(5, 1000);
window.location.href = donation.data.redirectUrl;
// Check history
const { data: history } = await api.getMyDonations();
console.log('Your donations:', history.data);
Next Steps
Now that you've made your first requests, explore these topics:
Authentication - Token refresh and session managementSubscriptions - Set up recurring donationsPayment Methods - Save cards for recurring donationsWebhooks - Receive real-time payment notificationsError Handling - Handle all error scenariosRate Limiting - Optimize API usage