PayeeConfig Encryption

Overview

Payee configuration data (address, tax ID, patient account number, payer 835 ID, etc.) contains sensitive PII/PHI. To protect this data at rest, Convenient Checkout encrypts the serialized payee details using AES-256-GCM before persisting them in the database. The encryption key is stored in Azure Key Vault, never in source code or application configuration.

---

Data Model

PayeeConfig (wallet-event-commons)

Stored per-payee on VendorMerchant.payeeConfigs.

Field	Type	Description
payeeId	UUID	Unique identifier for the payee entry.
encryptedPayeeDetails	String	AES-256-GCM ciphertext prefixed with enc:v1:, or legacy plain text for pre-encryption rows.
keyVersion	String	The Azure Key Vault secret version used to encrypt this row; required for decryption.

PayeeConfigs (wallet-event-commons)

Top-level container stored on VendorMerchant.

Field	Type	Description
defaultPayeeId	UUID	The payee used by default when none is specified on a payment.
payees	List<PayeeConfig>	All payee entries for this vendor-merchant.

PayeeConfigDTO (wallet-merchant-service)

The inbound API representation validated before encryption.

Field	Constraints	Description
payeeName	Required, max 35 chars, [A-Za-z0-9 !@#$%&()_+=\-;\",'./?]	Payee name.
payeeAddressLine1	Required, max 30 chars, [A-Za-z0-9 !@#$%&()_+=\-;\",'./?]	Street address line 1.
payeeAddressLine2	Optional	Street address line 2.
payeeCity	Required, max 24 chars, letters & spaces only	City.
payeeState	Required, max 2 chars, letters only	US state code.
payeeZip	Required, max 10 chars, alphanumeric	ZIP / postal code.
payeeCountry	Required	Country code.
payeePatientAccountNumber	Required, max 38 chars	Patient account number used in payment routing.
payeeTaxId	Required, max 15 chars, alphanumeric	Payee tax identifier.
payer835Id	Required, max 5 chars, alphanumeric	835 payer ID used for claim routing.

---

🔒 InternalInternal information — not visible in the public (merchant) site.

Architecture

                    ┌──────────────────────────────────────┐
                    │       wallet-merchant-service        │
                    │                                      │
  Merchant API ───► │  MerchantService                     │
  (PayeeConfigDTO)  │    └─ PayeeConfigEncryptionHelper    │
                    │         └─ PayeeEncryptionService    │◄──── Azure Key Vault
                    │              (Spring @Service)       │      (secret: payee-encryption-key)
                    └──────────────────┬───────────────────┘
                                       │ MerchantEvent (encrypted PayeeConfigs)
                                       ▼  (Kafka / Event Bus)
                    ┌──────────────────────────────────────┐
                    │       wallet-payment-service         │
                    │                                      │
                    │  MerchantConsumer                    │
                    │    └─ stores encrypted PayeeConfigs  │
                    │         in Merchant entity (DB)      │
                    │                                      │
                    │  CreateUserPaymentCommandHandler     │
                    │    └─ PayeeEncryptionService.decrypt │◄──── Azure Key Vault
                    └──────────────────────────────────────┘

              ─── wallet-event-commons (shared library) ───
                   PayeeEncryptionService  (core logic)
                   AesGcmUtils            (AES-256-GCM)
                   KeyVersionedSupplier   (KV abstraction)
                   PayeeConfig / PayeeConfigs (POJOs)

---

Key Components

PayeeEncryptionService (wallet-event-commons — framework-agnostic core)

Located at com.optum.wallet.common.util.payment.vendor.crypto.PayeeEncryptionService.

Pure-Java library class with no Spring dependency. Both services wrap it with a thin @Service adapter that supplies the KeyVersionedSupplier from their own Azure Key Vault client.

Method	Description
encrypt(String plainPayeeDetails)	Encrypts the plain text using the current key version; returns a PayeeConfig with ciphertext prefixed enc:v1: and the keyVersion used.
decrypt(String storedValue, String keyVersion)	Decrypts an enc:v1: prefixed value with the specified key version. Returns the value unchanged for legacy plain-text rows (backward compatibility).
isEncrypted(String value)	Returns true if the value starts with enc:v1:.

Versioned-key design

Every encrypted row stores the keyVersion (Azure Key Vault secret version ID) alongside the ciphertext. On decryption the service fetches that specific version from Key Vault. This enables zero-downtime key rotation: new rows are encrypted with the new version; old rows remain decryptable as long as the old version exists in the vault.

Backward compatibility

Rows that pre-date encryption (plain-text encryptedPayeeDetails) are detected by the absence of the enc:v1: prefix and are returned as-is by decrypt(). No migration script is required; rows are re-encrypted lazily on the next write.

AesGcmUtils (wallet-event-commons)

Low-level utility that performs AES-256-GCM operations.

• Algorithm: AES/GCM/NoPadding
• IV: 12 random bytes generated per encryption via SecureRandom
• GCM tag: 128 bits
• Key size: exactly 256 bits (32 bytes); enforced at runtime
• Wire format: Base64( IV[12] || ciphertext+tag )

KeyVersionedSupplier (wallet-event-commons)

Interface that decouples the core encryption logic from any specific key-store SDK.

public interface KeyVersionedSupplier {
    /** Returns the Base64-encoded AES-256 key for the given version. */
    String getKey(String version);

    /** Returns the current (latest) version identifier from the key store. */
    String currentVersion();
}

Both services implement this anonymously using their KeyVaultClient.

---

Service Responsibilities

wallet-merchant-service

Responsibility: encrypt payee details on write.

1. Merchant API receives a VendorMerchant payload containing a PayeeConfigs object with plain-text encryptedPayeeDetails.
2. MerchantService delegates to PayeeConfigEncryptionHelper.encryptAll(PayeeConfigs).
3. PayeeConfigEncryptionHelper iterates each PayeeConfig:
   • Skips entries where details are blank.
   • Skips entries already prefixed with enc:v1: (idempotent re-saves).
   • Calls PayeeEncryptionService.encrypt(details) for all other entries.
4. The resulting encrypted PayeeConfigs is stored and published as a MerchantEvent.

Spring PayeeEncryptionService adapter (merchant-service) wires to Key Vault via:

• Secret name property: payment.payee.encryption.secret-name (default: payee-encryption-key)
• Strips trailing whitespace/newlines from Key Vault responses before Base64 decoding.

wallet-payment-service

Responsibility: store encrypted payee configs and decrypt on payment processing.

1. MerchantConsumer receives MerchantEvent and persists the PayeeConfigs (already encrypted) onto the Merchant entity — no decryption at this stage.
2. CreateUserPaymentCommandHandler decrypts payee details at payment-processing time by calling PayeeEncryptionService.decrypt(storedValue, keyVersion).

---

Key Vault Configuration

Property	Service	Default	Description
payment.payee.encryption.secret-name	merchant-service	payee-encryption-key	Name of the Key Vault secret holding the AES-256 key.
payment.payee.encryption.secret-name	payment-service	payee-encryption-key	Same secret name; each service has its own Key Vault client.

Secret format

The Key Vault secret value must be a Base64-encoded 256-bit (32-byte) AES key, e.g.:

# Generate a suitable key:
openssl rand -base64 32

Store the output directly as the secret value. The service automatically strips leading/trailing whitespace.

Local development

For local development profiles (LocalKeyVaultClient), a static Base64 key is supplied by implementing KeyVersionedSupplier with fixed values:

KeyVersionedSupplier localSupplier = new KeyVersionedSupplier() {
    @Override
    public String getKey(String version) { return localBase64Key; }

    @Override
    public String currentVersion() { return "local"; }
};
new com.optum.wallet.common.util.payment.vendor.crypto.PayeeEncryptionService(localSupplier);

This means encryption/decryption still works end-to-end locally without a real Key Vault connection.

---

Sequence: Merchant Save (Encrypt)

Client → MerchantController
           → MerchantService.saveMerchant(vendorMerchant)
               → PayeeConfigEncryptionHelper.encryptAll(payeeConfigs)
                   → [for each PayeeConfig]
                       → PayeeEncryptionService.isEncrypted(details) → false
                       → PayeeEncryptionService.encrypt(details)
                           → KeyVaultClient.getCurrentSecretVersion()  → version
                           → KeyVaultClient.getSecretValue(name, version) → base64Key
                           → AesGcmUtils.encrypt(details, aesKey) → ciphertext
                           → return PayeeConfig(enc:v1:<ciphertext>, version)
               → save encrypted VendorMerchant
               → publish MerchantEvent (encrypted)

Sequence: Payment Processing (Decrypt)

PaymentCommand → CreateUserPaymentCommandHandler
                   → merchantRepository.findMerchant(...)
                   → PayeeEncryptionService.decrypt(encryptedPayeeDetails, keyVersion)
                       → isEncrypted? → yes (enc:v1: prefix)
                       → KeyVaultClient.getSecretValue(name, keyVersion) → base64Key
                       → AesGcmUtils.decrypt(cipherPayload, aesKey) → plainText
                   → use plain-text payee details for payment routing

---

Error Handling

All encryption/decryption failures are wrapped in PayeeCryptoException (unchecked). Common causes:

Cause	Exception message
Blank payee details on encrypt	"Payee details are empty"
Missing keyVersion for encrypted row	"Missing key version for encrypted payee details"
Key Vault returns empty/null key	"Encryption key is empty"
Key Vault key is not valid Base64	"Encryption key is not valid Base64"
Key is not 256-bit	"Invalid AES key length: N bytes"
JCE encryption failure	"Failed to encrypt payee details"
JCE decryption failure	"Failed to decrypt payee details"

---

Testing

• PayeeEncryptionServiceTest (commons, merchant-service, payment-service): unit tests covering encrypt/decrypt round-trips, legacy plain-text pass-through, blank-input guards, and invalid key detection.
• PayeeConfigEncryptionHelperTest (merchant-service): tests the idempotency guard (skip already-encrypted), null/blank skip, and full encryptAll list behaviour.