Skip to main content

​
Automatic Callback Handling

Moflay automatically handles all callbacks from Safaricom’s Daraja API after successful payments. You don’t need to implement any callback handling logic in your application.
This means you can focus on building your payment flow without worrying about the complex callback processing that’s typically required when integrating directly with Safaricom’s Daraja API.

​
How It Works

​
1. Payment Initiation

When you initiate a payment through Moflay’s API, we:
  • Send the STK Push request to Safaricom
  • Handle the authentication and token management
  • Monitor the transaction status

​
2. Automatic Callback Processing

After Safaricom processes the payment, they send callbacks to Moflay’s servers:
  • Success callbacks - When payment is completed
  • Timeout callbacks - When payment times out
  • Cancellation callbacks - When user cancels the payment

​
3. Status Updates

Moflay automatically:
  • Processes all incoming callbacks from Safaricom
  • Updates the transaction status in our system
  • Provides real-time status updates through our API
  • Handles retries and error scenarios

​
What You Need to Do

​
Nothing!

Moflay handles everything automatically. Simply:
  1. Initiate payments using our API or SDK
  2. Wait for the response - the express endpoint waits until the user completes the payment
  3. Handle the final status in your application

​
Example Flow

// Make payment - the endpoint waits until user completes payment
const result = await moflay.express.pay({
  amount: 100,
  phoneNumber: "254712345678",
  description: "Product Payment"
});

// The response contains the final status immediately
if (result.status === 'completed') {
  // Payment successful - update your system
  console.log('Payment completed!');
} else if (result.status === 'failed') {
  // Payment failed - handle accordingly
  console.log('Payment failed');
}

​
Benefits of Automatic Callback Handling

​
Simplified Integration

  • No callback endpoints to implement
  • No webhook configuration required
  • No callback validation needed
  • No retry logic to manage

​
Reliability

  • Automatic retries for failed callbacks
  • Duplicate detection to prevent double processing
  • Error handling for all edge cases
  • Monitoring and alerting built-in

​
Security

  • Secure callback processing on our infrastructure
  • Automatic signature verification from Safaricom
  • Encrypted data transmission throughout the flow

​
Transaction Statuses

Moflay provides clear transaction statuses that you can rely on:
StatusDescription
pendingPayment initiated, waiting for user action
completedPayment successfully completed
failedPayment failed (insufficient funds, user cancelled, etc.)

​
Monitoring and Debugging

​
Real-time Status Updates

The express endpoint provides immediate status updates when you make a payment request: 
curl -H "Authorization: Bearer mf_test_1234567890" \
  -X POST "https://api.moflay.com/v1/express" \
  -d '{"amount": 100, "phoneNumber": "254712345678", "description": "Test Payment"}'

​
Dashboard Monitoring

View all transactions and their statuses in the Moflay Dashboard.

​
Webhook Support (Coming Soon)

We’re working on webhook support for real-time notifications when transaction statuses change.

​
Common Questions

No. Moflay handles all callback URLs automatically. You don’t need to configure anything.
The express endpoint tells you immediately. When you call the express payment endpoint, it waits until the user completes the payment and returns the final status in the response.
The express endpoint will return the appropriate status (failed or timeout) immediately. You can handle these cases in your application logic without needing to poll or check status separately.
Yes. You can view detailed transaction information including callback data in the Moflay Dashboard or through our API endpoints.
Yes, payments have a timeout period. If a user doesn’t complete the payment within the timeout window, the express endpoint will return a timeout status. The exact timeout duration is managed by Safaricom’s Daraja API.

​
Next Steps

  1. Start building your payment integration using our API or SDK
  2. Test thoroughly in the sandbox environment
  3. Monitor transactions through our dashboard
  4. Go live when you’re ready
If you’re migrating from a direct Daraja integration, you can remove all your callback handling code - Moflay takes care of everything!