Webhook Integration for Asynchronous Careem Pay Transactions

When integrating the Careem Pay Merchant API, relying solely on synchronous HTTP responses can lead to missed updates if a user closes their browser or a network timeout occurs. To build a robust and reliable payment flow, merchants must implement Webhooks to handle asynchronous payment confirmations.

What is a Webhook?

A webhook is an HTTP callback. Instead of your Node.js server continuously polling the Careem Pay API for a transaction status, Careem Pay automatically sends a POST request to your server when an event occurs (e.g., payment success, refund failure).

Why Webhooks are Critical for E-Commerce

Reliability: Captures successful payments even if the user drops off the confirmation page.
Efficiency: Eliminates the need for resource-intensive polling mechanisms.
Real-Time Updates: Instantly updates order status in your database, allowing for immediate fulfillment.

Setting Up Your Node.js Webhook Endpoint

To receive webhooks, you need to expose a public, unauthenticated endpoint on your server. However, this endpoint must securely verify that the incoming request actually originated from Careem Pay.

Step 1: Create the Route

In your Express.js application, create a POST route to listen for incoming events.

const express = require('express');
const app = express();

// Webhook route
app.post('/careem-pay/webhook', express.json(), (req, res) => {
    const event = req.body;

    // Acknowledge receipt of the webhook immediately
    res.status(200).send('Webhook Received');

    // Process the event asynchronously
    handleCareemEvent(event);
});

Step 2: Processing the Event Payload

The Careem Pay webhook payload typically contains the transaction_id, the event type, and the current status.

function handleCareemEvent(event) {
    switch (event.type) {
        case 'PAYMENT_SUCCESS':
            console.log(`Payment successful for transaction: ${event.transaction_id}`);
            // TODO: Update order status to 'Paid' in your database
            // TODO: Trigger fulfillment or email receipt
            break;
        case 'PAYMENT_FAILED':
            console.log(`Payment failed for transaction: ${event.transaction_id}`);
            // TODO: Notify the user and prompt for an alternative payment method
            break;
        case 'REFUND_PROCESSED':
            console.log(`Refund completed for transaction: ${event.transaction_id}`);
            // TODO: Update order status to 'Refunded'
            break;
        default:
            console.log(`Unhandled event type: ${event.type}`);
    }
}

Best Practices for Webhook Reliability

To ensure your system remains resilient and passes Google’s technical integration standards, follow these best practices:

Respond Quickly (200 OK) Always return a 200 OK status back to Careem Pay immediately, before processing the business logic. If your server takes too long to respond, Careem Pay may assume the webhook failed and attempt to resend it.
Handle Duplicate Webhooks Due to network retries, your server might receive the same webhook event more than once. Always check your database to see if the transaction_id has already been processed before updating the order status.
Log Everything Maintain a detailed log of all incoming webhooks. If a customer disputes a charge or an order isn’t fulfilled, these logs are critical for troubleshooting.

Conclusion

Integrating webhooks is a non-negotiable requirement for a production-ready Careem Pay setup. By utilizing an asynchronous Node.js endpoint, you guarantee that your application remains perfectly synchronized with Careem’s payment gateway, providing a flawless experience for your users.

Next Steps

For information on how to secure this webhook endpoint against malicious actors, please review our guide on Node.js Payment Security & Idempotency for Careem Pay.