hold/release + discovery based routing

api/pkg/payments/rail/gateway.go

@@ -24,6 +24,8 @@ type RailCapabilities struct {
 	CanReadBalance         bool
 	CanSendFee             bool
 	RequiresObserveConfirm bool
+	CanBlock               bool
+	CanRelease             bool
 }
 
 // FeeBreakdown provides a gateway-level fee description.
@@ -49,6 +51,25 @@ type TransferRequest struct {
 	DestinationMemo string
 }
 
+// BlockRequest defines the inputs for reserving value through a rail gateway.
+type BlockRequest struct {
+	OrganizationRef string
+	AccountID       string
+	Currency        string
+	Amount          string
+	IdempotencyKey  string
+	Metadata        map[string]string
+	ClientReference string
+}
+
+// ReleaseRequest defines the inputs for releasing a prior block.
+type ReleaseRequest struct {
+	ReferenceID     string
+	IdempotencyKey  string
+	Metadata        map[string]string
+	ClientReference string
+}
+
 // RailResult reports the outcome of a rail gateway operation.
 type RailResult struct {
 	ReferenceID string
@@ -80,4 +101,6 @@ type RailGateway interface {
 	Capabilities() RailCapabilities
 	Send(ctx context.Context, req TransferRequest) (RailResult, error)
 	Observe(ctx context.Context, referenceID string) (ObserveResult, error)
+	Block(ctx context.Context, req BlockRequest) (RailResult, error)
+	Release(ctx context.Context, req ReleaseRequest) (RailResult, error)
 }