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.

---