Webhooks

Webhooks allow you to receive real-time notifications when payment events occur. Maya sends webhook events to inform you about donation status changes.

Overview

Instead of polling the API to check donation status, configure webhooks to receive automatic notifications when:

Payment is completed
Payment fails
Payment expires
Payment is cancelled

Benefits

Name
Real-time Updates
Description
Get instant notifications without polling
Name
Reduced API Calls
Description
No need to constantly check donation status
Name
Reliable
Description
Payment gateways retry failed webhook deliveries
Name
Automatic
Description
Updates happen in the background without user action

Webhook Endpoints

Batchmates provides a dedicated webhook endpoint for the payment gateway:

Name
Maya Webhook
Description
POST https://batchmates-v2.revlv.com/api/v1/payments/maya/webhook

Maya Webhooks

Webhook Events

Maya sends the following events:

Name
PAYMENT_SUCCESS
Description
Payment completed successfully
Name
PAYMENT_FAILED
Description
Payment failed (insufficient funds, declined card, etc.)
Name
PAYMENT_EXPIRED
Description
Checkout session expired before payment
Name
PAYMENT_CANCELLED
Description
User cancelled payment

Payload Structure

{
  "id": "maya_ch_abc123xyz",
  "status": "PAYMENT_SUCCESS",
  "requestReferenceNumber": "550e8400-e29b-41d4-a716-446655440000",
  "amount": {
    "value": 1000.00,
    "currency": "PHP"
  },
  "paymentMethod": "card",
  "createdAt": "2024-02-06T10:30:00Z",
  "completedAt": "2024-02-06T10:30:15Z"
}

Example: Payment Success

Maya Webhook - Payment Success

{
  "id": "maya_ch_abc123xyz",
  "status": "PAYMENT_SUCCESS",
  "requestReferenceNumber": "550e8400-e29b-41d4-a716-446655440000",
  "amount": {
    "value": 1040.00,
    "currency": "PHP"
  },
  "paymentMethod": "card",
  "customer": {
    "email": "donor@example.com"
  },
  "createdAt": "2024-02-06T10:30:00Z",
  "completedAt": "2024-02-06T10:30:15Z"
}

What happens:

Maya sends webhook to your endpoint
Batchmates verifies signature
Donation status updated to completed
Campaign raised_amount and available_amount incremented
User receives success notification

Example: Payment Failed

Maya Webhook - Payment Failed

{
  "id": "maya_ch_def456abc",
  "status": "PAYMENT_FAILED",
  "requestReferenceNumber": "650e8400-e29b-41d4-a716-446655440001",
  "amount": {
    "value": 1040.00,
    "currency": "PHP"
  },
  "failureReason": "Insufficient funds",
  "createdAt": "2024-02-06T10:35:00Z"
}

What happens:

Maya sends webhook
Donation status updated to failed
User can retry payment from their donation history

Webhook Security

Maya's webhook endpoint is protected by an IP allowlist — only Maya's published webhook source IPs are accepted:

Environment	Source IPs
Sandbox	`13.229.160.234`, `3.1.199.75`
Production	`18.138.50.235`, `3.1.207.200`

Requests from any other source are rejected before the handler runs. The success redirect additionally calls verifyAndComplete(), which confirms the payment status directly with Maya's API before a donation is marked complete.

Batchmates API automatically handles webhook verification. You don't need to implement this unless building your own webhook handlers.

Testing Webhooks

Using Webhook Testing Tools

1. ngrok for Local Development

# Install ngrok
brew install ngrok  # macOS
# or download from ngrok.com

# Start your local server
php artisan serve

# Expose port 8000
ngrok http 8000

# Use the ngrok URL in payment gateway settings
# https://abc123.ngrok.io/api/v1/payments/maya/webhook

2. RequestBin for Quick Testing

# Create a RequestBin at requestbin.com
# Use the bin URL to inspect webhook payloads

Manual Webhook Testing

Test Maya Webhook

curl -X POST https://batchmates-v2.revlv.com/api/v1/payments/maya/webhook \
  -H "Content-Type: application/json" \
  -H "Maya-Signature: {computed_signature}" \
  -d '{
    "id": "maya_test_123",
    "status": "PAYMENT_SUCCESS",
    "requestReferenceNumber": "550e8400-e29b-41d4-a716-446655440000",
    "amount": {
      "value": 1040.00,
      "currency": "PHP"
    }
  }'

Webhook Flow Diagram

Complete Payment Flow

sequenceDiagram
    participant User
    participant App
    participant API
    participant Gateway
    
    User->>App: Click "Donate"
    App->>API: POST /donations
    API->>Gateway: Create checkout
    Gateway-->>API: Checkout URL
    API-->>App: Redirect URL
    App->>Gateway: Redirect to payment
    User->>Gateway: Enter payment details
    Gateway->>Gateway: Process payment
    Gateway->>API: Webhook: PAYMENT_SUCCESS
    API->>API: Update donation status
    API->>API: Update campaign balances
    API->>User: Send notification
    Gateway->>User: Redirect to success page
    User->>App: View success page

Webhook Event Reference

Maya Events

Event	Description	Action
PAYMENT_SUCCESS	Payment completed	Mark donation completed
PAYMENT_FAILED	Payment failed	Mark donation failed
PAYMENT_EXPIRED	Session expired	Mark donation expired
PAYMENT_CANCELLED	User cancelled	Mark donation cancelled

Troubleshooting

Webhook Not Received

Check:

Webhook URL configured correctly in gateway dashboard
Server is publicly accessible (not behind firewall)
HTTPS enabled (required by most gateways)
No rate limiting blocking webhook requests

Webhook Rejected

Check:

Request originates from a Maya webhook source IP (sandbox or production allowlist)
Server is publicly reachable over HTTPS
No proxy is rewriting the source IP — configure trusted proxies if fronted by a load balancer

Donation Not Updating

Check:

Webhook handler returns 200 OK
Reference number matches donation record
Idempotency checks not blocking legitimate updates
Database transaction not rolled back due to error

Testing Webhooks

# Check if webhook endpoint is accessible
curl -I https://batchmates-v2.revlv.com/api/v1/payments/maya/webhook

# Should return 405 Method Not Allowed (POST required)
# If timeout or connection error, check firewall/DNS

Need Help?

If webhooks aren't working as expected:

Check webhook logs in payment gateway dashboard
Verify webhook URL configuration
Test with manual webhook calls
Review signature verification implementation
Contact support with webhook payload and error logs

Contact Support Donations API