refactored notificatoin / tgsettle responsibility boundaries

api/proto/common/payment/v1/card.proto

@@ -4,10 +4,7 @@ package common.payment.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
 
-
-// -------------------------
-// Card network (payment system)
-// -------------------------
+// CardNetwork identifies a card payment network (scheme).
 enum CardNetwork {
   CARD_NETWORK_UNSPECIFIED = 0;
   CARD_NETWORK_VISA = 1;
@@ -19,6 +16,7 @@ enum CardNetwork {
   CARD_NETWORK_DISCOVER = 7;
 }
 
+// CardFundingType classifies the funding source behind a card.
 enum CardFundingType {
   CARD_FUNDING_UNSPECIFIED = 0;
   CARD_FUNDING_DEBIT = 1;
@@ -26,10 +24,8 @@ enum CardFundingType {
   CARD_FUNDING_PREPAID = 3;
 }
 
-// -------------------------
-// PCI scope: raw card details
-// -------------------------
-
+// RawCardData carries PCI-scope card credentials for tokenisation or
+// direct processing.
 message RawCardData {
   string pan = 1;
   uint32 exp_month = 2; // 1–12
@@ -37,10 +33,8 @@ message RawCardData {
   string cvv = 4; // optional; often omitted for payouts
 }
 
-
-// -------------------------
-// Safe metadata (display / routing hints)
-// -------------------------
+// CardMetadata holds non-sensitive display and routing hints derived from
+// card details.
 message CardMetadata {
   string masked_pan = 1; // e.g. 411111******1111
   CardNetwork network = 2; // Visa/Mastercard/Mir/...
@@ -49,11 +43,8 @@ message CardMetadata {
   string issuer_name = 5; // display only (if known)
 }
 
-
-// -------------------------
-// Card details
-// Either inline credentials OR reference to stored payment method
-// -------------------------
+// CardDetails provides card credentials for a payment operation, either
+// as inline raw data or a reference to a stored payment method.
 message CardDetails {
   string id = 1;
 
@@ -67,5 +58,3 @@ message CardDetails {
 
   string billing_country = 6; // ISO 3166-1 alpha-2, if you need it per operation
 }
-
-