Skip to main content

0046: Payment Gateway Secure Credential Management

Date: 2025-11-08

Status: Proposed

Context​

The payment-gateway-service needs to authenticate with various third-party payment providers (e.g., Stripe, PayPal). This requires storing and using highly sensitive credentials, such as API keys and secret tokens.

Storing these secrets directly in the service's source code, configuration files, or environment variables is a major security risk. It makes secret rotation difficult, increases the risk of accidental exposure, and violates security best practices.

We need a secure, centralized, and auditable method for managing these credentials.

Decision​

All secrets and credentials for third-party payment providers will be managed by the platform's central secret management system (e.g., HashiCorp Vault).

  1. No Secrets in Code/Config: Credentials must not be stored in source code, configuration files, or environment variables.
  2. Runtime Retrieval: The payment-gateway-service will retrieve the necessary secrets from the central secret management system at startup or runtime. It will use a standard client library provided by our platform commons.

Consequences​

Positive​

  • Enhanced Security: Secrets are encrypted at rest, access is tightly controlled and auditable, and the risk of accidental leakage is significantly reduced.
  • Centralized Management: All secrets are managed in one place, simplifying operations like secret rotation and auditing.
  • Consistency: This approach aligns with the platform-wide strategy for managing all sensitive information.

Negative​

  • Runtime Dependency: The service has a runtime dependency on the secret management system. If the secret store is unavailable at startup, the service may fail to initialize its payment provider adapters. This is an acceptable trade-off for the security benefits.