This technical guide walks you through integrating the ElyonPay payment API with JavaScript step by step. From SDK installation to going live, learn how to accept Mobile Money payments across 14 African countries with just a few lines of code.
1Why Use the ElyonPay API
The ElyonPay API allows developers to integrate Mobile Money and card payments directly into their web or mobile applications, without depending on a hosted payment page. This approach offers full control over the user experience, allowing you to create fully customized payment flows that naturally integrate into your existing interface.
Unlike redirect solutions that send users to an external page to complete payment, the ElyonPay API allows processing the entire transaction server-side. The customer stays on your site or application throughout the process, which significantly reduces cart abandonment related to redirects. Merchants using the direct API see an average conversion rate 25% higher than those using hosted payment pages.
The API is RESTful, documented with OpenAPI 3.0, and available in a sandbox environment for testing. It supports Mobile Money payments in 14 African countries, Visa and Mastercard card payments, and local bank transfers. Webhooks allow you to receive real-time notifications about each transaction's status changes.
2Install the JavaScript SDK
The ElyonPay JavaScript SDK simplifies integration by encapsulating API calls in intuitive methods and automatically handling authentication, error management, and data serialization. The SDK is compatible with Node.js 16+ and can be used both server-side (Express, Fastify, NestJS) and in serverless environments (AWS Lambda, Vercel Functions).
npm install elyonpay-jsThe package weighs less than 50 KB minified and has zero external dependencies, ensuring minimal impact on your bundle size. It is also available via yarn and pnpm if you prefer those package managers. Once installed, you can import it using CommonJS or ESM depending on your project configuration.
// CommonJS
const ElyonPay = require('elyonpay-js');
// ESM
import ElyonPay from 'elyonpay-js';The SDK includes complete TypeScript types, providing autocompletion and type checking in modern IDEs like VS Code. This facilitates API discovery and reduces integration errors by warning you during development if a parameter is missing or invalid.
3Initialize the Client
Initializing the ElyonPay client requires your API key, which you can find in the "API Settings" section of your dashboard. You have two separate keys: a sandbox key for testing and a production key for real transactions. Never confuse the two environments and never commit your production key to a source code repository.
const ElyonPay = require('elyonpay-js');
const client = new ElyonPay({
apiKey: process.env.ELYONPAY_API_KEY,
environment: 'sandbox', // 'sandbox' or 'production'
timeout: 30000, // timeout in milliseconds
retries: 2 // number of retries on network failure
});The client automatically handles retries on temporary network errors, with exponential backoff to avoid overloading the servers. The timeout parameter defines the maximum wait time for each request. We recommend a 30-second timeout for Mobile Money payments, as user validation can take a few seconds.
Always store your API key in an environment variable and never hardcode it in your source code. Use a .env file for local development and your hosting platform's secrets for production. This practice is essential for the security of your integration.
4Create a Payment
Creating a payment is the core API operation. It initiates a Mobile Money transaction by sending a request with the payment information: amount, currency, operator, payer's phone number, and callback URL for webhook notifications. The API immediately returns a payment object with a unique identifier and initial status.
const payment = await client.payments.create({
amount: 5000,
currency: 'XOF',
provider: 'orange_money',
phone: '+2250701234567',
description: 'Order #12345',
callback_url: 'https://yoursite.com/webhook',
metadata: {
order_id: '12345',
customer_email: 'client@example.com'
}
});
console.log(payment.id); // 'pay_xxxxxxxxxxxxxxxx'
console.log(payment.status); // 'pending'The provider field accepts the following values: mtn_momo, orange_money, wave, moov_money, and airtel_money. If you don't know the customer's operator, you can omit this field and ElyonPay will automatically determine it from the phone number. The metadata field is optional but strongly recommended: it allows you to associate business data with the transaction for easier reconciliation.
Once the request is sent, the customer receives a USSD or push notification on their phone to validate the payment. The transaction status changes from pending to completed or failed based on the user's response, and you are notified via the configured webhook.
5Handle Webhooks
Webhooks are the recommended mechanism for tracking payment status changes in real time. When a payment changes status (successful, failed, expired), ElyonPay sends an HTTP POST request to the callback URL you specified when creating the payment. Your server must process this notification and update the order status accordingly.
const express = require('express');
const app = express();
app.post('/webhook', express.json(), (req, res) => {
const signature = req.headers['x-elyonpay-signature'];
const isValid = client.webhooks.verify(req.body, signature);
if (!isValid) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = req.body;
switch (event.type) {
case 'payment.completed':
// Mark order as paid
updateOrder(event.data.metadata.order_id, 'paid');
break;
case 'payment.failed':
// Notify customer of failure
notifyCustomer(event.data.metadata.customer_email, 'failed');
break;
}
res.status(200).json({ received: true });
});Signature verification is a critical security step. Each webhook is signed with your webhook secret key (available in the dashboard), and the client.webhooks.verify() method validates that the request genuinely comes from ElyonPay and has not been tampered with in transit. Never process a webhook without verifying its signature.
Your webhook endpoint must respond with an HTTP 200 status code within 5 seconds. If the response is different or the timeout is exceeded, ElyonPay considers delivery failed and retries up to 5 times with increasing intervals (1 min, 5 min, 30 min, 2 h, 24 h). Make sure your webhook processing is idempotent to correctly handle potential multiple deliveries.
6Handle Errors
The ElyonPay API uses standard HTTP error codes combined with specific error codes to help you identify and handle issues effectively. Robust error handling is essential to provide a smooth user experience, even when things don't go as planned.
try {
const payment = await client.payments.create({
amount: 5000,
currency: 'XOF',
provider: 'orange_money',
phone: '+2250701234567'
});
} catch (error) {
if (error.type === 'invalid_request') {
// Missing or invalid parameter
console.error('Validation error:', error.message);
} else if (error.type === 'provider_error') {
// Error from Mobile Money operator
console.error('Operator error:', error.provider_code);
} else if (error.type === 'network_error') {
// Connectivity issue
console.error('Network error, please retry later');
} else if (error.type === 'authentication_error') {
// Invalid or expired API key
console.error('Check your API key');
}
}Errors of type provider_error deserve special attention as they come directly from Mobile Money operators. The most common codes are insufficient_balance (insufficient balance), invalid_number (invalid phone number), user_cancelled (payment cancelled by user), and timeout (user didn't validate within the allotted time).
For each error type, adapt the message displayed to the end user. A clear, actionable message — "Your Orange Money balance is insufficient, please top up your account" — is infinitely more useful than a generic technical message. Also implement a server-side logging system to monitor recurring errors and detect anomalies.
7Go to Production
Once your integration is tested and validated in sandbox, going to production requires a few simple but important adjustments. The first step is to replace your sandbox API key with your production key, and update the API base URL. Make sure your production server uses HTTPS for all communications with the API and for receiving webhooks.
const client = new ElyonPay({
apiKey: process.env.ELYONPAY_PRODUCTION_KEY,
environment: 'production',
timeout: 30000,
retries: 3
});
// Verify connection
const status = await client.health.check();
console.log('API Status:', status.environment); // 'production'Before processing real transactions, perform a complete configuration check. Ensure your webhook endpoint is publicly accessible and responds correctly, your production keys are securely stored in environment variables, and your code correctly handles all documented error types. Make a first transaction with a small amount to validate the complete end-to-end flow.
Production checklist: production API key configured, HTTPS enabled on server, webhook accessible and verified, error handling implemented, monitoring logs in place, first test transaction successful, support team informed. Once all these points are validated, your integration is ready to process real payments.
ElyonPay also provides a real-time monitoring dashboard that lets you track transaction success rates, API response times, and any errors. Set up alerts to be notified immediately in case of performance degradation or recurring errors, so you can react quickly and maintain an optimal experience for your users.
Conclusion
By following this guide, you have integrated the ElyonPay API in JavaScript from end to end: SDK installation, client initialization, payment creation, webhook handling, and error management. Your application is now ready to accept Mobile Money payments across 14 African countries. Check our complete documentation at docs.elyonpay.com to discover advanced features like recurring payments, refunds, and payouts.
Get started with ElyonPay
Accept Mobile Money and card payments in minutes.
Create your free account