API key security: best practices for payment integrations

API key security comes down to four habits: keep secret keys out of code and browsers, give each key only the access it needs, rotate keys on a schedule and whenever someone with access leaves, and have a rehearsed plan for when a key leaks. For payment integrations this matters more than usual, because a secret key can often create charges, issue refunds or read customer data.

Below is a practical set of controls for South African development teams, from small agencies to in-house finance engineering.

What a payment API key can do in the wrong hands

Depending on the provider and the key's permissions, an exposed secret key may allow someone to:

• read customer names, email addresses and transaction history;
• create payment links or invoices that look legitimate;
• issue refunds;
• change webhook endpoints so your system stops hearing about payments;
• create further keys, making clean-up harder.

Some of that is also a personal information security issue under POPIA. If a compromise exposes customer data, section 22 requires notifying the Information Regulator and affected data subjects as soon as reasonably possible; see our POPIA payment data guide.

Publishable vs secret keys

Many payment providers issue two kinds of key:

The rule is simple: a secret key must never reach a browser, mobile app, public repository or client-side bundle. If your front end needs to start a payment, have it call your server, which then calls the provider with the secret key.

Storing keys safely

Use environment variables or a secrets manager

Load keys at runtime from environment variables or, better, a secrets manager provided by your cloud platform or a dedicated vault product. This keeps them out of source control and lets you rotate without redeploying code.

// Read the key at startup and fail fast if it's missing.
const apiKey = process.env.PAYMENTS_API_KEY;
if (!apiKey) {
  throw new Error("PAYMENTS_API_KEY is not set");
}

Never commit keys

• Add .env files to .gitignore before the first commit.
• Turn on secret scanning in your Git hosting platform where available, and add a pre-commit hook that blocks obvious key patterns.
• Remember that deleting a key from the latest commit doesn't remove it from history. If it was ever pushed, treat it as leaked.

Keep keys out of logs and tickets

Redact authorisation headers in request logging, error trackers and APM tools. Don't paste keys into support tickets, chat messages or shared documents.

Least privilege

Give every integration its own key, scoped as narrowly as the provider allows:

• One key per system. Your website checkout, accounting sync and reporting script should each have their own key. When one leaks, you revoke only that one.
• Separate environments. Sandbox keys in development and testing; production keys only in production.
• Restrict who can create keys. Only a small number of administrators should be able to view or generate production keys. Use roles in the provider's dashboard and require two-factor authentication for those users; see authenticator app 2FA.
• Use IP allow-listing if the provider offers it and your servers have stable addresses.

Rotating keys

Rotation limits how long a quietly leaked key stays useful. A low-drama process:

1. Create a new key alongside the old one.
2. Update the secret in your secrets manager or environment.
3. Deploy or restart the services that use it.
4. Confirm traffic is using the new key (check the provider's logs or your own).
5. Revoke the old key.

Rotate on a schedule that suits your risk (for example quarterly), and always when a developer, contractor or agency with access leaves the project.

When a key leaks: the first hour

Speed matters more than perfection. Work through this list:

1. Revoke or roll the key immediately in the provider's dashboard, even if it will cause a brief outage.
2. Issue a replacement and deploy it to the affected service.
3. Check activity in the provider's logs from the moment the key could have been exposed: refunds, new payment links, changed webhook URLs, new keys, data exports.
4. Undo malicious changes, such as altered webhook endpoints or unexpected refunds, and contact the provider's support.
5. Find the source: public repo, log file, laptop, third-party tool.
6. Assess personal information exposure and decide with your information officer whether POPIA notification applies.
7. Write a short post-incident note and fix the process gap that allowed the leak.

A quick API key security checklist

• Secret keys only on servers, never in front-end code
• Keys stored in a secrets manager or environment variables
• Secret scanning and pre-commit checks enabled
• One key per integration, separate per environment
• Key management restricted to a few admins with 2FA
• Authorisation headers redacted from logs
• Rotation schedule documented and followed
• Leak response steps written down and known by the team

How CentraPoint helps

CentraPoint's REST API authenticates with API keys that you manage from the dashboard, and roles and permissions (admin, staff, viewer and custom roles) let you control who can manage them. Team members can be protected with authenticator-app (TOTP) two-factor authentication, audit logs record account activity, and the gateway credentials you connect are encrypted at rest with AES-256-GCM. See the developers page for an overview.

Frequently asked questions

Where should I store payment API keys?

On your servers only, loaded from environment variables or a secrets manager. Never in source code, front-end bundles, mobile apps or shared documents.

How often should API keys be rotated?

Choose a regular schedule that fits your risk, such as quarterly, and always rotate when someone with access leaves or you suspect exposure.

What should I do if I committed an API key to GitHub?

Revoke it immediately and issue a new one, even if you've deleted the commit. Assume it has been copied, then review the provider's logs for misuse.

Is it safe to use a secret key in a mobile app?

No. Anything shipped in an app can be extracted. Have the app call your server, which uses the secret key on its behalf.