Deploy your new key to all services first, then rotate on the Paystack dashboard. If you have multiple services, use a dual-key verification approach where your code tries the new key and falls back to the old one during the transition window. Always rotate during low-traffic hours and verify with a test transaction immediately after.
Key rotation is not something you do casually. It involves coordination, potential downtime risk, and verification. Rotate when you have a genuine reason:
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.
Get weekly developer tips
Join 25,000+ developers. Practical guides, job tips, and new content — straight to your inbox.
No spam. Unsubscribe anytime.
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.
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.
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();
}
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:
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:
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.
KES 2,999
The definitive guide to building payment systems with Paystack — from your first transaction to production-grade payment infrastructure across Africa. 9 modules, 47 lessons. Free preview available.
Start Paystack Course