Rotating Paystack Secret Keys Without Downtime

Key rotation is not something you do casually. It involves coordination, potential downtime risk, and verification. Rotate when you have a genuine reason:

• A team member with key access leaves. Anyone who had access to the Paystack dashboard or your environment variables could have copied the key.
• A suspected or confirmed leak. The key appeared in a git commit, a log file, a Slack message, or any other place it should not be. See what to do if your Paystack secret key leaked.
• Periodic rotation policy. Fintech companies and regulated businesses often require key rotation every 90 days regardless of incidents.
• Infrastructure migration. Moving to a new hosting provider or restructuring your services is a good time to rotate.

Do not rotate just because you can. Each rotation carries risk. But when any of the above conditions apply, rotate promptly.

Paystack key rotation works like this: you click "Generate New Keys" on the dashboard, and the old keys stop working immediately. The new keys are active from that moment.

This creates a timing problem. Between the moment you generate new keys and the moment your server starts using them, your server is sending requests with an invalid key. Every API call during that window fails with a 401 Unauthorized error. That means failed payment verifications, failed transaction initializations, and failed webhook signature checks.

The window can be as short as a few seconds (if you update an environment variable and your platform auto-restarts) or as long as several minutes (if you need to update multiple services, run a deployment pipeline, and wait for containers to restart).

The strategies below minimize or eliminate this window.

If your Paystack integration runs as a single service (one server, one deployment), the simplest approach is to pre-stage the new key and swap it at the same time you rotate on the dashboard.

Step-by-Step

1. Generate the new keys on the Paystack dashboard. Copy them immediately.
2. Update the environment variable on your hosting platform with the new key value.
3. Trigger a deployment or restart the service.
4. Once the new deployment is live, verify with a test transaction.

The window of downtime is the time between step 1 (when the old key is invalidated) and step 3 (when the new deployment is live). On platforms like Railway that auto-restart on variable changes, this can be under 30 seconds. On Vercel, a redeployment takes 30 to 90 seconds.

Minimizing the Window

Some developers prefer to reverse the order: update the environment variable with the new key value first, deploy, and then rotate on Paystack. But this does not work because you do not have the new key until you generate it on the dashboard, which simultaneously invalidates the old one.

The practical approach: schedule the rotation during your lowest traffic hour. For most African businesses, this is between 2 AM and 5 AM local time. The probability of a payment attempt during a 30-second window at 3 AM is very low.

If your architecture has multiple services that use the Paystack key (a web server, a webhook handler, a background worker), you cannot update them all simultaneously. The dual-key pattern handles this.

Add support for a secondary key in your configuration:

// config.js
var primaryKey = process.env.PAYSTACK_SECRET_KEY;
var fallbackKey = process.env.PAYSTACK_SECRET_KEY_OLD;

function getPaystackHeaders() {
  return {
    Authorization: 'Bearer ' + primaryKey,
    'Content-Type': 'application/json',
  };
}

function getFallbackHeaders() {
  if (!fallbackKey) return null;
  return {
    Authorization: 'Bearer ' + fallbackKey,
    'Content-Type': 'application/json',
  };
}

module.exports = { getPaystackHeaders, getFallbackHeaders };

In your API calls, try the primary key first and fall back:

var https = require('https');
var config = require('./config');

function verifyTransaction(reference, callback) {
  var headers = config.getPaystackHeaders();

  makeRequest(headers, reference, function(err, result) {
    if (err && err.statusCode === 401) {
      var fallback = config.getFallbackHeaders();
      if (fallback) {
        console.log('Primary key failed, trying fallback key');
        makeRequest(fallback, reference, callback);
        return;
      }
    }
    callback(err, result);
  });
}

function makeRequest(headers, reference, callback) {
  var options = {
    hostname: 'api.paystack.co',
    path: '/transaction/verify/' + reference,
    method: 'GET',
    headers: headers,
  };

  var req = https.request(options, function(res) {
    var data = '';
    res.on('data', function(chunk) { data += chunk; });
    res.on('end', function() {
      if (res.statusCode === 401) {
        callback({ statusCode: 401 }, null);
      } else {
        callback(null, JSON.parse(data));
      }
    });
  });
  req.end();
}

Rotation Sequence with Dual Keys

1. Deploy the dual-key code to all services (with only the primary key set)
2. Generate new keys on Paystack dashboard
3. Set PAYSTACK_SECRET_KEY to the new key and PAYSTACK_SECRET_KEY_OLD to the old key on all services
4. Deploy all services (they now try new key first, fall back to old)
5. Once all services are running with the new key, remove PAYSTACK_SECRET_KEY_OLD
6. Deploy again to clean up

This approach eliminates downtime because every service can use either key during the transition.

Your webhook handler uses the Paystack secret key to verify webhook signatures. When you rotate the secret key, the HMAC computation changes. Webhooks signed with the old key will fail verification if your handler only knows the new key.

This matters because Paystack may retry failed webhooks. A webhook that was sent and signed before rotation but retried after rotation will have a signature computed with the old key.

var crypto = require('crypto');

function verifyWebhookSignature(payload, signature) {
  var keys = [process.env.PAYSTACK_SECRET_KEY];

  // During rotation, also check the old key
  if (process.env.PAYSTACK_SECRET_KEY_OLD) {
    keys.push(process.env.PAYSTACK_SECRET_KEY_OLD);
  }

  for (var i = 0; i < keys.length; i++) {
    var hash = crypto
      .createHmac('sha512', keys[i])
      .update(JSON.stringify(payload))
      .digest('hex');

    if (hash === signature) {
      return true;
    }
  }

  return false;
}

Accept signatures from either key during the rotation window. After 48 hours (enough time for all webhook retries to complete), remove the old key and revert to single-key verification.

After rotating keys and deploying, verify everything works before going back to bed:

1. Transaction initialization. Start a test payment through your frontend. Confirm the checkout popup appears.
2. Transaction verification. Complete the test payment. Confirm your server successfully verifies it with the new key.
3. Webhook delivery. Check your webhook logs. Confirm the charge.success webhook arrived and passed signature verification.
4. API calls. If your application makes other API calls (list transactions, create transfers, manage subscriptions), test those too.
5. Error logs. Check your application logs for any 401 errors in the minutes following rotation.

If any step fails, the most likely cause is a service that still has the old key. Check all services and redeploy the ones that were missed.

Maintain a rotation log for compliance and incident response. Each entry should include:

• Date and time of rotation
• Reason for rotation (team change, suspected leak, periodic policy)
• Who performed the rotation
• Which environments were updated
• Verification results
• Duration of any downtime

Keep this log in a secure location (not in the git repository). A shared document in your team's password manager or a dedicated security log works well.

If your organization is subject to regulatory requirements (PCI DSS, NDPA, Kenya DPA), key rotation documentation may be required during audits. Having a clean log saves hours of investigation later.