Best practices
Recommendations to follow for a robust, secure, and high-performance Wajub integration.
These best practices come from our experience with hundreds of production integrations. Following them will help you avoid the most common pitfalls and ensure a reliable payment experience for your customers.
The pillars of a solid integration
- Idempotency — avoid duplicate charges and duplicate processing.
- Error handling — anticipate network failures, timeouts, and declines.
- Security — protect your keys, verify signatures, stay compliant.
- Performance — paginate correctly, optimize your calls, manage concurrency.
Apply from development
These practices are easier to integrate from the start than to add after a production incident. Include them in your definition of done.
Rule #1: fulfill only on server confirmation
Never deliver a product or service based solely on the browser return. Always confirm
via webhook or server-side API verification that the status is succeeded.
Rule #2: always verify webhook signatures
A webhook endpoint without signature verification is an open door to fraudulent requests.
Use constructEvent (or the equivalent) from your SDK before any processing.
Rule #3: log everything
Record every interaction with the Wajub API: requests, responses, received webhooks, errors. These logs are your first line of defense to diagnose a problem.
const logPayment = (reference, event, data) => {
console.log(JSON.stringify({
timestamp: new Date().toISOString(),
reference,
event,
data,
environment: process.env.NODE_ENV,
}));
};
// At each lifecycle step
logPayment(orderId, 'payment.initialized', { trx: transaction.reference });
logPayment(orderId, 'webhook.received', { type: event.type, id: event.id });
logPayment(orderId, 'fulfillment.complete', { status: 'shipped' });