How Do API Authentication and Request Signatures Work?

Payment APIs move money, so proving who is calling them, and that the message has not been altered in transit, is non-negotiable. South African banks and payment providers typically layer several mechanisms: transport security, caller authentication and message-level signatures.

Understanding what each layer protects against helps you implement them correctly and troubleshoot failures such as expired tokens, certificate mismatches and signature errors.

What authentication methods do payment APIs use?

API keys

A static secret issued per merchant and environment, sent with each request. Simple to implement, but the key is long-lived, so it must be stored in a secrets manager, never committed to source control, and rotated on a schedule. Keys for sandbox and production must never be interchangeable; see sandbox, UAT and production.

OAuth 2.0 client credentials

Your system authenticates with a client ID and secret to obtain a short-lived access token, then presents the token on API calls. This is the dominant pattern for bank corporate APIs. Practical points:

• Cache tokens and refresh before expiry rather than requesting a new token per call.
• Handle rejected-token responses by refreshing once and retrying, not by looping.
• Treat the client secret with the same care as an API key.

Mutual TLS (mTLS)

Standard TLS proves the server's identity to you; mutual TLS also proves your identity to the server using a client certificate. Banks commonly require mTLS for host-to-host channels and high-value APIs. Certificates expire, so track expiry dates and renew ahead of time; an expired client certificate is a classic cause of sudden total integration failure.

What do request signatures add?

Transport security protects data in transit, but it does not prove that the message body itself is authentic and unmodified end to end. Message signatures close that gap:

• The sender computes a signature over the request body (and often selected headers and a timestamp) using a shared secret (HMAC) or a private key (asymmetric signing).
• The receiver recomputes or verifies the signature before trusting the payload.
• A timestamp inside the signed content lets the receiver reject stale messages, defending against replay attacks where an old, valid request is resent.

Signatures matter in both directions: providers verify your signed instructions, and you must verify the signatures on inbound webhooks and callbacks before acting on them. Always verify against the raw request body exactly as received; re-serialising JSON before verification is a common cause of spurious signature failures.

How do these layers fit together?

High-assurance integrations use all three. The cryptographic building blocks are explained in tokenisation, encryption and hashing.

How should you manage credentials operationally?

• Store secrets and private keys in a secrets manager with restricted access, and log access to them.
• Use separate credentials per environment and per system, so a leaked credential has a small blast radius.
• Rotate keys, secrets and certificates on a schedule, and rehearse rotation so it is routine rather than risky.
• Monitor authentication failures: a spike can indicate an expired credential, a clock-drift problem breaking timestamp validation, or an attack.
• Revoke immediately on suspicion of compromise and follow your payment incident response process.

Common authentication failures and causes

• 401 or invalid token: expired or wrongly scoped OAuth token, or wrong environment credentials.
• TLS handshake failure: expired or untrusted client certificate, or unsupported TLS version.
• Signature mismatch: body modified by middleware, wrong key version, or re-serialised payload.
• Replay rejection: server clock drift pushing timestamps outside the allowed window.

Back to the Payment Operations hub.