PayeeConfig Encryption & Key Rotation (Internal)

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.

Keys are stored in Azure Key Vault (never in source code or app config). Each encrypted payee record also stores the Key Vault secret version used to encrypt it, enabling zero-downtime key rotation.

---

Data Model

Where the encrypted data lives

Payee configs are stored on the merchant aggregate:

• VendorMerchant.payeeConfigs (type: PayeeConfigs, from wallet-event-commons)
  • defaultPayeeId
  • payees: List<PayeeConfig>

Sensitive payload is stored per payee in:

• PayeeConfig.encryptedPayeeDetails (ciphertext or legacy plaintext)
• PayeeConfig.keyVersion (Key Vault secret version)

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	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)

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.

---