.. meta::
    :description: Essential security practices for Node.js payment integrations, including Idempotency Keys and HMAC verification.
    :keywords: Node.js Payment Security, Idempotency Keys, HMAC Verification, Careem Pay Security, API Credential Protection
    :author: Muayed

================================================================
Node.js Payment Security & Idempotency for Careem Pay
================================================================

When handling financial transactions via the Careem Pay Merchant API, security cannot be an afterthought. A compromised API key or an unverified webhook can lead to significant financial loss. This guide details the essential security measures every Node.js developer must implement to protect their marketplace.

1. Protecting Credentials with `.env`
=====================================

Never hardcode your `CLIENT_ID` or `CLIENT_SECRET` in your source code. These values should be injected via environment variables.

- **Use the `dotenv` package:** Ensure `dotenv` is configured at the very top of your application entry point.
- **Ignore the `.env` file:** Verify that `.env` is listed in your `.gitignore` file to prevent accidental commits to public repositories.

.. code-block:: javascript

   require('dotenv').config();
   const careemClientId = process.env.CLIENT_ID;
   const careemClientSecret = process.env.CLIENT_SECRET;

2. Preventing Duplicate Charges: Idempotency Keys
=================================================

Network timeouts are common in mobile environments. A user might tap "Pay" twice if the app seems unresponsive, causing your server to send two identical payment requests to Careem Pay.

To prevent double-charging the customer, use an **Idempotency Key**.

What is an Idempotency Key?
---------------------------
It is a unique identifier generated by your server for a specific transaction attempt. When you send a request to Careem Pay with this key, the Careem system remembers it. If Careem receives a second request with the exact same Idempotency Key, it will ignore the second request and return the result of the first one.

Implementing Idempotency in Node.js:
------------------------------------

Generate a standard UUID (v4) for every unique checkout session.

.. code-block:: javascript

   const { v4: uuidv4 } = require('uuid');
   const axios = require('axios');

   async function processPayment(orderDetails) {
       const idempotencyKey = uuidv4(); // Generate unique key

       try {
           const response = await axios.post('https://api.careem.com/process-payment', orderDetails, {
               headers: {
                   'Authorization': `Bearer ${accessToken}`,
                   'Idempotency-Key': idempotencyKey
               }
           });
           return response.data;
       } catch (error) {
           console.error("Payment failed", error);
       }
   }

3. Verifying Webhook Authenticity (HMAC Signatures)
===================================================

If you followed the :doc:`webhook-integration` guide, you have a public endpoint listening for updates. You must ensure that only Careem Pay can trigger this endpoint. Malicious actors could send fake "PAYMENT_SUCCESS" requests to mark unpaid orders as paid.

Careem Pay secures webhooks by signing the payload with an **HMAC (Hash-based Message Authentication Code)** using your Client Secret. This signature is sent in the HTTP headers.

How to Verify the Signature in Node.js:
---------------------------------------

You must calculate the HMAC signature of the incoming request body using your secret key and compare it to the signature provided in the headers.

.. code-block:: javascript

   const crypto = require('crypto');

   function verifyCareemWebhook(req, res, next) {
       const signatureHeader = req.headers['x-careem-signature'];
       const payload = JSON.stringify(req.body);
       const secret = process.env.CLIENT_SECRET;

       // Create the HMAC hash
       const hash = crypto.createHmac('sha256', secret)
                          .update(payload)
                          .digest('hex');

       // Compare securely to prevent timing attacks
       if (crypto.timingSafeEqual(Buffer.from(hash), Buffer.from(signatureHeader))) {
           next(); // Signature is valid, proceed
       } else {
           res.status(401).send('Invalid Webhook Signature');
       }
   }

   // Apply the middleware to your webhook route
   app.post('/careem-pay/webhook', express.json(), verifyCareemWebhook, (req, res) => {
       // Handle the verified event
   });

Conclusion
==========

By strictly managing environment variables, utilizing Idempotency Keys, and mathematically verifying incoming webhooks via HMAC, you fortify your Node.js application against the most common e-commerce vulnerabilities. These practices ensure a secure, reliable environment for both your business and your users.