unified gateway interface

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