refactored notificatoin / tgsettle responsibility boundaries

api/proto/common/gateway/v1/gateway.proto

@@ -7,7 +7,8 @@ option go_package = "github.com/tech/sendico/pkg/proto/common/gateway/v1;gateway
 import "api/proto/common/money/v1/money.proto";
 import "api/proto/payments/endpoint/v1/endpoint.proto";
 
-
+// Operation enumerates gateway-level operations that can be performed on a
+// payment method.
 enum Operation {
   OPERATION_UNSPECIFIED     = 0;
   OPERATION_AUTHORIZE       = 1;
@@ -126,6 +127,7 @@ message RailCapabilities {
   bool can_release = 7;
 }
 
+// LimitsOverride provides per-currency overrides for global limit settings.
 message LimitsOverride {
   string max_volume = 1;
   string min_amount = 2;
@@ -166,6 +168,7 @@ enum OperationResult {
   OPERATION_RESULT_CANCELLED   = 3;
 }
 
+// OperationError describes a failure returned by a gateway operation.
 message OperationError {
   string code            = 1;
   string message         = 2;
@@ -173,6 +176,8 @@ message OperationError {
   bool should_rollback  = 4;
 }
 
+// OperationExecutionStatus reports the result of executing a single gateway
+// operation, including the settled amount and any error.
 message OperationExecutionStatus {
   string idempotency_key = 1;
   string operation_ref   = 2;

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

api/proto/common/payment/v1/custom.proto

@@ -4,8 +4,11 @@ package common.payment.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
 
-
+// CustomPaymentDetails carries an opaque, gateway-specific payment method
+// encoded as JSON bytes.
 message CustomPaymentDetails {
+  // id is the unique identifier for this payment method instance.
   string id = 1;
+  // payment_method_json is the raw JSON payload understood by the target gateway.
   bytes payment_method_json = 2;
-}
+}

api/proto/common/payment/v1/external_chain.proto

@@ -6,11 +6,15 @@ option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;payment
 
 import "api/proto/gateway/chain/v1/chain.proto";
 
-
+// ExternalChainDetails describes an external blockchain address as a
+// payment endpoint.
 message ExternalChainDetails {
+  // id is the unique identifier for this endpoint instance.
   string id = 1;
+  // asset identifies the on-chain token (network + symbol + contract).
   chain.gateway.v1.Asset asset = 2;
+  // address is the destination blockchain address.
   string address = 3;
+  // memo is an optional transfer memo or tag required by some chains.
   string memo = 4;
 }
-

api/proto/common/payment/v1/ledger.proto

@@ -4,11 +4,14 @@ package common.payment.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
 
-
+// LedgerDetails identifies an internal ledger account as a payment endpoint.
 message LedgerDetails {
+  // id is the unique identifier for this endpoint instance.
   string id = 1;
   oneof source {
+    // ledger_account_ref is the direct ledger account reference.
     string ledger_account_ref = 2;
+    // account_code is a human-readable account code resolved at runtime.
     string account_code = 3;
   }
 }

api/proto/common/payment/v1/managed_wallet.proto

@@ -4,8 +4,11 @@ package common.payment.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
 
-
+// ManagedWalletDetails identifies a platform-managed blockchain wallet as a
+// payment endpoint.
 message ManagedWalletDetails {
+  // id is the unique identifier for this endpoint instance.
   string id = 1;
+  // managed_wallet_ref is the reference to the managed wallet record.
   string managed_wallet_ref = 2;
-}
+}

api/proto/common/payment/v1/rba.proto

@@ -4,13 +4,15 @@ package common.payment.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
 
-// -------------------------
-// Russian bank account details
-// -------------------------
-
+// RussianBankDetails carries Russian domestic bank account information for
+// RUB payouts.
 message RussianBankDetails {
+  // id is the unique identifier for this endpoint instance.
   string id = 1;
-  string account_number = 2; // 20 digits
-  string bik = 3; // 9 digits
+  // account_number is the 20-digit Russian bank account number.
+  string account_number = 2;
+  // bik is the 9-digit Russian bank identification code.
+  string bik = 3;
+  // account_holder_name is the full name of the account holder.
   string account_holder_name = 4;
 }

api/proto/common/payment/v1/sepa.proto

@@ -4,14 +4,14 @@ package common.payment.v1;
 
 option go_package = "github.com/tech/sendico/pkg/proto/common/payment/v1;paymentv1";
 
-// -------------------------
-// SEPA bank account details
-// -------------------------
-
+// SepaBankDetails carries SEPA bank account information for EUR transfers.
 message SepaBankDetails {
+  // id is the unique identifier for this endpoint instance.
   string id = 1;
-  string iban = 2; // IBAN
-  string bic = 3; // optional (BIC/SWIFT)
+  // iban is the International Bank Account Number.
+  string iban = 2;
+  // bic is the optional BIC/SWIFT code.
+  string bic = 3;
+  // account_holder_name is the full name of the account holder.
   string account_holder_name = 4;
 }
-

api/proto/common/storable/v1/storable.proto

@@ -7,6 +7,7 @@ option go_package = "github.com/tech/sendico/pkg/proto/common/storable/v1;storab
 import "google/protobuf/timestamp.proto";
 
 
+// Storable carries common persistence metadata (ID and timestamps).
 message Storable {
   string id = 1;
   google.protobuf.Timestamp created_at = 10;