unified gateway interface

api/pkg/payments/rail/gateway.go

@@ -0,0 +1,83 @@
+package rail
+
+import (
+	"context"
+
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+)
+
+// Money represents a currency amount using decimal-safe strings.
+type Money = paymenttypes.Money
+
+const (
+	TransferStatusUnspecified = "UNSPECIFIED"
+	TransferStatusSuccess     = "SUCCESS"
+	TransferStatusFailed      = "FAILED"
+	TransferStatusRejected    = "REJECTED"
+	TransferStatusPending     = "PENDING"
+)
+
+// RailCapabilities are declared per gateway instance.
+type RailCapabilities struct {
+	CanPayIn               bool
+	CanPayOut              bool
+	CanReadBalance         bool
+	CanSendFee             bool
+	RequiresObserveConfirm bool
+}
+
+// FeeBreakdown provides a gateway-level fee description.
+type FeeBreakdown struct {
+	FeeCode     string
+	Amount      *Money
+	Description string
+}
+
+// TransferRequest defines the inputs for sending value through a rail gateway.
+type TransferRequest struct {
+	OrganizationRef string
+	FromAccountID   string
+	ToAccountID     string
+	Currency        string
+	Network         string
+	Amount          string
+	Fee             *Money
+	Fees            []FeeBreakdown
+	IdempotencyKey  string
+	Metadata        map[string]string
+	ClientReference string
+	DestinationMemo string
+}
+
+// RailResult reports the outcome of a rail gateway operation.
+type RailResult struct {
+	ReferenceID string
+	Status      string
+	FinalAmount *Money
+	Error       *RailError
+}
+
+// ObserveResult reports the outcome of a confirmation observation.
+type ObserveResult struct {
+	ReferenceID string
+	Status      string
+	FinalAmount *Money
+	Error       *RailError
+}
+
+// RailError captures structured failure details from a gateway.
+type RailError struct {
+	Code           string
+	Message        string
+	CanRetry       bool
+	ShouldRollback bool
+}
+
+// RailGateway exposes unified gateway operations for external rails.
+type RailGateway interface {
+	Rail() string
+	Network() string
+	Capabilities() RailCapabilities
+	Send(ctx context.Context, req TransferRequest) (RailResult, error)
+	Observe(ctx context.Context, referenceID string) (ObserveResult, error)
+}

api/pkg/payments/rail/ledger.go

@@ -0,0 +1,38 @@
+package rail
+
+import (
+	"context"
+	"time"
+
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+	ledgerv1 "github.com/tech/sendico/pkg/proto/ledger/v1"
+)
+
+// InternalLedger exposes unified ledger operations for orchestration.
+type InternalLedger interface {
+	ReadBalance(ctx context.Context, accountID string) (*moneyv1.Money, error)
+	CreateTransaction(ctx context.Context, tx LedgerTx) (string, error)
+	HoldBalance(ctx context.Context, accountID string, amount string) error
+}
+
+// LedgerTx captures ledger posting context used by orchestration.
+type LedgerTx struct {
+	PaymentPlanID       string
+	Currency            string
+	Amount              string
+	FeeAmount           string
+	FromRail            string
+	ToRail              string
+	ExternalReferenceID string
+	FXRateUsed          string
+	IdempotencyKey      string
+	CreatedAt           time.Time
+
+	// Internal fields required to map into the ledger API.
+	OrganizationRef        string
+	LedgerAccountRef       string
+	ContraLedgerAccountRef string
+	Description            string
+	Charges                []*ledgerv1.PostingLine
+	Metadata               map[string]string
+}