unified gateway interface

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

@@ -26,6 +26,27 @@ enum PaymentMethodType {
   PM_LOCAL_BANK  = 7; // generic local rails, refine later if needed
 }
 
+// Rail identifiers for orchestration. Extend with new rails as needed.
+enum Rail {
+  RAIL_UNSPECIFIED = 0;
+  RAIL_CRYPTO = 1;
+  RAIL_PROVIDER_SETTLEMENT = 2;
+  RAIL_LEDGER = 3;
+  RAIL_CARD_PAYOUT = 4;
+  RAIL_FIAT_ONRAMP = 5;
+}
+
+// Operations supported in a payment plan.
+enum RailOperation {
+  RAIL_OPERATION_UNSPECIFIED = 0;
+  RAIL_OPERATION_DEBIT = 1;
+  RAIL_OPERATION_CREDIT = 2;
+  RAIL_OPERATION_SEND = 3;
+  RAIL_OPERATION_FEE = 4;
+  RAIL_OPERATION_OBSERVE_CONFIRM = 5;
+  RAIL_OPERATION_FX_CONVERT = 6;
+}
+
 // Limits in minor units, e.g. cents
 message AmountLimits {
   int64 min_minor = 1;
@@ -95,3 +116,44 @@ message GatewayDescriptor {
 
   GatewayCapabilities capabilities = 6;
 }
+
+// Capabilities declared per gateway instance for orchestration.
+message RailCapabilities {
+  bool can_pay_in = 1;
+  bool can_pay_out = 2;
+  bool can_read_balance = 3;
+  bool can_send_fee = 4;
+  bool requires_observe_confirm = 5;
+}
+
+message LimitsOverride {
+  string max_volume = 1;
+  string min_amount = 2;
+  string max_amount = 3;
+  string max_fee = 4;
+  int32 max_ops = 5;
+}
+
+// Limits are decimal-safe string amounts unless otherwise noted.
+message Limits {
+  string min_amount = 1;
+  string max_amount = 2;
+  string per_tx_max_fee = 3;
+  string per_tx_min_amount = 4;
+  string per_tx_max_amount = 5;
+  map<string, string> volume_limit = 6; // bucket -> max volume
+  map<string, int32> velocity_limit = 7; // bucket -> max operations count
+  map<string, LimitsOverride> currency_limits = 8;
+}
+
+// A specific gateway instance for a given rail/network pairing.
+message GatewayInstanceDescriptor {
+  string id = 1; // unique instance id
+  Rail rail = 2;
+  string network = 3;
+  repeated string currencies = 4;
+  RailCapabilities capabilities = 5;
+  Limits limits = 6;
+  string version = 7;
+  bool is_enabled = 8;
+}

api/proto/gateway/mntx/v1/mntx.proto

@@ -5,7 +5,7 @@ package mntx.gateway.v1;
 option go_package = "github.com/tech/sendico/pkg/proto/gateway/mntx/v1;mntxv1";
 
 import "google/protobuf/timestamp.proto";
-import "common/money/v1/money.proto";
+import "common/gateway/v1/gateway.proto";
 
 // Status of a payout request handled by Monetix.
 enum PayoutStatus {
@@ -15,75 +15,6 @@ enum PayoutStatus {
   PAYOUT_STATUS_FAILED = 3;
 }
 
-// Basic destination data for the payout.
-message BankAccount {
-  string iban = 1;
-  string bic = 2;
-  string account_holder = 3;
-  string country = 4;
-}
-
-// Card destination for payouts (PAN-based or tokenized).
-message CardDestination {
-  oneof card {
-    string pan = 1;   // raw primary account number
-    string token = 2; // network or gateway-issued token
-  }
-  string cardholder_name = 3;
-  string exp_month = 4;
-  string exp_year = 5;
-  string country = 6;
-}
-
-// Wrapper allowing multiple payout destination types.
-message PayoutDestination {
-  oneof destination {
-    BankAccount bank_account = 1;
-    CardDestination card = 2;
-  }
-}
-
-message Payout {
-  string payout_ref = 1;
-  string idempotency_key = 2;
-  string organization_ref = 3;
-  PayoutDestination destination = 4;
-  common.money.v1.Money amount = 5;
-  string description = 6;
-  map<string, string> metadata = 7;
-  PayoutStatus status = 8;
-  string failure_reason = 9;
-  google.protobuf.Timestamp created_at = 10;
-  google.protobuf.Timestamp updated_at = 11;
-}
-
-message SubmitPayoutRequest {
-  string idempotency_key = 1;
-  string organization_ref = 2;
-  PayoutDestination destination = 3;
-  common.money.v1.Money amount = 4;
-  string description = 5;
-  map<string, string> metadata = 6;
-  string simulated_failure_reason = 7; // optional trigger to force a failed payout for testing
-}
-
-message SubmitPayoutResponse {
-  Payout payout = 1;
-}
-
-message GetPayoutRequest {
-  string payout_ref = 1;
-}
-
-message GetPayoutResponse {
-  Payout payout = 1;
-}
-
-// Event emitted over messaging when payout status changes.
-message PayoutStatusChangedEvent {
-  Payout payout = 1;
-}
-
 // Request to initiate a Monetix card payout.
 message CardPayoutRequest {
   string payout_id = 1;              // internal payout id, mapped to Monetix payment_id
@@ -144,6 +75,12 @@ message CardPayoutStatusChangedEvent {
   CardPayoutState payout = 1;
 }
 
+message ListGatewayInstancesRequest {}
+
+message ListGatewayInstancesResponse {
+  repeated common.gateway.v1.GatewayInstanceDescriptor items = 1;
+}
+
 // Request to initiate a token-based card payout.
 message CardTokenPayoutRequest {
   string payout_id = 1;
@@ -229,10 +166,9 @@ message CardTokenizeResponse {
 }
 
 service MntxGatewayService {
-  rpc SubmitPayout(SubmitPayoutRequest) returns (SubmitPayoutResponse);
-  rpc GetPayout(GetPayoutRequest) returns (GetPayoutResponse);
   rpc CreateCardPayout(CardPayoutRequest) returns (CardPayoutResponse);
   rpc GetCardPayoutStatus(GetCardPayoutStatusRequest) returns (GetCardPayoutStatusResponse);
   rpc CreateCardTokenPayout(CardTokenPayoutRequest) returns (CardTokenPayoutResponse);
   rpc CreateCardToken(CardTokenizeRequest) returns (CardTokenizeResponse);
+  rpc ListGatewayInstances(ListGatewayInstancesRequest) returns (ListGatewayInstancesResponse);
 }

api/proto/payments/orchestrator/v1/orchestrator.proto

@@ -7,6 +7,7 @@ option go_package = "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1;
 import "google/protobuf/timestamp.proto";
 import "common/money/v1/money.proto";
 import "common/fx/v1/fx.proto";
+import "common/gateway/v1/gateway.proto";
 import "common/trace/v1/trace.proto";
 import "common/pagination/v1/cursor.proto";
 import "billing/fees/v1/fees.proto";
@@ -23,9 +24,9 @@ enum PaymentKind {
 
 // SettlementMode defines how to treat fees/FX variance for payouts.
 enum SettlementMode {
-  SETTLEMENT_MODE_UNSPECIFIED = 0;
-  SETTLEMENT_MODE_FIX_SOURCE = 1;   // customer pays fees; sent amount fixed
-  SETTLEMENT_MODE_FIX_RECEIVED = 2; // receiver gets fixed amount; source flexes
+  SETTLEMENT_UNSPECIFIED = 0;
+  SETTLEMENT_FIX_SOURCE = 1;   // customer pays fees; sent amount fixed
+  SETTLEMENT_FIX_RECEIVED = 2; // receiver gets fixed amount; source flexes
 }
 
 enum PaymentState {
@@ -39,13 +40,13 @@ enum PaymentState {
 }
 
 enum PaymentFailureCode {
-  PAYMENT_FAILURE_CODE_UNSPECIFIED = 0;
-  PAYMENT_FAILURE_CODE_BALANCE = 1;
-  PAYMENT_FAILURE_CODE_LEDGER = 2;
-  PAYMENT_FAILURE_CODE_FX = 3;
-  PAYMENT_FAILURE_CODE_CHAIN = 4;
-  PAYMENT_FAILURE_CODE_FEES = 5;
-  PAYMENT_FAILURE_CODE_POLICY = 6;
+  FAILURE_UNSPECIFIED = 0;
+  FAILURE_BALANCE = 1;
+  FAILURE_LEDGER = 2;
+  FAILURE_FX = 3;
+  FAILURE_CHAIN = 4;
+  FAILURE_FEES = 5;
+  FAILURE_POLICY = 6;
 }
 
 message RequestMeta {
@@ -171,6 +172,21 @@ message ExecutionPlan {
   common.money.v1.Money total_network_fee = 2;
 }
 
+message PaymentStep {
+  common.gateway.v1.Rail rail = 1;
+  string gateway_id = 2; // required for external rails
+  common.gateway.v1.RailOperation action = 3;
+  common.money.v1.Money amount = 4;
+  string ref = 5;
+}
+
+message PaymentPlan {
+  string id = 1;
+  repeated PaymentStep steps = 2;
+  string idempotency_key = 3;
+  google.protobuf.Timestamp created_at = 4;
+}
+
 // Card payout gateway tracking info.
 message CardPayout {
   string payout_ref = 1;
@@ -197,6 +213,7 @@ message Payment {
   google.protobuf.Timestamp updated_at = 11;
   CardPayout card_payout = 12;
   ExecutionPlan execution_plan = 13;
+  PaymentPlan payment_plan = 14;
 }
 
 message QuotePaymentRequest {