Merge pull request 'separated quotation and payments' (#462) from pq-462 into main

Reviewed-on: #462

.woodpecker/payments_quotation.yml

@@ -0,0 +1,81 @@
+matrix:
+  include:
+    - PAYMENTS_QUOTATION_IMAGE_PATH: payments/quotation
+      PAYMENTS_QUOTATION_DOCKERFILE: ci/prod/compose/payments_quotation.dockerfile
+      PAYMENTS_QUOTATION_MONGO_SECRET_PATH: sendico/db
+      PAYMENTS_QUOTATION_ENV: prod
+
+when:
+  - event: push
+    branch: main
+    path:
+      include:
+        - api/payments/quotation/**
+        - api/payments/storage/**
+        - api/payments/orchestrator/**
+        - api/proto/**
+        - api/pkg/**
+      ignore_message: '[rebuild]'
+
+steps:
+  - name: version
+    image: alpine:latest
+    commands:
+      - set -euo pipefail 2>/dev/null || set -eu
+      - apk add --no-cache git
+      - GIT_REV="$(git rev-parse --short HEAD)"
+      - BUILD_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
+      - APP_V="$(cat version)"
+      - BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+      - BUILD_USER="${WOODPECKER_MACHINE:-woodpecker}"
+      - printf "GIT_REV=%s\nBUILD_BRANCH=%s\nAPP_V=%s\nBUILD_DATE=%s\nBUILD_USER=%s\n" \
+          "$GIT_REV" "$BUILD_BRANCH" "$APP_V" "$BUILD_DATE" "$BUILD_USER" | tee .env.version
+
+  - name: proto
+    image: golang:alpine
+    depends_on: [ version ]
+    commands:
+      - set -eu
+      - apk add --no-cache bash git build-base protoc protobuf-dev
+      - go install google.golang.org/protobuf/cmd/protoc-gen-go@latest
+      - go install google.golang.org/grpc/cmd/protoc-gen-go-grpc@latest
+      - export PATH="$(go env GOPATH)/bin:$PATH"
+      - bash ci/scripts/proto/generate.sh
+
+  - name: secrets
+    image: alpine:latest
+    depends_on: [ version ]
+    environment:
+      VAULT_ADDR: { from_secret: VAULT_ADDR }
+      VAULT_ROLE_ID:   { from_secret: VAULT_APP_ROLE }
+      VAULT_SECRET_ID: { from_secret: VAULT_SECRET_ID }
+    commands:
+      - set -euo pipefail
+      - apk add --no-cache bash coreutils openssh-keygen curl sed python3
+      - mkdir -p secrets
+      - ./ci/vlt kv_to_file kv ops/deploy/ssh_key private_b64 secrets/SSH_KEY.b64 600
+      - base64 -d secrets/SSH_KEY.b64 > secrets/SSH_KEY
+      - chmod 600 secrets/SSH_KEY
+      - ssh-keygen -y -f secrets/SSH_KEY >/dev/null
+      - ./ci/vlt kv_get kv registry user > secrets/REGISTRY_USER
+      - ./ci/vlt kv_get kv registry password > secrets/REGISTRY_PASSWORD
+
+  - name: build-image
+    image: gcr.io/kaniko-project/executor:debug
+    depends_on: [ proto, secrets ]
+    commands:
+      - sh ci/scripts/payments_quotation/build-image.sh
+
+  - name: deploy
+    image: alpine:latest
+    depends_on: [ secrets, build-image ]
+    environment:
+      VAULT_ADDR: { from_secret: VAULT_ADDR }
+      VAULT_ROLE_ID:   { from_secret: VAULT_APP_ROLE }
+      VAULT_SECRET_ID: { from_secret: VAULT_SECRET_ID }
+    commands:
+      - set -euo pipefail
+      - apk add --no-cache bash openssh-client rsync coreutils curl sed python3
+      - mkdir -p /root/.ssh
+      - install -m 600 secrets/SSH_KEY /root/.ssh/id_rsa
+      - sh ci/scripts/payments_quotation/deploy.sh

api/payments/orchestrator/client/client.go

@@ -14,7 +14,7 @@ import (
 	"google.golang.org/grpc/credentials/insecure"
 )
 
-// Client exposes typed helpers around the payment orchestrator gRPC API.
+// Client exposes typed helpers around the payment orchestration and quotation gRPC APIs.
 type Client interface {
 	QuotePayment(ctx context.Context, req *orchestratorv1.QuotePaymentRequest) (*orchestratorv1.QuotePaymentResponse, error)
 	QuotePayments(ctx context.Context, req *orchestratorv1.QuotePaymentsRequest) (*orchestratorv1.QuotePaymentsResponse, error)
@@ -30,8 +30,6 @@ type Client interface {
 }
 
 type grpcOrchestratorClient interface {
-	QuotePayment(ctx context.Context, in *orchestratorv1.QuotePaymentRequest, opts ...grpc.CallOption) (*orchestratorv1.QuotePaymentResponse, error)
-	QuotePayments(ctx context.Context, in *orchestratorv1.QuotePaymentsRequest, opts ...grpc.CallOption) (*orchestratorv1.QuotePaymentsResponse, error)
 	InitiatePayments(ctx context.Context, in *orchestratorv1.InitiatePaymentsRequest, opts ...grpc.CallOption) (*orchestratorv1.InitiatePaymentsResponse, error)
 	InitiatePayment(ctx context.Context, in *orchestratorv1.InitiatePaymentRequest, opts ...grpc.CallOption) (*orchestratorv1.InitiatePaymentResponse, error)
 	CancelPayment(ctx context.Context, in *orchestratorv1.CancelPaymentRequest, opts ...grpc.CallOption) (*orchestratorv1.CancelPaymentResponse, error)
@@ -42,10 +40,17 @@ type grpcOrchestratorClient interface {
 	ProcessDepositObserved(ctx context.Context, in *orchestratorv1.ProcessDepositObservedRequest, opts ...grpc.CallOption) (*orchestratorv1.ProcessDepositObservedResponse, error)
 }
 
+type grpcQuotationClient interface {
+	QuotePayment(ctx context.Context, in *orchestratorv1.QuotePaymentRequest, opts ...grpc.CallOption) (*orchestratorv1.QuotePaymentResponse, error)
+	QuotePayments(ctx context.Context, in *orchestratorv1.QuotePaymentsRequest, opts ...grpc.CallOption) (*orchestratorv1.QuotePaymentsResponse, error)
+}
+
 type orchestratorClient struct {
-	cfg    Config
-	conn   *grpc.ClientConn
-	client grpcOrchestratorClient
+	cfg         Config
+	conn        *grpc.ClientConn
+	quoteConn   *grpc.ClientConn
+	client      grpcOrchestratorClient
+	quoteClient grpcQuotationClient
 }
 
 // New dials the payment orchestrator endpoint and returns a ready client.
@@ -54,10 +59,36 @@ func New(ctx context.Context, cfg Config, opts ...grpc.DialOption) (Client, erro
 	if strings.TrimSpace(cfg.Address) == "" {
 		return nil, merrors.InvalidArgument("payment-orchestrator: address is required")
 	}
+	if strings.TrimSpace(cfg.QuoteAddress) == "" {
+		cfg.QuoteAddress = cfg.Address
+	}
 
+	conn, err := dial(ctx, cfg, cfg.Address, opts...)
+	if err != nil {
+		return nil, err
+	}
+
+	quoteConn := conn
+	if cfg.QuoteAddress != cfg.Address {
+		quoteConn, err = dial(ctx, cfg, cfg.QuoteAddress, opts...)
+		if err != nil {
+			_ = conn.Close()
+			return nil, err
+		}
+	}
+
+	return &orchestratorClient{
+		cfg:         cfg,
+		conn:        conn,
+		quoteConn:   quoteConn,
+		client:      orchestratorv1.NewPaymentOrchestratorClient(conn),
+		quoteClient: orchestratorv1.NewPaymentQuotationClient(quoteConn),
+	}, nil
+}
+
+func dial(ctx context.Context, cfg Config, address string, opts ...grpc.DialOption) (*grpc.ClientConn, error) {
 	dialCtx, cancel := context.WithTimeout(ctx, cfg.DialTimeout)
 	defer cancel()
-
 	dialOpts := make([]grpc.DialOption, 0, len(opts)+1)
 	dialOpts = append(dialOpts, opts...)
 
@@ -67,44 +98,64 @@ func New(ctx context.Context, cfg Config, opts ...grpc.DialOption) (Client, erro
 		dialOpts = append(dialOpts, grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
 	}
 
-	conn, err := grpc.DialContext(dialCtx, cfg.Address, dialOpts...)
+	conn, err := grpc.DialContext(dialCtx, address, dialOpts...)
 	if err != nil {
-		return nil, merrors.InternalWrap(err, fmt.Sprintf("payment-orchestrator: dial %s", cfg.Address))
+		return nil, merrors.InternalWrap(err, fmt.Sprintf("payment-orchestrator: dial %s", address))
 	}
-
-	return &orchestratorClient{
-		cfg:    cfg,
-		conn:   conn,
-		client: orchestratorv1.NewPaymentOrchestratorClient(conn),
-	}, nil
+	return conn, nil
 }
 
 // NewWithClient injects a pre-built orchestrator client (useful for tests).
 func NewWithClient(cfg Config, oc grpcOrchestratorClient) Client {
+	return NewWithClients(cfg, oc, nil)
+}
+
+// NewWithClients injects pre-built orchestrator and quotation clients (useful for tests).
+func NewWithClients(cfg Config, oc grpcOrchestratorClient, qc grpcQuotationClient) Client {
 	cfg.setDefaults()
+	if qc == nil {
+		if q, ok := any(oc).(grpcQuotationClient); ok {
+			qc = q
+		}
+	}
 	return &orchestratorClient{
-		cfg:    cfg,
-		client: oc,
+		cfg:         cfg,
+		client:      oc,
+		quoteClient: qc,
 	}
 }
 
 func (c *orchestratorClient) Close() error {
-	if c.conn != nil {
-		return c.conn.Close()
+	var firstErr error
+	if c.quoteConn != nil && c.quoteConn != c.conn {
+		if err := c.quoteConn.Close(); err != nil && firstErr == nil {
+			firstErr = err
+		}
 	}
-	return nil
+	if c.conn != nil {
+		if err := c.conn.Close(); err != nil && firstErr == nil {
+			firstErr = err
+		}
+	}
+	return firstErr
 }
 
 func (c *orchestratorClient) QuotePayment(ctx context.Context, req *orchestratorv1.QuotePaymentRequest) (*orchestratorv1.QuotePaymentResponse, error) {
+	if c.quoteClient == nil {
+		return nil, merrors.InvalidArgument("payment-orchestrator: quotation client is not configured")
+	}
 	ctx, cancel := c.callContext(ctx)
 	defer cancel()
-	return c.client.QuotePayment(ctx, req)
+	return c.quoteClient.QuotePayment(ctx, req)
 }
 
 func (c *orchestratorClient) QuotePayments(ctx context.Context, req *orchestratorv1.QuotePaymentsRequest) (*orchestratorv1.QuotePaymentsResponse, error) {
+	if c.quoteClient == nil {
+		return nil, merrors.InvalidArgument("payment-orchestrator: quotation client is not configured")
+	}
 	ctx, cancel := c.callContext(ctx)
 	defer cancel()
-	return c.client.QuotePayments(ctx, req)
+	return c.quoteClient.QuotePayments(ctx, req)
 }
 
 func (c *orchestratorClient) InitiatePayments(ctx context.Context, req *orchestratorv1.InitiatePaymentsRequest) (*orchestratorv1.InitiatePaymentsResponse, error) {

api/payments/orchestrator/client/config.go

@@ -4,10 +4,11 @@ import "time"
 
 // Config captures connection settings for the payment orchestrator gRPC service.
 type Config struct {
-	Address     string
-	DialTimeout time.Duration
-	CallTimeout time.Duration
-	Insecure    bool
+	Address      string
+	QuoteAddress string
+	DialTimeout  time.Duration
+	CallTimeout  time.Duration
+	Insecure     bool
 }
 
 func (c *Config) setDefaults() {

api/payments/orchestrator/go.mod

@@ -14,6 +14,8 @@ replace github.com/tech/sendico/fx/oracle => ../../fx/oracle
 
 replace github.com/tech/sendico/ledger => ../../ledger
 
+replace github.com/tech/sendico/payments/storage => ../storage
+
 require (
 	github.com/google/uuid v1.6.0
 	github.com/prometheus/client_golang v1.23.2
@@ -22,6 +24,7 @@ require (
 	github.com/tech/sendico/gateway/chain v0.0.0-00010101000000-000000000000
 	github.com/tech/sendico/gateway/mntx v0.0.0-00010101000000-000000000000
 	github.com/tech/sendico/ledger v0.0.0-00010101000000-000000000000
+	github.com/tech/sendico/payments/storage v0.0.0-00010101000000-000000000000
 	github.com/tech/sendico/pkg v0.1.0
 	github.com/testcontainers/testcontainers-go v0.33.0
 	github.com/testcontainers/testcontainers-go/modules/mongodb v0.33.0

api/payments/orchestrator/internal/server/internal/config.go

@@ -12,17 +12,17 @@ import (
 )
 
 type config struct {
-	*grpcapp.Config  `yaml:",inline"`
-	Fees             clientConfig                      `yaml:"fees"`
-	Ledger           clientConfig                      `yaml:"ledger"`
-	Gateway          clientConfig                      `yaml:"gateway"`
-	PaymentGateway   clientConfig                      `yaml:"payment_gateway"`
-	Mntx             clientConfig                      `yaml:"mntx"`
-	Oracle           clientConfig                      `yaml:"oracle"`
-	CardGateways     map[string]cardGatewayRouteConfig `yaml:"card_gateways"`
-	FeeAccounts      map[string]string                 `yaml:"fee_ledger_accounts"`
-	GatewayInstances []gatewayInstanceConfig           `yaml:"gateway_instances"`
-	QuoteRetentionHrs int                              `yaml:"quote_retention_hours"`
+	*grpcapp.Config   `yaml:",inline"`
+	Fees              clientConfig                      `yaml:"fees"`
+	Ledger            clientConfig                      `yaml:"ledger"`
+	Gateway           clientConfig                      `yaml:"gateway"`
+	PaymentGateway    clientConfig                      `yaml:"payment_gateway"`
+	Mntx              clientConfig                      `yaml:"mntx"`
+	Oracle            clientConfig                      `yaml:"oracle"`
+	CardGateways      map[string]cardGatewayRouteConfig `yaml:"card_gateways"`
+	FeeAccounts       map[string]string                 `yaml:"fee_ledger_accounts"`
+	GatewayInstances  []gatewayInstanceConfig           `yaml:"gateway_instances"`
+	QuoteRetentionHrs int                               `yaml:"quote_retention_hours"`
 }
 
 type clientConfig struct {

api/payments/orchestrator/internal/server/internal/discovery.go

@@ -33,7 +33,7 @@ func (i *Imp) initDiscovery(cfg *config) {
 	}
 	announce := discovery.Announcement{
 		Service:    "PAYMENTS_ORCHESTRATOR",
-		Operations: []string{"payment.quote", "payment.initiate"},
+		Operations: []string{"payment.initiate"},
 		InvokeURI:  cfg.GRPC.DiscoveryInvokeURI(),
 		Version:    appversion.Create().Short(),
 	}

api/payments/orchestrator/internal/server/internal/serverimp.go

@@ -2,8 +2,8 @@ package serverimp
 
 import (
 	"github.com/tech/sendico/payments/orchestrator/internal/service/orchestrator"
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	mongostorage "github.com/tech/sendico/payments/orchestrator/storage/mongo"
+	"github.com/tech/sendico/payments/storage"
+	mongostorage "github.com/tech/sendico/payments/storage/mongo"
 	"github.com/tech/sendico/pkg/db"
 	msg "github.com/tech/sendico/pkg/messaging"
 	mb "github.com/tech/sendico/pkg/messaging/broker"

api/payments/orchestrator/internal/server/internal/types.go

@@ -2,7 +2,7 @@ package serverimp
 
 import (
 	"github.com/tech/sendico/payments/orchestrator/internal/service/orchestrator"
-	"github.com/tech/sendico/payments/orchestrator/storage"
+	"github.com/tech/sendico/payments/storage"
 	"github.com/tech/sendico/pkg/discovery"
 	"github.com/tech/sendico/pkg/mlogger"
 	"github.com/tech/sendico/pkg/server/grpcapp"
@@ -13,11 +13,11 @@ type Imp struct {
 	file   string
 	debug  bool
 
-	config               *config
-	app                  *grpcapp.App[storage.Repository]
-	discoveryWatcher     *discovery.RegistryWatcher
-	discoveryReg         *discovery.Registry
-	discoveryAnnouncer   *discovery.Announcer
-	discoveryClients     *discoveryClientResolver
-	service              *orchestrator.Service
+	config             *config
+	app                *grpcapp.App[storage.Repository]
+	discoveryWatcher   *discovery.RegistryWatcher
+	discoveryReg       *discovery.Registry
+	discoveryAnnouncer *discovery.Announcer
+	discoveryClients   *discoveryClientResolver
+	service            *orchestrator.Service
 }

api/payments/orchestrator/internal/service/orchestrator/card_payout_funding.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/shopspring/decimal"
 	chainclient "github.com/tech/sendico/gateway/chain/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"

api/payments/orchestrator/internal/service/orchestrator/card_payout_helpers.go

@@ -4,7 +4,7 @@ import (
 	"strings"
 
 	"github.com/shopspring/decimal"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 )
 

api/payments/orchestrator/internal/service/orchestrator/card_payout_submit.go

@@ -6,7 +6,7 @@ import (
 
 	"github.com/google/uuid"
 	"github.com/shopspring/decimal"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"

api/payments/orchestrator/internal/service/orchestrator/card_payout_test.go

@@ -7,7 +7,7 @@ import (
 
 	chainclient "github.com/tech/sendico/gateway/chain/client"
 	mntxclient "github.com/tech/sendico/gateway/mntx/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	mo "github.com/tech/sendico/pkg/model"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"

api/payments/orchestrator/internal/service/orchestrator/command_factory.go

@@ -4,8 +4,8 @@ import (
 	"context"
 	"time"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/mlogger"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 )

api/payments/orchestrator/internal/service/orchestrator/composite_gateway_registry.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"sort"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/mlogger"
 	"go.uber.org/zap"
 )

api/payments/orchestrator/internal/service/orchestrator/convert.go

@@ -4,7 +4,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	chainasset "github.com/tech/sendico/pkg/chain"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"

api/payments/orchestrator/internal/service/orchestrator/convert_card_test.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"testing"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 )
 

api/payments/orchestrator/internal/service/orchestrator/discovery_gateway_registry.go

@@ -6,7 +6,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/discovery"
 	"github.com/tech/sendico/pkg/mlogger"
 )

api/payments/orchestrator/internal/service/orchestrator/execution_plan.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
 )
 

api/payments/orchestrator/internal/service/orchestrator/gateway_execution_consumer.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"strings"
 
-	paymodel "github.com/tech/sendico/payments/orchestrator/storage/model"
+	paymodel "github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	cons "github.com/tech/sendico/pkg/messaging/consumer"
 	paymentgateway "github.com/tech/sendico/pkg/messaging/notifications/paymentgateway"

api/payments/orchestrator/internal/service/orchestrator/gateway_execution_consumer_test.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"testing"
 
-	paymodel "github.com/tech/sendico/payments/orchestrator/storage/model"
+	paymodel "github.com/tech/sendico/payments/storage/model"
 	mloggerfactory "github.com/tech/sendico/pkg/mlogger/factory"
 	"github.com/tech/sendico/pkg/model"
 	"github.com/tech/sendico/pkg/payments/rail"

api/payments/orchestrator/internal/service/orchestrator/gateway_registry.go

@@ -5,7 +5,7 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/mlogger"
 )
 

api/payments/orchestrator/internal/service/orchestrator/gateway_resolution.go

@@ -7,7 +7,7 @@ import (
 
 	"github.com/shopspring/decimal"
 	chainclient "github.com/tech/sendico/gateway/chain/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	"go.uber.org/zap"

api/payments/orchestrator/internal/service/orchestrator/handlers_commands.go

@@ -10,8 +10,8 @@ import (
 	"time"
 
 	"github.com/google/uuid"
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/api/routers/gsresponse"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"

api/payments/orchestrator/internal/service/orchestrator/handlers_events.go

@@ -4,8 +4,8 @@ import (
 	"context"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/api/routers/gsresponse"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"

api/payments/orchestrator/internal/service/orchestrator/handlers_queries.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"context"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
+	"github.com/tech/sendico/payments/storage"
 	"github.com/tech/sendico/pkg/api/routers/gsresponse"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"

api/payments/orchestrator/internal/service/orchestrator/internal_helpers.go

@@ -5,7 +5,7 @@ import (
 	"strings"
 	"time"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/api/routers/gsresponse"
 	"github.com/tech/sendico/pkg/mservice"
 	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"

api/payments/orchestrator/internal/service/orchestrator/internal_helpers_test.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"testing"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 )

api/payments/orchestrator/internal/service/orchestrator/options.go

@@ -11,7 +11,7 @@ import (
 	chainclient "github.com/tech/sendico/gateway/chain/client"
 	mntxclient "github.com/tech/sendico/gateway/mntx/client"
 	ledgerclient "github.com/tech/sendico/ledger/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	clockpkg "github.com/tech/sendico/pkg/clock"
 	"github.com/tech/sendico/pkg/merrors"
 	mb "github.com/tech/sendico/pkg/messaging/broker"

api/payments/orchestrator/internal/service/orchestrator/payment_executor.go

@@ -4,8 +4,8 @@ import (
 	"context"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"
 	fxv1 "github.com/tech/sendico/pkg/proto/common/fx/v1"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_analyzer.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"errors"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/mlogger"
 	"go.uber.org/zap"
 )

api/payments/orchestrator/internal/service/orchestrator/payment_plan_card.go

@@ -5,7 +5,7 @@ import (
 	"strings"
 
 	"github.com/shopspring/decimal"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/model/account_role"
 	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_chain.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/model/account_role"
 	"github.com/tech/sendico/pkg/payments/rail"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_executor.go

@@ -3,8 +3,8 @@ package orchestrator
 import (
 	"context"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 	"go.uber.org/zap"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_executor_test.go

@@ -7,7 +7,7 @@ import (
 
 	mntxclient "github.com/tech/sendico/gateway/mntx/client"
 	ledgerclient "github.com/tech/sendico/ledger/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	mo "github.com/tech/sendico/pkg/model"
 	"github.com/tech/sendico/pkg/model/account_role"
 	"github.com/tech/sendico/pkg/payments/rail"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_helpers.go

@@ -5,7 +5,7 @@ import (
 	"strings"
 
 	"github.com/google/uuid"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/model/account_role"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 )

api/payments/orchestrator/internal/service/orchestrator/payment_plan_ledger.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/ledgerconv"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/model/account_role"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_ledger_test.go

@@ -5,7 +5,7 @@ import (
 	"testing"
 
 	ledgerclient "github.com/tech/sendico/ledger/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/model/account_role"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	connectorv1 "github.com/tech/sendico/pkg/proto/connector/v1"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_order.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 )
 

api/payments/orchestrator/internal/service/orchestrator/payment_plan_release.go

@@ -3,8 +3,8 @@ package orchestrator
 import (
 	"context"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"go.uber.org/zap"
 )
 

api/payments/orchestrator/internal/service/orchestrator/payment_plan_release_test.go

@@ -6,7 +6,7 @@ import (
 	"testing"
 
 	ledgerclient "github.com/tech/sendico/ledger/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	mo "github.com/tech/sendico/pkg/model"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	"go.mongodb.org/mongo-driver/v2/bson"

api/payments/orchestrator/internal/service/orchestrator/payment_plan_steps.go

@@ -6,7 +6,7 @@ import (
 	"math/big"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	ledgerv1 "github.com/tech/sendico/pkg/proto/ledger/v1"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"

api/payments/orchestrator/internal/service/orchestrator/plan_builder.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"context"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 )
 

api/payments/orchestrator/internal/service/orchestrator/plan_builder_default.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"context"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"
 	"github.com/tech/sendico/pkg/mutil/mzap"

api/payments/orchestrator/internal/service/orchestrator/plan_builder_default_test.go

@@ -5,7 +5,7 @@ import (
 	"strings"
 	"testing"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	mloggerfactory "github.com/tech/sendico/pkg/mlogger/factory"
 	"github.com/tech/sendico/pkg/model/account_role"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"

api/payments/orchestrator/internal/service/orchestrator/plan_builder_endpoints.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 )
 

api/payments/orchestrator/internal/service/orchestrator/plan_builder_gateways.go

@@ -7,7 +7,7 @@ import (
 	"strings"
 
 	"github.com/shopspring/decimal"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"

api/payments/orchestrator/internal/service/orchestrator/plan_builder_plans.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"time"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	paymenttypes "github.com/tech/sendico/pkg/payments/types"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"

api/payments/orchestrator/internal/service/orchestrator/plan_builder_routes.go

@@ -5,7 +5,7 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 )
 

api/payments/orchestrator/internal/service/orchestrator/plan_builder_steps.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/model/account_role"
 	"github.com/tech/sendico/pkg/mutil/mzap"

api/payments/orchestrator/internal/service/orchestrator/plan_builder_templates.go

@@ -5,7 +5,7 @@ import (
 	"sort"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"
 	"github.com/tech/sendico/pkg/mutil/mzap"

api/payments/orchestrator/internal/service/orchestrator/provider_settlement.go

@@ -3,7 +3,7 @@ package orchestrator
 import (
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/model/account_role"
 	"github.com/tech/sendico/pkg/payments/rail"

api/payments/orchestrator/internal/service/orchestrator/quote_batch.go

@@ -7,7 +7,7 @@ import (
 	"time"
 
 	"github.com/shopspring/decimal"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
 )

api/payments/orchestrator/internal/service/orchestrator/quote_engine.go

@@ -8,7 +8,7 @@ import (
 	"time"
 
 	oracleclient "github.com/tech/sendico/fx/oracle/client"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage/model"
 	chainpkg "github.com/tech/sendico/pkg/chain"
 	"github.com/tech/sendico/pkg/merrors"
 	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"

api/payments/orchestrator/internal/service/orchestrator/quote_payment_idempotency_integration_test.go

@@ -9,8 +9,8 @@ import (
 	"testing"
 	"time"
 
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
-	storagemongo "github.com/tech/sendico/payments/orchestrator/storage/mongo"
+	"github.com/tech/sendico/payments/storage/model"
+	storagemongo "github.com/tech/sendico/payments/storage/mongo"
 	"github.com/tech/sendico/pkg/db/repository"
 	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
 	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"

api/payments/orchestrator/internal/service/orchestrator/service.go

@@ -3,8 +3,8 @@ package orchestrator
 import (
 	"context"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/api/routers"
 	clockpkg "github.com/tech/sendico/pkg/clock"
 	msg "github.com/tech/sendico/pkg/messaging"

api/payments/orchestrator/internal/service/orchestrator/service_helpers.go

@@ -5,8 +5,8 @@ import (
 	"errors"
 	"strings"
 
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/api/routers/gsresponse"
 	"github.com/tech/sendico/pkg/merrors"
 	"github.com/tech/sendico/pkg/mlogger"

api/payments/orchestrator/internal/service/orchestrator/service_helpers_test.go

@@ -7,8 +7,8 @@ import (
 
 	oracleclient "github.com/tech/sendico/fx/oracle/client"
 	ledgerclient "github.com/tech/sendico/ledger/client"
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	clockpkg "github.com/tech/sendico/pkg/clock"
 	mloggerfactory "github.com/tech/sendico/pkg/mlogger/factory"
 	"github.com/tech/sendico/pkg/model/account_role"

api/payments/orchestrator/internal/service/orchestrator/service_test.go

@@ -8,8 +8,8 @@ import (
 	"time"
 
 	ledgerclient "github.com/tech/sendico/ledger/client"
-	"github.com/tech/sendico/payments/orchestrator/storage"
-	"github.com/tech/sendico/payments/orchestrator/storage/model"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
 	"github.com/tech/sendico/pkg/api/routers/gsresponse"
 	"github.com/tech/sendico/pkg/merrors"
 	mo "github.com/tech/sendico/pkg/model"

api/payments/quotation/.air.toml

@@ -0,0 +1,46 @@
+root = "."
+testdata_dir = "testdata"
+tmp_dir = "tmp"
+
+[build]
+  args_bin = []
+  entrypoint = "./tmp/main"
+  cmd = "go build -o ./tmp/main ."
+  delay = 1000
+  exclude_dir = ["assets", "tmp", "vendor", "testdata"]
+  exclude_file = []
+  exclude_regex = ["_test.go", "_templ.go"]
+  exclude_unchanged = false
+  follow_symlink = false
+  full_bin = ""
+  include_dir = []
+  include_ext = ["go", "tpl", "tmpl", "html"]
+  include_file = []
+  kill_delay = "0s"
+  log = "build-errors.log"
+  poll = false
+  poll_interval = 0
+  post_cmd = []
+  pre_cmd = []
+  rerun = false
+  rerun_delay = 500
+  send_interrupt = false
+  stop_on_error = false
+
+[color]
+  app = ""
+  build = "yellow"
+  main = "magenta"
+  runner = "green"
+  watcher = "cyan"
+
+[log]
+  main_only = false
+  time = false
+
+[misc]
+  clean_on_exit = false
+
+[screen]
+  clear_on_rebuild = false
+  keep_scroll = true

api/payments/quotation/.gitignore

@@ -0,0 +1,4 @@
+internal/generated
+.gocache
+app
+tmp

api/payments/quotation/config.dev.yml

@@ -0,0 +1,59 @@
+runtime:
+  shutdown_timeout_seconds: 15
+
+grpc:
+  network: tcp
+  address: ":50064"
+  advertise_host: "dev-payments-quotation"
+  enable_reflection: true
+  enable_health: true
+
+metrics:
+  address: ":9414"
+
+messaging:
+  driver: NATS
+  settings:
+    url_env: NATS_URL
+    host_env: NATS_HOST
+    port_env: NATS_PORT
+    username_env: NATS_USER
+    password_env: NATS_PASSWORD
+    broker_name: Payments Quotation Service
+    max_reconnects: 10
+    reconnect_wait: 5
+    buffer_size: 1024
+
+database:
+  driver: mongodb
+  settings:
+    host_env: PAYMENTS_MONGO_HOST
+    port_env: PAYMENTS_MONGO_PORT
+    database_env: PAYMENTS_MONGO_DATABASE
+    user_env: PAYMENTS_MONGO_USER
+    password_env: PAYMENTS_MONGO_PASSWORD
+    auth_source_env: PAYMENTS_MONGO_AUTH_SOURCE
+    replica_set_env: PAYMENTS_MONGO_REPLICA_SET
+
+fees:
+  address: dev-billing-fees:50060
+  address_env: FEES_ADDRESS
+  dial_timeout_seconds: 5
+  call_timeout_seconds: 5
+  insecure: true
+
+oracle:
+  address: dev-fx-oracle:50051
+  address_env: ORACLE_ADDRESS
+  dial_timeout_seconds: 5
+  call_timeout_seconds: 5
+  insecure: true
+
+gateway:
+  address: dev-chain-gateway:50053
+  address_env: CHAIN_GATEWAY_ADDRESS
+  dial_timeout_seconds: 5
+  call_timeout_seconds: 5
+  insecure: true
+
+quote_retention_hours: 72

api/payments/quotation/config.yml

@@ -0,0 +1,59 @@
+runtime:
+  shutdown_timeout_seconds: 15
+
+grpc:
+  network: tcp
+  address: ":50064"
+  advertise_host: "sendico_payments_quotation"
+  enable_reflection: true
+  enable_health: true
+
+metrics:
+  address: ":9414"
+
+messaging:
+  driver: NATS
+  settings:
+    url_env: NATS_URL
+    host_env: NATS_HOST
+    port_env: NATS_PORT
+    username_env: NATS_USER
+    password_env: NATS_PASSWORD
+    broker_name: Payments Quotation Service
+    max_reconnects: 10
+    reconnect_wait: 5
+    buffer_size: 1024
+
+database:
+  driver: mongodb
+  settings:
+    host_env: PAYMENTS_MONGO_HOST
+    port_env: PAYMENTS_MONGO_PORT
+    database_env: PAYMENTS_MONGO_DATABASE
+    user_env: PAYMENTS_MONGO_USER
+    password_env: PAYMENTS_MONGO_PASSWORD
+    auth_source_env: PAYMENTS_MONGO_AUTH_SOURCE
+    replica_set_env: PAYMENTS_MONGO_REPLICA_SET
+
+fees:
+  address: sendico_billing_fees:50060
+  address_env: FEES_ADDRESS
+  dial_timeout_seconds: 5
+  call_timeout_seconds: 5
+  insecure: true
+
+oracle:
+  address: sendico_fx_oracle:50051
+  address_env: ORACLE_ADDRESS
+  dial_timeout_seconds: 5
+  call_timeout_seconds: 5
+  insecure: true
+
+gateway:
+  address: sendico_chain_gateway:50053
+  address_env: CHAIN_GATEWAY_ADDRESS
+  dial_timeout_seconds: 5
+  call_timeout_seconds: 5
+  insecure: true
+
+quote_retention_hours: 72

api/payments/quotation/env/.gitignore

@@ -0,0 +1 @@
+.env.api

api/payments/quotation/go.mod

@@ -0,0 +1,67 @@
+module github.com/tech/sendico/payments/quotation
+
+go 1.25.7
+
+replace github.com/tech/sendico/pkg => ../../pkg
+
+replace github.com/tech/sendico/fx/oracle => ../../fx/oracle
+
+replace github.com/tech/sendico/gateway/chain => ../../gateway/chain
+
+replace github.com/tech/sendico/billing/fees => ../../billing/fees
+
+replace github.com/tech/sendico/gateway/mntx => ../../gateway/mntx
+
+replace github.com/tech/sendico/ledger => ../../ledger
+
+replace github.com/tech/sendico/payments/storage => ../storage
+
+require (
+	github.com/google/uuid v1.6.0
+	github.com/prometheus/client_golang v1.23.2
+	github.com/shopspring/decimal v1.4.0
+	github.com/tech/sendico/fx/oracle v0.0.0-00010101000000-000000000000
+	github.com/tech/sendico/gateway/chain v0.0.0-00010101000000-000000000000
+	github.com/tech/sendico/gateway/mntx v0.0.0-00010101000000-000000000000
+	github.com/tech/sendico/ledger v0.0.0-00010101000000-000000000000
+	github.com/tech/sendico/payments/storage v0.0.0-00010101000000-000000000000
+	github.com/tech/sendico/pkg v0.1.0
+	go.mongodb.org/mongo-driver/v2 v2.5.0
+	go.uber.org/zap v1.27.1
+	google.golang.org/grpc v1.78.0
+	google.golang.org/protobuf v1.36.11
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	github.com/beorn7/perks v1.0.1 // indirect
+	github.com/bmatcuk/doublestar/v4 v4.10.0 // indirect
+	github.com/casbin/casbin/v2 v2.135.0 // indirect
+	github.com/casbin/govaluate v1.10.0 // indirect
+	github.com/casbin/mongodb-adapter/v4 v4.3.0 // indirect
+	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/go-chi/chi/v5 v5.2.5 // indirect
+	github.com/klauspost/compress v1.18.4 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/mitchellh/mapstructure v1.5.0 // indirect
+	github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 // indirect
+	github.com/nats-io/nats.go v1.48.0 // indirect
+	github.com/nats-io/nkeys v0.4.15 // indirect
+	github.com/nats-io/nuid v1.0.1 // indirect
+	github.com/prometheus/client_model v0.6.2 // indirect
+	github.com/prometheus/common v0.67.5 // indirect
+	github.com/prometheus/procfs v0.19.2 // indirect
+	github.com/xdg-go/pbkdf2 v1.0.0 // indirect
+	github.com/xdg-go/scram v1.2.0 // indirect
+	github.com/xdg-go/stringprep v1.0.4 // indirect
+	github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 // indirect
+	go.uber.org/multierr v1.11.0 // indirect
+	go.yaml.in/yaml/v2 v2.4.3 // indirect
+	golang.org/x/crypto v0.48.0 // indirect
+	golang.org/x/net v0.50.0 // indirect
+	golang.org/x/sync v0.19.0 // indirect
+	golang.org/x/sys v0.41.0 // indirect
+	golang.org/x/text v0.34.0 // indirect
+	google.golang.org/genproto/googleapis/rpc v0.0.0-20260209200024-4cfbd4190f57 // indirect
+)

api/payments/quotation/go.sum

@@ -0,0 +1,224 @@
+dario.cat/mergo v1.0.1 h1:Ra4+bf83h2ztPIQYNP99R6m+Y7KfnARDfID+a+vLl4s=
+dario.cat/mergo v1.0.1/go.mod h1:uNxQE+84aUszobStD9th8a29P2fMDhsBdgRYvZOxGmk=
+github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161 h1:L/gRVlceqvL25UVaW/CKtUDjefjrs0SPonmDGUVOYP0=
+github.com/Azure/go-ansiterm v0.0.0-20230124172434-306776ec8161/go.mod h1:xomTg63KZ2rFqZQzSB4Vz2SUXa1BpHTVz9L5PTmPC4E=
+github.com/Microsoft/go-winio v0.6.2 h1:F2VQgta7ecxGYO8k3ZZz3RS8fVIXVxONVUPlNERoyfY=
+github.com/Microsoft/go-winio v0.6.2/go.mod h1:yd8OoFMLzJbo9gZq8j5qaps8bJ9aShtEA8Ipt1oGCvU=
+github.com/beorn7/perks v1.0.1 h1:VlbKKnNfV8bJzeqoa4cOKqO6bYr3WgKZxO8Z16+hsOM=
+github.com/beorn7/perks v1.0.1/go.mod h1:G2ZrVWU2WbWT9wwq4/hrbKbnv/1ERSJQ0ibhJ6rlkpw=
+github.com/bmatcuk/doublestar/v4 v4.6.1/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
+github.com/bmatcuk/doublestar/v4 v4.10.0 h1:zU9WiOla1YA122oLM6i4EXvGW62DvKZVxIe6TYWexEs=
+github.com/bmatcuk/doublestar/v4 v4.10.0/go.mod h1:xBQ8jztBU6kakFMg+8WGxn0c6z1fTSPVIjEY1Wr7jzc=
+github.com/casbin/casbin/v2 v2.135.0 h1:6BLkMQiGotYyS5yYeWgW19vxqugUlvHFkFiLnLR/bxk=
+github.com/casbin/casbin/v2 v2.135.0/go.mod h1:FmcfntdXLTcYXv/hxgNntcRPqAbwOG9xsism0yXT+18=
+github.com/casbin/govaluate v1.3.0/go.mod h1:G/UnbIjZk/0uMNaLwZZmFQrR72tYRZWQkO70si/iR7A=
+github.com/casbin/govaluate v1.10.0 h1:ffGw51/hYH3w3rZcxO/KcaUIDOLP84w7nsidMVgaDG0=
+github.com/casbin/govaluate v1.10.0/go.mod h1:G/UnbIjZk/0uMNaLwZZmFQrR72tYRZWQkO70si/iR7A=
+github.com/casbin/mongodb-adapter/v4 v4.3.0 h1:yYXky9v1by6vj/0QK7OyHyd/xpz4vzh0lCi7JKrS4qQ=
+github.com/casbin/mongodb-adapter/v4 v4.3.0/go.mod h1:bOTSYZUjX7I9E0ExEvgq46m3mcDNRII7g8iWjrM1BHE=
+github.com/cenkalti/backoff/v4 v4.3.0 h1:MyRJ/UdXutAwSAT+s3wNd7MfTIcy71VQueUuFK343L8=
+github.com/cenkalti/backoff/v4 v4.3.0/go.mod h1:Y3VNntkOUPxTVeUxJ/G5vcM//AlwfmyYozVcomhLiZE=
+github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
+github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
+github.com/containerd/log v0.1.0 h1:TCJt7ioM2cr/tfR8GPbGf9/VRAX8D2B4PjzCpfX540I=
+github.com/containerd/log v0.1.0/go.mod h1:VRRf09a7mHDIRezVKTRCrOq78v577GXq3bSa3EhrzVo=
+github.com/containerd/platforms v0.2.1 h1:zvwtM3rz2YHPQsF2CHYM8+KtB5dvhISiXh5ZpSBQv6A=
+github.com/containerd/platforms v0.2.1/go.mod h1:XHCb+2/hzowdiut9rkudds9bE5yJ7npe7dG/wG+uFPw=
+github.com/cpuguy83/dockercfg v0.3.2 h1:DlJTyZGBDlXqUZ2Dk2Q3xHs/FtnooJJVaad2S9GKorA=
+github.com/cpuguy83/dockercfg v0.3.2/go.mod h1:sugsbF4//dDlL/i+S+rtpIWp+5h0BHJHfjj5/jFyUJc=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/distribution/reference v0.6.0 h1:0IXCQ5g4/QMHHkarYzh5l+u8T3t73zM5QvfrDyIgxBk=
+github.com/distribution/reference v0.6.0/go.mod h1:BbU0aIcezP1/5jX/8MP0YiH4SdvB5Y4f/wlDRiLyi3E=
+github.com/docker/docker v27.3.1+incompatible h1:KttF0XoteNTicmUtBO0L2tP+J7FGRFTjaEF4k6WdhfI=
+github.com/docker/docker v27.3.1+incompatible/go.mod h1:eEKB0N0r5NX/I1kEveEz05bcu8tLC/8azJZsviup8Sk=
+github.com/docker/go-connections v0.5.0 h1:USnMq7hx7gwdVZq1L49hLXaFtUdTADjXGp+uj1Br63c=
+github.com/docker/go-connections v0.5.0/go.mod h1:ov60Kzw0kKElRwhNs9UlUHAE/F9Fe6GLaXnqyDdmEXc=
+github.com/docker/go-units v0.5.0 h1:69rxXcBk27SvSaaxTtLh/8llcHD8vYHT7WSdRZ/jvr4=
+github.com/docker/go-units v0.5.0/go.mod h1:fgPhTUdO+D/Jk86RDLlptpiXQzgHJF7gydDDbaIK4Dk=
+github.com/felixge/httpsnoop v1.0.4 h1:NFTV2Zj1bL4mc9sqWACXbQFVBBg2W3GPvqp8/ESS2Wg=
+github.com/felixge/httpsnoop v1.0.4/go.mod h1:m8KPJKqk1gH5J9DgRY2ASl2lWCfGKXixSwevea8zH2U=
+github.com/go-chi/chi/v5 v5.2.5 h1:Eg4myHZBjyvJmAFjFvWgrqDTXFyOzjj7YIm3L3mu6Ug=
+github.com/go-chi/chi/v5 v5.2.5/go.mod h1:X7Gx4mteadT3eDOMTsXzmI4/rwUpOwBHLpAfupzFJP0=
+github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
+github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
+github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
+github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
+github.com/go-ole/go-ole v1.3.0 h1:Dt6ye7+vXGIKZ7Xtk4s6/xVdGDQynvom7xCFEdWr6uE=
+github.com/go-ole/go-ole v1.3.0/go.mod h1:5LS6F96DhAwUc7C+1HLexzMXY1xGRSryjyPPKW6zv78=
+github.com/gogo/protobuf v1.3.2 h1:Ov1cvc58UF3b5XjBnZv7+opcTcQFZebYjWzi34vdm4Q=
+github.com/gogo/protobuf v1.3.2/go.mod h1:P1XiOD3dCwIKUDQYPy72D8LYyHL2YPYrpS2s69NZV8Q=
+github.com/golang/mock v1.4.4/go.mod h1:l3mdAwkq5BuhzHwde/uurv3sEJeZMXNpwsxVWU71h+4=
+github.com/golang/mock v1.6.0 h1:ErTB+efbowRARo13NNdxyJji2egdxLGQhRaY+DUumQc=
+github.com/golang/mock v1.6.0/go.mod h1:p6yTPP+5HYm5mzsMV8JkE6ZKdX+/wYM6Hr+LicevLPs=
+github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
+github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/klauspost/compress v1.18.4 h1:RPhnKRAQ4Fh8zU2FY/6ZFDwTVTxgJ/EMydqSTzE9a2c=
+github.com/klauspost/compress v1.18.4/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
+github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
+github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
+github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
+github.com/kylelemons/godebug v1.1.0 h1:RPNrshWIDI6G2gRW9EHilWtl7Z6Sb1BR0xunSBf0SNc=
+github.com/kylelemons/godebug v1.1.0/go.mod h1:9/0rRGxNHcop5bhtWyNeEfOS8JIWk580+fNqagV/RAw=
+github.com/lufia/plan9stats v0.0.0-20250827001030-24949be3fa54 h1:mFWunSatvkQQDhpdyuFAYwyAan3hzCuma+Pz8sqvOfg=
+github.com/lufia/plan9stats v0.0.0-20250827001030-24949be3fa54/go.mod h1:autxFIvghDt3jPTLoqZ9OZ7s9qTGNAWmYCjVFWPX/zg=
+github.com/magiconair/properties v1.8.7 h1:IeQXZAiQcpL9mgcAe1Nu6cX9LLw6ExEHKjN0VQdvPDY=
+github.com/magiconair/properties v1.8.7/go.mod h1:Dhd985XPs7jluiymwWYZ0G4Z61jb3vdS329zhj2hYo0=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/mitchellh/mapstructure v1.5.0 h1:jeMsZIYE/09sWLaz43PL7Gy6RuMjD2eJVyuac5Z2hdY=
+github.com/mitchellh/mapstructure v1.5.0/go.mod h1:bFUtVrKA4DC2yAKiSyO/QUcy7e+RRV2QTWOzhPopBRo=
+github.com/moby/docker-image-spec v1.3.1 h1:jMKff3w6PgbfSa69GfNg+zN/XLhfXJGnEx3Nl2EsFP0=
+github.com/moby/docker-image-spec v1.3.1/go.mod h1:eKmb5VW8vQEh/BAr2yvVNvuiJuY6UIocYsFu/DxxRpo=
+github.com/moby/patternmatcher v0.6.0 h1:GmP9lR19aU5GqSSFko+5pRqHi+Ohk1O69aFiKkVGiPk=
+github.com/moby/patternmatcher v0.6.0/go.mod h1:hDPoyOpDY7OrrMDLaYoY3hf52gNCR/YOUYxkhApJIxc=
+github.com/moby/sys/sequential v0.6.0 h1:qrx7XFUd/5DxtqcoH1h438hF5TmOvzC/lspjy7zgvCU=
+github.com/moby/sys/sequential v0.6.0/go.mod h1:uyv8EUTrca5PnDsdMGXhZe6CCe8U/UiTWd+lL+7b/Ko=
+github.com/moby/sys/user v0.3.0 h1:9ni5DlcW5an3SvRSx4MouotOygvzaXbaSrc/wGDFWPo=
+github.com/moby/sys/user v0.3.0/go.mod h1:bG+tYYYJgaMtRKgEmuueC0hJEAZWwtIbZTB+85uoHjs=
+github.com/moby/sys/userns v0.1.0 h1:tVLXkFOxVu9A64/yh59slHVv9ahO9UIev4JZusOLG/g=
+github.com/moby/sys/userns v0.1.0/go.mod h1:IHUYgu/kao6N8YZlp9Cf444ySSvCmDlmzUcYfDHOl28=
+github.com/moby/term v0.5.0 h1:xt8Q1nalod/v7BqbG21f8mQPqH+xAaC9C3N3wfWbVP0=
+github.com/moby/term v0.5.0/go.mod h1:8FzsFHVUBGZdbDsJw/ot+X+d5HLUbvklYLJ9uGfcI3Y=
+github.com/morikuni/aec v1.0.0 h1:nP9CBfwrvYnBRgY6qfDQkygYDmYwOilePFkwzv4dU8A=
+github.com/morikuni/aec v1.0.0/go.mod h1:BbKIizmSmc5MMPqRYbxO4ZU0S0+P200+tUnFx7PXmsc=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822 h1:C3w9PqII01/Oq1c1nUAm88MOHcQC9l5mIlSMApZMrHA=
+github.com/munnerz/goautoneg v0.0.0-20191010083416-a7dc8b61c822/go.mod h1:+n7T8mK8HuQTcFwEeznm/DIxMOiR9yIdICNftLE1DvQ=
+github.com/nats-io/nats.go v1.48.0 h1:pSFyXApG+yWU/TgbKCjmm5K4wrHu86231/w84qRVR+U=
+github.com/nats-io/nats.go v1.48.0/go.mod h1:iRWIPokVIFbVijxuMQq4y9ttaBTMe0SFdlZfMDd+33g=
+github.com/nats-io/nkeys v0.4.15 h1:JACV5jRVO9V856KOapQ7x+EY8Jo3qw1vJt/9Jpwzkk4=
+github.com/nats-io/nkeys v0.4.15/go.mod h1:CpMchTXC9fxA5zrMo4KpySxNjiDVvr8ANOSZdiNfUrs=
+github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=
+github.com/nats-io/nuid v1.0.1/go.mod h1:19wcPz3Ph3q0Jbyiqsd0kePYG7A95tJPxeL+1OSON2c=
+github.com/opencontainers/go-digest v1.0.0 h1:apOUWs51W5PlhuyGyz9FCeeBIOUDA/6nW8Oi/yOhh5U=
+github.com/opencontainers/go-digest v1.0.0/go.mod h1:0JzlMkj0TRzQZfJkVvzbP0HBR3IKzErnv2BNG4W4MAM=
+github.com/opencontainers/image-spec v1.1.0 h1:8SG7/vwALn54lVB/0yZ/MMwhFrPYtpEHQb2IpWsCzug=
+github.com/opencontainers/image-spec v1.1.0/go.mod h1:W4s4sFTMaBeK1BQLXbG4AdM2szdn85PY75RI83NrTrM=
+github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
+github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 h1:o4JXh1EVt9k/+g42oCprj/FisM4qX9L3sZB3upGN2ZU=
+github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55/go.mod h1:OmDBASR4679mdNQnz2pUhc2G8CO2JrUAVFDRBDP/hJE=
+github.com/prometheus/client_golang v1.23.2 h1:Je96obch5RDVy3FDMndoUsjAhG5Edi49h0RJWRi/o0o=
+github.com/prometheus/client_golang v1.23.2/go.mod h1:Tb1a6LWHB3/SPIzCoaDXI4I8UHKeFTEQ1YCr+0Gyqmg=
+github.com/prometheus/client_model v0.6.2 h1:oBsgwpGs7iVziMvrGhE53c/GrLUsZdHnqNwqPLxwZyk=
+github.com/prometheus/client_model v0.6.2/go.mod h1:y3m2F6Gdpfy6Ut/GBsUqTWZqCUvMVzSfMLjcu6wAwpE=
+github.com/prometheus/common v0.67.5 h1:pIgK94WWlQt1WLwAC5j2ynLaBRDiinoAb86HZHTUGI4=
+github.com/prometheus/common v0.67.5/go.mod h1:SjE/0MzDEEAyrdr5Gqc6G+sXI67maCxzaT3A2+HqjUw=
+github.com/prometheus/procfs v0.19.2 h1:zUMhqEW66Ex7OXIiDkll3tl9a1ZdilUOd/F6ZXw4Vws=
+github.com/prometheus/procfs v0.19.2/go.mod h1:M0aotyiemPhBCM0z5w87kL22CxfcH05ZpYlu+b4J7mw=
+github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8=
+github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
+github.com/shirou/gopsutil v3.21.11+incompatible h1:+1+c1VGhc88SSonWP6foOcLhvnKlUeu/erjjvaPEYiI=
+github.com/shirou/gopsutil/v3 v3.24.5 h1:i0t8kL+kQTvpAYToeuiVk3TgDeKOFioZO3Ztz/iZ9pI=
+github.com/shirou/gopsutil/v3 v3.24.5/go.mod h1:bsoOS1aStSs9ErQ1WWfxllSeS1K5D+U30r2NfcubMVk=
+github.com/shoenig/go-m1cpu v0.1.6 h1:nxdKQNcEB6vzgA2E2bvzKIYRuNj7XNJ4S/aRSwKzFtM=
+github.com/shoenig/go-m1cpu v0.1.6/go.mod h1:1JJMcUBvfNwpq05QDQVAnx3gUHr9IYF7GNg9SUEw2VQ=
+github.com/shopspring/decimal v1.4.0 h1:bxl37RwXBklmTi0C79JfXCEBD1cqqHt0bbgBAGFp81k=
+github.com/shopspring/decimal v1.4.0/go.mod h1:gawqmDU56v4yIKSwfBSFip1HdCCXN8/+DMd9qYNcwME=
+github.com/sirupsen/logrus v1.9.3 h1:dueUQJ1C2q9oE3F7wvmSGAaVtTmUizReu6fjN8uqzbQ=
+github.com/sirupsen/logrus v1.9.3/go.mod h1:naHLuLoDiP4jHNo9R0sCBMtWGeIprob74mVsIT4qYEQ=
+github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
+github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/testcontainers/testcontainers-go v0.33.0 h1:zJS9PfXYT5O0ZFXM2xxXfk4J5UMw/kRiISng037Gxdw=
+github.com/testcontainers/testcontainers-go v0.33.0/go.mod h1:W80YpTa8D5C3Yy16icheD01UTDu+LmXIA2Keo+jWtT8=
+github.com/testcontainers/testcontainers-go/modules/mongodb v0.33.0 h1:iXVA84s5hKMS5gn01GWOYHE3ymy/2b+0YkpFeTxB2XY=
+github.com/testcontainers/testcontainers-go/modules/mongodb v0.33.0/go.mod h1:R6tMjTojRiaoo89fh/hf7tOmfzohdqSU17R9DwSVSog=
+github.com/tklauser/go-sysconf v0.3.16 h1:frioLaCQSsF5Cy1jgRBrzr6t502KIIwQ0MArYICU0nA=
+github.com/tklauser/go-sysconf v0.3.16/go.mod h1:/qNL9xxDhc7tx3HSRsLWNnuzbVfh3e7gh/BmM179nYI=
+github.com/tklauser/numcpus v0.11.0 h1:nSTwhKH5e1dMNsCdVBukSZrURJRoHbSEQjdEbY+9RXw=
+github.com/tklauser/numcpus v0.11.0/go.mod h1:z+LwcLq54uWZTX0u/bGobaV34u6V7KNlTZejzM6/3MQ=
+github.com/xdg-go/pbkdf2 v1.0.0 h1:Su7DPu48wXMwC3bs7MCNG+z4FhcyEuz5dlvchbq0B0c=
+github.com/xdg-go/pbkdf2 v1.0.0/go.mod h1:jrpuAogTd400dnrH08LKmI/xc1MbPOebTwRqcT5RDeI=
+github.com/xdg-go/scram v1.2.0 h1:bYKF2AEwG5rqd1BumT4gAnvwU/M9nBp2pTSxeZw7Wvs=
+github.com/xdg-go/scram v1.2.0/go.mod h1:3dlrS0iBaWKYVt2ZfA4cj48umJZ+cAEbR6/SjLA88I8=
+github.com/xdg-go/stringprep v1.0.4 h1:XLI/Ng3O1Atzq0oBs3TWm+5ZVgkq2aqdlvP9JtoZ6c8=
+github.com/xdg-go/stringprep v1.0.4/go.mod h1:mPGuuIYwz7CmR2bT9j4GbQqutWS1zV24gijq1dTyGkM=
+github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78 h1:ilQV1hzziu+LLM3zUTJ0trRztfwgjqKnBWNtSRkbmwM=
+github.com/youmark/pkcs8 v0.0.0-20240726163527-a2c0da244d78/go.mod h1:aL8wCCfTfSfmXjznFBSZNN13rSJjlIOI1fUNAtF7rmI=
+github.com/yuin/goldmark v1.4.13/go.mod h1:6yULJ656Px+3vBD8DxQVa3kxgyrAnzto9xy5taEt/CY=
+github.com/yusufpapurcu/wmi v1.2.4 h1:zFUKzehAFReQwLys1b/iSMl+JQGSCSjtVqQn9bBrPo0=
+github.com/yusufpapurcu/wmi v1.2.4/go.mod h1:SBZ9tNy3G9/m5Oi98Zks0QjeHVDvuK0qfxQmPyzfmi0=
+go.mongodb.org/mongo-driver/v2 v2.5.0 h1:yXUhImUjjAInNcpTcAlPHiT7bIXhshCTL3jVBkF3xaE=
+go.mongodb.org/mongo-driver/v2 v2.5.0/go.mod h1:yOI9kBsufol30iFsl1slpdq1I0eHPzybRWdyYUs8K/0=
+go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
+go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.56.0 h1:UP6IpuHFkUgOQL9FFQFrZ+5LiwhhYRbi7VZSIx6Nj5s=
+go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.56.0/go.mod h1:qxuZLtbq5QDtdeSHsS7bcf6EH6uO6jUAgk764zd3rhM=
+go.opentelemetry.io/otel v1.38.0 h1:RkfdswUDRimDg0m2Az18RKOsnI8UDzppJAtj01/Ymk8=
+go.opentelemetry.io/otel v1.38.0/go.mod h1:zcmtmQ1+YmQM9wrNsTGV/q/uyusom3P8RxwExxkZhjM=
+go.opentelemetry.io/otel/metric v1.38.0 h1:Kl6lzIYGAh5M159u9NgiRkmoMKjvbsKtYRwgfrA6WpA=
+go.opentelemetry.io/otel/metric v1.38.0/go.mod h1:kB5n/QoRM8YwmUahxvI3bO34eVtQf2i4utNVLr9gEmI=
+go.opentelemetry.io/otel/sdk v1.38.0 h1:l48sr5YbNf2hpCUj/FoGhW9yDkl+Ma+LrVl8qaM5b+E=
+go.opentelemetry.io/otel/sdk v1.38.0/go.mod h1:ghmNdGlVemJI3+ZB5iDEuk4bWA3GkTpW+DOoZMYBVVg=
+go.opentelemetry.io/otel/sdk/metric v1.38.0 h1:aSH66iL0aZqo//xXzQLYozmWrXxyFkBJ6qT5wthqPoM=
+go.opentelemetry.io/otel/sdk/metric v1.38.0/go.mod h1:dg9PBnW9XdQ1Hd6ZnRz689CbtrUp0wMMs9iPcgT9EZA=
+go.opentelemetry.io/otel/trace v1.38.0 h1:Fxk5bKrDZJUH+AMyyIXGcFAPah0oRcT+LuNtJrmcNLE=
+go.opentelemetry.io/otel/trace v1.38.0/go.mod h1:j1P9ivuFsTceSWe1oY+EeW3sc+Pp42sO++GHkg4wwhs=
+go.uber.org/goleak v1.3.0 h1:2K3zAYmnTNqV73imy9J1T3WC+gmCePx2hEGkimedGto=
+go.uber.org/goleak v1.3.0/go.mod h1:CoHD4mav9JJNrW/WLlf7HGZPjdw8EucARQHekz1X6bE=
+go.uber.org/multierr v1.11.0 h1:blXXJkSxSSfBVBlC76pxqeO+LN3aDfLQo+309xJstO0=
+go.uber.org/multierr v1.11.0/go.mod h1:20+QtiLqy0Nd6FdQB9TLXag12DsQkrbs3htMFfDN80Y=
+go.uber.org/zap v1.27.1 h1:08RqriUEv8+ArZRYSTXy1LeBScaMpVSTBhCeaZYfMYc=
+go.uber.org/zap v1.27.1/go.mod h1:GB2qFLM7cTU87MWRP2mPIjqfIDnGu+VIO4V/SdhGo2E=
+go.yaml.in/yaml/v2 v2.4.3 h1:6gvOSjQoTB3vt1l+CU+tSyi/HOjfOjRLJ4YwYZGwRO0=
+go.yaml.in/yaml/v2 v2.4.3/go.mod h1:zSxWcmIDjOzPXpjlTTbAsKokqkDNAVtZO0WOMiT90s8=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20210921155107-089bfa567519/go.mod h1:GvvjBRRGRdwPK5ydBHafDWAxML/pGHZbMvKqRZ5+Abc=
+golang.org/x/crypto v0.48.0 h1:/VRzVqiRSggnhY7gNRxPauEQ5Drw9haKdM0jqfcCFts=
+golang.org/x/crypto v0.48.0/go.mod h1:r0kV5h3qnFPlQnBSrULhlsRfryS2pmewsg+XfMgkVos=
+golang.org/x/mod v0.6.0-dev.0.20220419223038-86c51ed26bb4/go.mod h1:jJ57K6gSWd91VN4djpZkiMVwK6gcyfeH4XE8wZrZaV4=
+golang.org/x/net v0.0.0-20190311183353-d8887717615a/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20210226172049-e18ecbb05110/go.mod h1:m0MpNAwzfU5UDzcl9v0D8zg8gWTRqZa9RBIspLL5mdg=
+golang.org/x/net v0.0.0-20220722155237-a158d28d115b/go.mod h1:XRhObCWvk6IyKnWLug+ECip1KBveYUHfp+8e9klMJ9c=
+golang.org/x/net v0.50.0 h1:ucWh9eiCGyDR3vtzso0WMQinm2Dnt8cFMuQa9K33J60=
+golang.org/x/net v0.50.0/go.mod h1:UgoSli3F/pBgdJBHCTc+tp3gmrU4XswgGRgtnwWTfyM=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20220722155255-886fb9371eb4/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.19.0 h1:vV+1eWNmZ5geRlYjzm2adRgW2/mcpevXNg50YZtPCE4=
+golang.org/x/sync v0.19.0/go.mod h1:9KTHXmSnoGruLpwFjVSX0lNNA75CykiMECbovNTZqGI=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20201119102817-f84b799fce68/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.41.0 h1:Ivj+2Cp/ylzLiEU89QhWblYnOE9zerudt9Ftecq2C6k=
+golang.org/x/sys v0.41.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/term v0.0.0-20201126162022-7de9c90e9dd1/go.mod h1:bj7SfCRtBDWHUb9snDiAeCFNEtKQo2Wmx5Cou7ajbmo=
+golang.org/x/term v0.0.0-20210927222741-03fcf44c2211/go.mod h1:jbD1KX2456YbFQfuXm/mYQcufACuNUgVhRMnK/tPxf8=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/text v0.3.7/go.mod h1:u+2+/6zg+i71rQMx5EYifcz6MCKuco9NR6JIITiCfzQ=
+golang.org/x/text v0.3.8/go.mod h1:E6s5w1FMmriuDzIBO73fBruAKo1PCIq6d2Q6DHfQ8WQ=
+golang.org/x/text v0.34.0 h1:oL/Qq0Kdaqxa1KbNeMKwQq0reLCCaFtqu2eNuSeNHbk=
+golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20190425150028-36563e24a262/go.mod h1:RgjU9mgBXZiqYHBnxXauZ1Gv1EHHAz9KjViQ78xBX0Q=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.1.12/go.mod h1:hNGJHUnrk76NpqgfD5Aqm5Crs+Hm0VOH/i9J2+nxYbc=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+gonum.org/v1/gonum v0.16.0 h1:5+ul4Swaf3ESvrOnidPp4GZbzf0mxVQpDCYUQE7OJfk=
+gonum.org/v1/gonum v0.16.0/go.mod h1:fef3am4MQ93R2HHpKnLk4/Tbh/s0+wqD5nfa6Pnwy4E=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260209200024-4cfbd4190f57 h1:mWPCjDEyshlQYzBpMNHaEof6UX1PmHcaUODUywQ0uac=
+google.golang.org/genproto/googleapis/rpc v0.0.0-20260209200024-4cfbd4190f57/go.mod h1:j9x/tPzZkyxcgEFkiKEEGxfvyumM01BEtsW8xzOahRQ=
+google.golang.org/grpc v1.78.0 h1:K1XZG/yGDJnzMdd/uZHAkVqJE+xIDOcmdSFZkBUicNc=
+google.golang.org/grpc v1.78.0/go.mod h1:I47qjTo4OKbMkjA/aOOwxDIiPSBofUtQUI5EfpWvW7U=
+google.golang.org/protobuf v1.36.11 h1:fV6ZwhNocDyBLK0dj+fg8ektcVegBBuEolpbTQyBNVE=
+google.golang.org/protobuf v1.36.11/go.mod h1:HTf+CrKn2C3g5S8VImy6tdcUvCska2kB7j23XfzDpco=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c h1:Hei/4ADfdWqJk1ZMxUNpqntNwaWcugrBjAiHlqqRiVk=
+gopkg.in/check.v1 v1.0.0-20201130134442-10cb98267c6c/go.mod h1:JHkPIbrfpd72SG/EVd6muEfDQjcINNoR0C8j2r3qZ4Q=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

api/payments/quotation/internal/appversion/version.go

@@ -0,0 +1,28 @@
+package appversion
+
+import (
+	"github.com/tech/sendico/pkg/version"
+	vf "github.com/tech/sendico/pkg/version/factory"
+)
+
+// Build information populated via ldflags.
+var (
+	Version   string
+	Revision  string
+	Branch    string
+	BuildUser string
+	BuildDate string
+)
+
+// Create returns a printer configured for the payment quotation service.
+func Create() version.Printer {
+	vi := version.Info{
+		Program:   "Sendico Payment Quotation Service",
+		Revision:  Revision,
+		Branch:    Branch,
+		BuildUser: BuildUser,
+		BuildDate: BuildDate,
+		Version:   Version,
+	}
+	return vf.Create(&vi)
+}

api/payments/quotation/internal/server/internal/config.go

@@ -0,0 +1,101 @@
+package serverimp
+
+import (
+	"os"
+	"strings"
+	"time"
+
+	"github.com/tech/sendico/pkg/api/routers"
+	"github.com/tech/sendico/pkg/server/grpcapp"
+	"go.uber.org/zap"
+	"gopkg.in/yaml.v3"
+)
+
+type config struct {
+	*grpcapp.Config   `yaml:",inline"`
+	Fees              clientConfig `yaml:"fees"`
+	Oracle            clientConfig `yaml:"oracle"`
+	Gateway           clientConfig `yaml:"gateway"`
+	QuoteRetentionHrs int          `yaml:"quote_retention_hours"`
+}
+
+type clientConfig struct {
+	Address           string `yaml:"address"`
+	AddressEnv        string `yaml:"address_env"`
+	DialTimeoutSecs   int    `yaml:"dial_timeout_seconds"`
+	CallTimeoutSecs   int    `yaml:"call_timeout_seconds"`
+	InsecureTransport bool   `yaml:"insecure"`
+}
+
+func (c clientConfig) resolveAddress() string {
+	if address := strings.TrimSpace(c.Address); address != "" {
+		return address
+	}
+	if env := strings.TrimSpace(c.AddressEnv); env != "" {
+		return strings.TrimSpace(os.Getenv(env))
+	}
+	return ""
+}
+
+func (c clientConfig) dialTimeout() time.Duration {
+	if c.DialTimeoutSecs <= 0 {
+		return 5 * time.Second
+	}
+	return time.Duration(c.DialTimeoutSecs) * time.Second
+}
+
+func (c clientConfig) callTimeout() time.Duration {
+	if c.CallTimeoutSecs <= 0 {
+		return 3 * time.Second
+	}
+	return time.Duration(c.CallTimeoutSecs) * time.Second
+}
+
+func (c *config) quoteRetention() time.Duration {
+	if c == nil || c.QuoteRetentionHrs <= 0 {
+		return 72 * time.Hour
+	}
+	return time.Duration(c.QuoteRetentionHrs) * time.Hour
+}
+
+func (i *Imp) loadConfig() (*config, error) {
+	data, err := os.ReadFile(i.file)
+	if err != nil {
+		i.logger.Error("Could not read configuration file", zap.String("config_file", i.file), zap.Error(err))
+		return nil, err
+	}
+
+	cfg := &config{Config: &grpcapp.Config{}}
+	if err := yaml.Unmarshal(data, cfg); err != nil {
+		i.logger.Error("Failed to parse configuration", zap.Error(err))
+		return nil, err
+	}
+
+	if cfg.Runtime == nil {
+		cfg.Runtime = &grpcapp.RuntimeConfig{ShutdownTimeoutSeconds: 15}
+	}
+
+	if cfg.GRPC == nil {
+		cfg.GRPC = &routers.GRPCConfig{
+			Network:          "tcp",
+			Address:          ":50064",
+			EnableReflection: true,
+			EnableHealth:     true,
+		}
+	} else {
+		if strings.TrimSpace(cfg.GRPC.Address) == "" {
+			cfg.GRPC.Address = ":50064"
+		}
+		if strings.TrimSpace(cfg.GRPC.Network) == "" {
+			cfg.GRPC.Network = "tcp"
+		}
+	}
+
+	if cfg.Metrics == nil {
+		cfg.Metrics = &grpcapp.MetricsConfig{Address: ":9414"}
+	} else if strings.TrimSpace(cfg.Metrics.Address) == "" {
+		cfg.Metrics.Address = ":9414"
+	}
+
+	return cfg, nil
+}

api/payments/quotation/internal/server/internal/dependencies.go

@@ -0,0 +1,107 @@
+package serverimp
+
+import (
+	"context"
+	"crypto/tls"
+	"strings"
+	"time"
+
+	oracleclient "github.com/tech/sendico/fx/oracle/client"
+	chainclient "github.com/tech/sendico/gateway/chain/client"
+	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"
+	"go.uber.org/zap"
+	"google.golang.org/grpc"
+	"google.golang.org/grpc/credentials"
+	"google.golang.org/grpc/credentials/insecure"
+)
+
+func (i *Imp) initDependencies(cfg *config) *clientDependencies {
+	deps := &clientDependencies{}
+	if cfg == nil {
+		return deps
+	}
+
+	if feesAddress := cfg.Fees.resolveAddress(); feesAddress != "" {
+		dialCtx, cancel := context.WithTimeout(context.Background(), cfg.Fees.dialTimeout())
+		conn, err := dialGRPC(dialCtx, cfg.Fees, feesAddress)
+		cancel()
+		if err != nil {
+			i.logger.Warn("Failed to dial fee engine", zap.Error(err), zap.String("address", feesAddress))
+		} else {
+			deps.feesConn = conn
+			deps.feesClient = feesv1.NewFeeEngineClient(conn)
+		}
+	}
+
+	if oracleAddress := cfg.Oracle.resolveAddress(); oracleAddress != "" {
+		client, err := oracleclient.New(context.Background(), oracleclient.Config{
+			Address:     oracleAddress,
+			DialTimeout: cfg.Oracle.dialTimeout(),
+			CallTimeout: cfg.Oracle.callTimeout(),
+			Insecure:    cfg.Oracle.InsecureTransport,
+		})
+		if err != nil {
+			i.logger.Warn("Failed to initialise oracle client", zap.Error(err), zap.String("address", oracleAddress))
+		} else {
+			deps.oracleClient = client
+		}
+	}
+
+	if gatewayAddress := cfg.Gateway.resolveAddress(); gatewayAddress != "" {
+		client, err := chainclient.New(context.Background(), chainclient.Config{
+			Address:     gatewayAddress,
+			DialTimeout: cfg.Gateway.dialTimeout(),
+			CallTimeout: cfg.Gateway.callTimeout(),
+			Insecure:    cfg.Gateway.InsecureTransport,
+		})
+		if err != nil {
+			i.logger.Warn("Failed to initialise chain gateway client", zap.Error(err), zap.String("address", gatewayAddress))
+		} else {
+			deps.gatewayClient = client
+		}
+	}
+
+	return deps
+}
+
+func (i *Imp) closeDependencies() {
+	if i.deps == nil {
+		return
+	}
+	if i.deps.oracleClient != nil {
+		_ = i.deps.oracleClient.Close()
+		i.deps.oracleClient = nil
+	}
+	if i.deps.gatewayClient != nil {
+		_ = i.deps.gatewayClient.Close()
+		i.deps.gatewayClient = nil
+	}
+	if i.deps.feesConn != nil {
+		_ = i.deps.feesConn.Close()
+		i.deps.feesConn = nil
+	}
+}
+
+func dialGRPC(ctx context.Context, cfg clientConfig, address string) (*grpc.ClientConn, error) {
+	address = strings.TrimSpace(address)
+	if ctx == nil {
+		var cancel context.CancelFunc
+		ctx, cancel = context.WithTimeout(context.Background(), 5*time.Second)
+		defer cancel()
+	}
+	if cfg.InsecureTransport {
+		return grpc.DialContext(
+			ctx,
+			address,
+			grpc.WithTransportCredentials(insecure.NewCredentials()),
+			grpc.WithBlock(),
+		)
+	}
+
+	return grpc.DialContext(
+		ctx,
+		address,
+		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})),
+		grpc.WithBlock(),
+	)
+}

api/payments/quotation/internal/server/internal/discovery.go

@@ -0,0 +1,45 @@
+package serverimp
+
+import (
+	"strings"
+
+	"github.com/tech/sendico/payments/quotation/internal/appversion"
+	"github.com/tech/sendico/pkg/discovery"
+	msg "github.com/tech/sendico/pkg/messaging"
+	"go.uber.org/zap"
+)
+
+const quotationDiscoverySender = "payment_quotation"
+
+func (i *Imp) startDiscoveryAnnouncer(cfg *config, producer msg.Producer) {
+	if i == nil || cfg == nil || producer == nil || cfg.GRPC == nil {
+		return
+	}
+
+	invokeURI := strings.TrimSpace(cfg.GRPC.DiscoveryInvokeURI())
+	if invokeURI == "" {
+		i.logger.Warn("Skipping discovery announcement: missing advertise host/port in gRPC config")
+		return
+	}
+
+	announce := discovery.Announcement{
+		Service:    "PAYMENTS_QUOTATION",
+		Operations: []string{"payment.quote", "payment.multiquote"},
+		InvokeURI:  invokeURI,
+		Version:    appversion.Create().Short(),
+	}
+
+	i.discoveryAnnouncer = discovery.NewAnnouncer(i.logger, producer, quotationDiscoverySender, announce)
+	i.discoveryAnnouncer.Start()
+	i.logger.Info("Discovery announcer started",
+		zap.String("service", announce.Service),
+		zap.String("invoke_uri", announce.InvokeURI))
+}
+
+func (i *Imp) stopDiscoveryAnnouncer() {
+	if i == nil || i.discoveryAnnouncer == nil {
+		return
+	}
+	i.discoveryAnnouncer.Stop()
+	i.discoveryAnnouncer = nil
+}

api/payments/quotation/internal/server/internal/lifecycle.go

@@ -0,0 +1,18 @@
+package serverimp
+
+import (
+	"context"
+	"time"
+)
+
+func (i *Imp) shutdownApp() {
+	if i.app != nil {
+		timeout := 15 * time.Second
+		if i.config != nil && i.config.Runtime != nil {
+			timeout = i.config.Runtime.ShutdownTimeout()
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), timeout)
+		i.app.Shutdown(ctx)
+		cancel()
+	}
+}

api/payments/quotation/internal/server/internal/serverimp.go

@@ -0,0 +1,70 @@
+package serverimp
+
+import (
+	quotesvc "github.com/tech/sendico/payments/quotation/internal/service/orchestrator"
+	"github.com/tech/sendico/payments/storage"
+	mongostorage "github.com/tech/sendico/payments/storage/mongo"
+	"github.com/tech/sendico/pkg/db"
+	msg "github.com/tech/sendico/pkg/messaging"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/server/grpcapp"
+)
+
+func Create(logger mlogger.Logger, file string, debug bool) (*Imp, error) {
+	return &Imp{
+		logger: logger.Named("server"),
+		file:   file,
+		debug:  debug,
+	}, nil
+}
+
+func (i *Imp) Shutdown() {
+	i.stopDiscoveryAnnouncer()
+	if i.service != nil {
+		i.service.Shutdown()
+	}
+	i.shutdownApp()
+	i.closeDependencies()
+}
+
+func (i *Imp) Start() error {
+	cfg, err := i.loadConfig()
+	if err != nil {
+		return err
+	}
+	i.config = cfg
+
+	i.deps = i.initDependencies(cfg)
+
+	quoteRetention := cfg.quoteRetention()
+	repoFactory := func(logger mlogger.Logger, conn *db.MongoConnection) (storage.Repository, error) {
+		return mongostorage.New(logger, conn, mongostorage.WithQuoteRetention(quoteRetention))
+	}
+
+	serviceFactory := func(logger mlogger.Logger, repo storage.Repository, producer msg.Producer) (grpcapp.Service, error) {
+		opts := []quotesvc.Option{}
+		if i.deps != nil {
+			if i.deps.feesClient != nil {
+				opts = append(opts, quotesvc.WithFeeEngine(i.deps.feesClient, cfg.Fees.callTimeout()))
+			}
+			if i.deps.oracleClient != nil {
+				opts = append(opts, quotesvc.WithOracleClient(i.deps.oracleClient))
+			}
+			if i.deps.gatewayClient != nil {
+				opts = append(opts, quotesvc.WithChainGatewayClient(i.deps.gatewayClient))
+			}
+		}
+		i.startDiscoveryAnnouncer(cfg, producer)
+		svc := quotesvc.NewQuotationService(logger, repo, opts...)
+		i.service = svc
+		return svc, nil
+	}
+
+	app, err := grpcapp.NewApp(i.logger, "payments_quotation", cfg.Config, i.debug, repoFactory, serviceFactory)
+	if err != nil {
+		return err
+	}
+	i.app = app
+
+	return i.app.Start()
+}

api/payments/quotation/internal/server/internal/types.go

@@ -0,0 +1,37 @@
+package serverimp
+
+import (
+	oracleclient "github.com/tech/sendico/fx/oracle/client"
+	chainclient "github.com/tech/sendico/gateway/chain/client"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/pkg/discovery"
+	"github.com/tech/sendico/pkg/mlogger"
+	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"
+	"github.com/tech/sendico/pkg/server/grpcapp"
+	"google.golang.org/grpc"
+)
+
+type quoteService interface {
+	grpcapp.Service
+	Shutdown()
+}
+
+type clientDependencies struct {
+	feesConn      *grpc.ClientConn
+	feesClient    feesv1.FeeEngineClient
+	oracleClient  oracleclient.Client
+	gatewayClient chainclient.Client
+}
+
+type Imp struct {
+	logger mlogger.Logger
+	file   string
+	debug  bool
+
+	config  *config
+	app     *grpcapp.App[storage.Repository]
+	service quoteService
+	deps    *clientDependencies
+
+	discoveryAnnouncer *discovery.Announcer
+}

api/payments/quotation/internal/server/server.go

@@ -0,0 +1,12 @@
+package server
+
+import (
+	serverimp "github.com/tech/sendico/payments/quotation/internal/server/internal"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/server"
+)
+
+// Create initialises the payment quotation server implementation.
+func Create(logger mlogger.Logger, file string, debug bool) (server.Application, error) {
+	return serverimp.Create(logger, file, debug)
+}

api/payments/quotation/internal/service/orchestrator/card_payout_constants.go

@@ -0,0 +1,10 @@
+package orchestrator
+
+const (
+	defaultCardGateway = "monetix"
+
+	stepCodeGasTopUp        = "gas_top_up"
+	stepCodeFundingTransfer = "funding_transfer"
+	stepCodeCardPayout      = "card_payout"
+	stepCodeFeeTransfer     = "fee_transfer"
+)

api/payments/quotation/internal/service/orchestrator/card_payout_funding.go

@@ -0,0 +1,367 @@
+package orchestrator
+
+import (
+	"context"
+	"strings"
+
+	"github.com/shopspring/decimal"
+	chainclient "github.com/tech/sendico/gateway/chain/client"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"go.uber.org/zap"
+)
+
+func (s *Service) submitCardFundingTransfers(ctx context.Context, payment *model.Payment, quote *orchestratorv1.PaymentQuote) error {
+	if payment == nil {
+		return merrors.InvalidArgument("payment is required")
+	}
+	intent := payment.Intent
+	source := intent.Source.ManagedWallet
+	if source == nil || strings.TrimSpace(source.ManagedWalletRef) == "" {
+		return merrors.InvalidArgument("card funding: source managed wallet is required")
+	}
+	route, err := s.cardRoute(defaultCardGateway)
+	if err != nil {
+		return err
+	}
+	sourceWalletRef := strings.TrimSpace(source.ManagedWalletRef)
+	fundingAddress := strings.TrimSpace(route.FundingAddress)
+	feeWalletRef := strings.TrimSpace(route.FeeWalletRef)
+
+	intentAmount := cloneMoney(intent.Amount)
+	if intentAmount == nil || strings.TrimSpace(intentAmount.GetAmount()) == "" || strings.TrimSpace(intentAmount.GetCurrency()) == "" {
+		return merrors.InvalidArgument("card funding: amount is required")
+	}
+	intentAmountProto := protoMoney(intentAmount)
+
+	payoutAmount, err := cardPayoutAmount(payment)
+	if err != nil {
+		return err
+	}
+
+	var feeAmount *paymenttypes.Money
+	if quote != nil {
+		feeAmount = moneyFromProto(quote.GetExpectedFeeTotal())
+	}
+	if feeAmount == nil && payment.LastQuote != nil {
+		feeAmount = cloneMoney(payment.LastQuote.ExpectedFeeTotal)
+	}
+	feeDecimal := decimal.Zero
+	if feeAmount != nil && strings.TrimSpace(feeAmount.GetAmount()) != "" {
+		if strings.TrimSpace(feeAmount.GetCurrency()) == "" {
+			return merrors.InvalidArgument("card funding: fee currency is required")
+		}
+		feeDecimal, err = decimalFromMoney(feeAmount)
+		if err != nil {
+			return err
+		}
+	}
+	feeRequired := feeDecimal.IsPositive()
+	feeAmountProto := protoMoney(feeAmount)
+
+	network := networkFromEndpoint(intent.Source)
+	instanceID := strings.TrimSpace(intent.Source.InstanceID)
+	actions := []model.RailOperation{model.RailOperationSend}
+	if feeRequired {
+		actions = append(actions, model.RailOperationFee)
+	}
+	chainClient, _, err := s.resolveChainGatewayClient(ctx, network, intentAmount, actions, instanceID, payment.PaymentRef)
+	if err != nil {
+		s.logger.Warn("card funding gateway resolution failed", zap.Error(err), zap.String("payment_ref", payment.PaymentRef))
+		return err
+	}
+
+	fundingDest := &chainv1.TransferDestination{
+		Destination: &chainv1.TransferDestination_ExternalAddress{ExternalAddress: fundingAddress},
+	}
+	fundingFee, err := s.estimateTransferNetworkFee(ctx, chainClient, sourceWalletRef, fundingDest, intentAmountProto)
+	if err != nil {
+		return err
+	}
+
+	var feeTransferFee *moneyv1.Money
+	if feeRequired {
+		if feeWalletRef == "" {
+			return merrors.InvalidArgument("card funding: fee wallet ref is required when fee exists")
+		}
+		feeDest := &chainv1.TransferDestination{
+			Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: feeWalletRef},
+		}
+		feeTransferFee, err = s.estimateTransferNetworkFee(ctx, chainClient, sourceWalletRef, feeDest, feeAmountProto)
+		if err != nil {
+			return err
+		}
+	}
+
+	totalFee, gasCurrency, err := sumNetworkFees(fundingFee, feeTransferFee)
+	if err != nil {
+		return err
+	}
+
+	var estimatedTotalFee *moneyv1.Money
+	if gasCurrency != "" && !totalFee.IsNegative() {
+		estimatedTotalFee = makeMoney(gasCurrency, totalFee)
+	}
+
+	var topUpMoney *moneyv1.Money
+	var topUpFee *moneyv1.Money
+	topUpPositive := false
+	if estimatedTotalFee != nil {
+		computeResp, err := chainClient.ComputeGasTopUp(ctx, &chainv1.ComputeGasTopUpRequest{
+			WalletRef:         sourceWalletRef,
+			EstimatedTotalFee: estimatedTotalFee,
+		})
+		if err != nil {
+			s.logger.Warn("card funding gas top-up compute failed", zap.Error(err), zap.String("payment_ref", payment.PaymentRef))
+			return err
+		}
+		if computeResp != nil {
+			topUpMoney = computeResp.GetTopupAmount()
+		}
+		if topUpMoney != nil && strings.TrimSpace(topUpMoney.GetAmount()) != "" {
+			amountDec, err := decimalFromMoney(topUpMoney)
+			if err != nil {
+				return err
+			}
+			topUpPositive = amountDec.IsPositive()
+		}
+		if topUpMoney != nil && topUpPositive {
+			if strings.TrimSpace(topUpMoney.GetCurrency()) == "" {
+				return merrors.InvalidArgument("card funding: gas top-up currency is required")
+			}
+			if feeWalletRef == "" {
+				return merrors.InvalidArgument("card funding: fee wallet ref is required for gas top-up")
+			}
+			topUpDest := &chainv1.TransferDestination{
+				Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: sourceWalletRef},
+			}
+			topUpFee, err = s.estimateTransferNetworkFee(ctx, chainClient, feeWalletRef, topUpDest, topUpMoney)
+			if err != nil {
+				return err
+			}
+		}
+	}
+
+	plan := ensureExecutionPlan(payment)
+	var gasStep *model.ExecutionStep
+	var feeStep *model.ExecutionStep
+	if topUpMoney != nil && topUpPositive {
+		gasStep = ensureExecutionStep(plan, stepCodeGasTopUp)
+		setExecutionStepRole(gasStep, executionStepRoleSource)
+		setExecutionStepStatus(gasStep, model.OperationStatePlanned)
+		gasStep.Description = "Top up native gas from fee wallet"
+		gasStep.Amount = moneyFromProto(topUpMoney)
+		gasStep.NetworkFee = moneyFromProto(topUpFee)
+		gasStep.SourceWalletRef = feeWalletRef
+		gasStep.DestinationRef = sourceWalletRef
+	}
+
+	fundStep := ensureExecutionStep(plan, stepCodeFundingTransfer)
+	setExecutionStepRole(fundStep, executionStepRoleSource)
+	setExecutionStepStatus(fundStep, model.OperationStatePlanned)
+	fundStep.Description = "Transfer payout amount to card funding wallet"
+	fundStep.Amount = cloneMoney(intentAmount)
+	fundStep.NetworkFee = moneyFromProto(fundingFee)
+	fundStep.SourceWalletRef = sourceWalletRef
+	fundStep.DestinationRef = fundingAddress
+
+	if feeRequired {
+		feeStep = ensureExecutionStep(plan, stepCodeFeeTransfer)
+		setExecutionStepRole(feeStep, executionStepRoleSource)
+		setExecutionStepStatus(feeStep, model.OperationStatePlanned)
+		feeStep.Description = "Transfer fee to fee wallet"
+		feeStep.Amount = cloneMoney(feeAmount)
+		feeStep.NetworkFee = moneyFromProto(feeTransferFee)
+		feeStep.SourceWalletRef = sourceWalletRef
+		feeStep.DestinationRef = feeWalletRef
+	}
+
+	cardStep := ensureExecutionStep(plan, stepCodeCardPayout)
+	setExecutionStepRole(cardStep, executionStepRoleConsumer)
+	setExecutionStepStatus(cardStep, model.OperationStatePlanned)
+	cardStep.Description = "Submit card payout"
+	cardStep.Amount = cloneMoney(payoutAmount)
+	if card := intent.Destination.Card; card != nil {
+		if masked := strings.TrimSpace(card.MaskedPan); masked != "" {
+			cardStep.DestinationRef = masked
+		}
+	}
+
+	updateExecutionPlanTotalNetworkFee(plan)
+
+	exec := payment.Execution
+	if exec == nil {
+		exec = &model.ExecutionRefs{}
+	}
+
+	if topUpMoney != nil && topUpPositive {
+		ensureResp, gasErr := chainClient.EnsureGasTopUp(ctx, &chainv1.EnsureGasTopUpRequest{
+			IdempotencyKey:    payment.IdempotencyKey + ":card:gas",
+			OrganizationRef:   payment.OrganizationRef.Hex(),
+			IntentRef:         strings.TrimSpace(payment.Intent.Ref),
+			OperationRef:      strings.TrimSpace(cardStep.OperationRef),
+			SourceWalletRef:   feeWalletRef,
+			TargetWalletRef:   sourceWalletRef,
+			EstimatedTotalFee: estimatedTotalFee,
+			Metadata:          cloneMetadata(payment.Metadata),
+			PaymentRef:        payment.PaymentRef,
+		})
+		if gasErr != nil {
+			s.logger.Warn("card gas top-up transfer failed", zap.Error(gasErr), zap.String("payment_ref", payment.PaymentRef))
+			return gasErr
+		}
+		if gasStep != nil {
+			actual := (*moneyv1.Money)(nil)
+			if ensureResp != nil {
+				actual = ensureResp.GetTopupAmount()
+				if transfer := ensureResp.GetTransfer(); transfer != nil {
+					gasStep.TransferRef = strings.TrimSpace(transfer.GetTransferRef())
+				}
+			}
+			actualPositive := false
+			if actual != nil && strings.TrimSpace(actual.GetAmount()) != "" {
+				actualDec, err := decimalFromMoney(actual)
+				if err != nil {
+					return err
+				}
+				actualPositive = actualDec.IsPositive()
+			}
+			if actual != nil && actualPositive {
+				gasStep.Amount = moneyFromProto(actual)
+				if strings.TrimSpace(actual.GetCurrency()) == "" {
+					return merrors.InvalidArgument("card funding: gas top-up currency is required")
+				}
+				topUpDest := &chainv1.TransferDestination{
+					Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: sourceWalletRef},
+				}
+				topUpFee, err = s.estimateTransferNetworkFee(ctx, chainClient, feeWalletRef, topUpDest, actual)
+				if err != nil {
+					return err
+				}
+				gasStep.NetworkFee = moneyFromProto(topUpFee)
+				setExecutionStepStatus(gasStep, model.OperationStateWaiting)
+			} else {
+				gasStep.Amount = nil
+				gasStep.NetworkFee = nil
+				gasStep.TransferRef = ""
+				setExecutionStepStatus(gasStep, model.OperationStateSkipped)
+			}
+		}
+		if gasStep != nil {
+			s.logger.Info("card gas top-up transfer submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", gasStep.TransferRef))
+		}
+		updateExecutionPlanTotalNetworkFee(plan)
+	}
+
+	fundResp, err := chainClient.SubmitTransfer(ctx, &chainv1.SubmitTransferRequest{
+		IdempotencyKey:  payment.IdempotencyKey + ":card:fund",
+		OrganizationRef: payment.OrganizationRef.Hex(),
+		SourceWalletRef: sourceWalletRef,
+		Destination:     fundingDest,
+		Amount:          cloneProtoMoney(intentAmountProto),
+		Metadata:        cloneMetadata(payment.Metadata),
+		PaymentRef:      payment.PaymentRef,
+		IntentRef:       strings.TrimSpace(intent.Ref),
+		OperationRef:    strings.TrimSpace(cardStep.OperationRef),
+	})
+	if err != nil {
+		return err
+	}
+	if fundResp != nil && fundResp.GetTransfer() != nil {
+		exec.ChainTransferRef = strings.TrimSpace(fundResp.GetTransfer().GetTransferRef())
+		fundStep.TransferRef = exec.ChainTransferRef
+	}
+	setExecutionStepStatus(fundStep, model.OperationStateWaiting)
+	updateExecutionPlanTotalNetworkFee(plan)
+
+	if feeRequired {
+		feeResp, err := chainClient.SubmitTransfer(ctx, &chainv1.SubmitTransferRequest{
+			IntentRef:       intent.Ref,
+			OperationRef:    feeStep.OperationRef,
+			IdempotencyKey:  payment.IdempotencyKey + ":card:fee",
+			OrganizationRef: payment.OrganizationRef.Hex(),
+			SourceWalletRef: sourceWalletRef,
+			Destination: &chainv1.TransferDestination{
+				Destination: &chainv1.TransferDestination_ManagedWalletRef{ManagedWalletRef: feeWalletRef},
+			},
+			Amount:     cloneProtoMoney(feeAmountProto),
+			Metadata:   cloneMetadata(payment.Metadata),
+			PaymentRef: payment.PaymentRef,
+		})
+		if err != nil {
+			return err
+		}
+		if feeResp != nil && feeResp.GetTransfer() != nil {
+			exec.FeeTransferRef = strings.TrimSpace(feeResp.GetTransfer().GetTransferRef())
+			feeStep.TransferRef = exec.FeeTransferRef
+		}
+		setExecutionStepStatus(feeStep, model.OperationStateWaiting)
+		s.logger.Info("card fee transfer submitted", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", exec.FeeTransferRef))
+	}
+
+	payment.Execution = exec
+	return nil
+}
+
+func (s *Service) estimateTransferNetworkFee(ctx context.Context, client chainclient.Client, sourceWalletRef string, destination *chainv1.TransferDestination, amount *moneyv1.Money) (*moneyv1.Money, error) {
+	if client == nil {
+		return nil, merrors.InvalidArgument("chain gateway unavailable")
+	}
+	sourceWalletRef = strings.TrimSpace(sourceWalletRef)
+	if sourceWalletRef == "" {
+		return nil, merrors.InvalidArgument("source wallet ref is required")
+	}
+	if amount == nil || strings.TrimSpace(amount.GetAmount()) == "" || strings.TrimSpace(amount.GetCurrency()) == "" {
+		return nil, merrors.InvalidArgument("amount is required")
+	}
+
+	resp, err := client.EstimateTransferFee(ctx, &chainv1.EstimateTransferFeeRequest{
+		SourceWalletRef: sourceWalletRef,
+		Destination:     destination,
+		Amount:          cloneProtoMoney(amount),
+	})
+	if err != nil {
+		s.logger.Warn("chain gateway fee estimation failed", zap.Error(err), zap.String("source_wallet_ref", sourceWalletRef))
+		return nil, merrors.Internal("chain_gateway_fee_estimation_failed")
+	}
+	if resp == nil {
+		s.logger.Warn("chain gateway fee estimation returned empty response", zap.String("source_wallet_ref", sourceWalletRef))
+		return nil, merrors.Internal("chain_gateway_fee_estimation_failed")
+	}
+	fee := resp.GetNetworkFee()
+	if fee == nil || strings.TrimSpace(fee.GetAmount()) == "" || strings.TrimSpace(fee.GetCurrency()) == "" {
+		s.logger.Warn("chain gateway fee estimation missing network fee", zap.String("source_wallet_ref", sourceWalletRef))
+		return nil, merrors.Internal("chain_gateway_fee_estimation_failed")
+	}
+	return cloneProtoMoney(fee), nil
+}
+
+func sumNetworkFees(fees ...*moneyv1.Money) (decimal.Decimal, string, error) {
+	total := decimal.Zero
+	currency := ""
+	for _, fee := range fees {
+		if fee == nil {
+			continue
+		}
+		amount := strings.TrimSpace(fee.GetAmount())
+		feeCurrency := strings.TrimSpace(fee.GetCurrency())
+		if amount == "" || feeCurrency == "" {
+			return decimal.Zero, "", merrors.InvalidArgument("network fee is required")
+		}
+		value, err := decimalFromMoney(fee)
+		if err != nil {
+			return decimal.Zero, "", err
+		}
+		if currency == "" {
+			currency = feeCurrency
+		} else if !strings.EqualFold(currency, feeCurrency) {
+			return decimal.Zero, "", merrors.InvalidArgument("network fee currency mismatch")
+		}
+		total = total.Add(value)
+	}
+	return total, currency, nil
+}

api/payments/quotation/internal/service/orchestrator/card_payout_helpers.go

@@ -0,0 +1,80 @@
+package orchestrator
+
+import (
+	"strings"
+
+	"github.com/shopspring/decimal"
+	"github.com/tech/sendico/payments/storage/model"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+)
+
+func ensureExecutionPlan(payment *model.Payment) *model.ExecutionPlan {
+	if payment == nil {
+		return nil
+	}
+	if payment.ExecutionPlan == nil {
+		payment.ExecutionPlan = &model.ExecutionPlan{}
+	}
+	return payment.ExecutionPlan
+}
+
+func ensureExecutionStep(plan *model.ExecutionPlan, code string) *model.ExecutionStep {
+	if plan == nil {
+		return nil
+	}
+	code = strings.TrimSpace(code)
+	if code == "" {
+		return nil
+	}
+	for _, step := range plan.Steps {
+		if step == nil {
+			continue
+		}
+		if strings.EqualFold(step.Code, code) {
+			if step.Code == "" {
+				step.Code = code
+			}
+			return step
+		}
+	}
+	step := &model.ExecutionStep{Code: code}
+	plan.Steps = append(plan.Steps, step)
+	return step
+}
+
+func updateExecutionPlanTotalNetworkFee(plan *model.ExecutionPlan) {
+	if plan == nil {
+		return
+	}
+	total := decimal.Zero
+	currency := ""
+	hasFee := false
+	for _, step := range plan.Steps {
+		if step == nil || step.NetworkFee == nil {
+			continue
+		}
+		fee := step.NetworkFee
+		if strings.TrimSpace(fee.GetAmount()) == "" || strings.TrimSpace(fee.GetCurrency()) == "" {
+			continue
+		}
+		if currency == "" {
+			currency = strings.TrimSpace(fee.GetCurrency())
+		} else if !strings.EqualFold(currency, fee.GetCurrency()) {
+			continue
+		}
+		value, err := decimalFromMoney(fee)
+		if err != nil {
+			continue
+		}
+		total = total.Add(value)
+		hasFee = true
+	}
+	if !hasFee || currency == "" {
+		plan.TotalNetworkFee = nil
+		return
+	}
+	plan.TotalNetworkFee = &paymenttypes.Money{
+		Currency: currency,
+		Amount:   total.String(),
+	}
+}

api/payments/quotation/internal/service/orchestrator/card_payout_routes.go

@@ -0,0 +1,29 @@
+package orchestrator
+
+import (
+	"strings"
+
+	"github.com/tech/sendico/pkg/merrors"
+	"go.uber.org/zap"
+)
+
+func (s *Service) cardRoute(gateway string) (CardGatewayRoute, error) {
+	if len(s.deps.cardRoutes) == 0 {
+		s.logger.Warn("card routing not configured", zap.String("gateway", gateway))
+		return CardGatewayRoute{}, merrors.InvalidArgument("card routing not configured")
+	}
+	key := strings.ToLower(strings.TrimSpace(gateway))
+	if key == "" {
+		key = defaultCardGateway
+	}
+	route, ok := s.deps.cardRoutes[key]
+	if !ok {
+		s.logger.Warn("card routing missing for gateway", zap.String("gateway", key))
+		return CardGatewayRoute{}, merrors.InvalidArgument("card routing missing for gateway " + key)
+	}
+	if strings.TrimSpace(route.FundingAddress) == "" {
+		s.logger.Warn("card routing missing funding address", zap.String("gateway", key))
+		return CardGatewayRoute{}, merrors.InvalidArgument("card funding address is required for gateway " + key)
+	}
+	return route, nil
+}

api/payments/quotation/internal/service/orchestrator/card_payout_submit.go

@@ -0,0 +1,351 @@
+package orchestrator
+
+import (
+	"context"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/shopspring/decimal"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"
+	"go.uber.org/zap"
+)
+
+func (s *Service) submitCardPayout(ctx context.Context, operationRef string, payment *model.Payment) error {
+	if payment == nil {
+		return merrors.InvalidArgument("payment is required")
+	}
+	if payment.Execution != nil && strings.TrimSpace(payment.Execution.CardPayoutRef) != "" {
+		return nil
+	}
+	intent := payment.Intent
+	card := intent.Destination.Card
+	if card == nil {
+		return merrors.InvalidArgument("card payout: card endpoint is required")
+	}
+	amount, err := cardPayoutAmount(payment)
+	if err != nil {
+		return err
+	}
+	amtDec, err := decimalFromMoney(amount)
+	if err != nil {
+		return err
+	}
+	minor := amtDec.Mul(decimal.NewFromInt(100)).IntPart()
+
+	payoutID := payment.PaymentRef
+	currency := strings.TrimSpace(amount.GetCurrency())
+	holder := strings.TrimSpace(card.Cardholder)
+	meta := cloneMetadata(payment.Metadata)
+	customer := intent.Customer
+	customerID := ""
+	customerFirstName := ""
+	customerMiddleName := ""
+	customerLastName := ""
+	customerIP := ""
+	customerZip := ""
+	customerCountry := ""
+	customerState := ""
+	customerCity := ""
+	customerAddress := ""
+	if customer != nil {
+		customerID = strings.TrimSpace(customer.ID)
+		customerFirstName = strings.TrimSpace(customer.FirstName)
+		customerMiddleName = strings.TrimSpace(customer.MiddleName)
+		customerLastName = strings.TrimSpace(customer.LastName)
+		customerIP = strings.TrimSpace(customer.IP)
+		customerZip = strings.TrimSpace(customer.Zip)
+		customerCountry = strings.TrimSpace(customer.Country)
+		customerState = strings.TrimSpace(customer.State)
+		customerCity = strings.TrimSpace(customer.City)
+		customerAddress = strings.TrimSpace(customer.Address)
+	}
+	if customerFirstName == "" {
+		customerFirstName = strings.TrimSpace(card.Cardholder)
+	}
+	if customerLastName == "" {
+		customerLastName = strings.TrimSpace(card.CardholderSurname)
+	}
+	if customerID == "" {
+		return merrors.InvalidArgument("card payout: customer id is required")
+	}
+	if customerFirstName == "" {
+		return merrors.InvalidArgument("card payout: customer first name is required")
+	}
+	if customerLastName == "" {
+		return merrors.InvalidArgument("card payout: customer last name is required")
+	}
+	if customerIP == "" {
+		return merrors.InvalidArgument("card payout: customer ip is required")
+	}
+
+	var (
+		state *mntxv1.CardPayoutState
+	)
+
+	if token := strings.TrimSpace(card.Token); token != "" {
+		req := &mntxv1.CardTokenPayoutRequest{
+			PayoutId:           payoutID,
+			IdempotencyKey:     payment.IdempotencyKey,
+			CustomerId:         customerID,
+			CustomerFirstName:  customerFirstName,
+			CustomerMiddleName: customerMiddleName,
+			CustomerLastName:   customerLastName,
+			CustomerIp:         customerIP,
+			CustomerZip:        customerZip,
+			CustomerCountry:    customerCountry,
+			CustomerState:      customerState,
+			CustomerCity:       customerCity,
+			CustomerAddress:    customerAddress,
+			AmountMinor:        minor,
+			Currency:           currency,
+			CardToken:          token,
+			CardHolder:         holder,
+			MaskedPan:          strings.TrimSpace(card.MaskedPan),
+			Metadata:           meta,
+		}
+		resp, err := s.deps.mntx.client.CreateCardTokenPayout(ctx, req)
+		if err != nil {
+			s.logger.Warn("card token payout failed", zap.Error(err), zap.String("payment_ref", payment.PaymentRef))
+			return err
+		}
+		state = resp.GetPayout()
+	} else if pan := strings.TrimSpace(card.Pan); pan != "" {
+		req := &mntxv1.CardPayoutRequest{
+			PayoutId:           payoutID,
+			IdempotencyKey:     payment.IdempotencyKey,
+			CustomerId:         customerID,
+			CustomerFirstName:  customerFirstName,
+			CustomerMiddleName: customerMiddleName,
+			CustomerLastName:   customerLastName,
+			CustomerIp:         customerIP,
+			CustomerZip:        customerZip,
+			CustomerCountry:    customerCountry,
+			CustomerState:      customerState,
+			CustomerCity:       customerCity,
+			CustomerAddress:    customerAddress,
+			AmountMinor:        minor,
+			Currency:           currency,
+			CardPan:            pan,
+			CardExpYear:        card.ExpYear,
+			CardExpMonth:       card.ExpMonth,
+			CardHolder:         holder,
+			Metadata:           meta,
+			IntentRef:          payment.Intent.Ref,
+			OperationRef:       operationRef,
+		}
+		resp, err := s.deps.mntx.client.CreateCardPayout(ctx, req)
+		if err != nil {
+			s.logger.Warn("card payout failed", zap.Error(err), zap.String("payment_ref", payment.PaymentRef))
+			return err
+		}
+		state = resp.GetPayout()
+	} else {
+		return merrors.InvalidArgument("card payout: either token or pan must be provided")
+	}
+
+	if state == nil {
+		return merrors.Internal("card payout: missing payout state")
+	}
+	recordCardPayoutState(payment, state)
+	exec := payment.Execution
+	if exec == nil {
+		exec = &model.ExecutionRefs{}
+	}
+	if exec.CardPayoutRef == "" {
+		exec.CardPayoutRef = strings.TrimSpace(state.GetPayoutId())
+	}
+	payment.Execution = exec
+
+	plan := ensureExecutionPlan(payment)
+	if plan != nil {
+		step := ensureExecutionStep(plan, stepCodeCardPayout)
+		setExecutionStepRole(step, executionStepRoleConsumer)
+		step.Description = "Submit card payout"
+		step.Amount = cloneMoney(amount)
+		if masked := strings.TrimSpace(card.MaskedPan); masked != "" {
+			step.DestinationRef = masked
+		}
+		if exec.CardPayoutRef != "" {
+			step.TransferRef = exec.CardPayoutRef
+		}
+		setExecutionStepStatus(step, model.OperationStateWaiting)
+		updateExecutionPlanTotalNetworkFee(plan)
+	}
+
+	s.logger.Info("card payout submitted", zap.String("payment_ref", payment.PaymentRef),
+		zap.String("payout_id", exec.CardPayoutRef), zap.String("operation_ref", state.OperationRef))
+
+	return nil
+}
+
+func recordCardPayoutState(payment *model.Payment, state *mntxv1.CardPayoutState) {
+	if payment == nil || state == nil {
+		return
+	}
+	if payment.CardPayout == nil {
+		payment.CardPayout = &model.CardPayout{}
+	}
+	payment.CardPayout.PayoutRef = strings.TrimSpace(state.GetPayoutId())
+	payment.CardPayout.ProviderPaymentID = strings.TrimSpace(state.GetProviderPaymentId())
+	payment.CardPayout.Status = state.GetStatus().String()
+	payment.CardPayout.FailureReason = strings.TrimSpace(state.GetProviderMessage())
+	payment.CardPayout.ProviderCode = strings.TrimSpace(state.GetProviderCode())
+	if payment.CardPayout.CardCountry == "" && payment.Intent.Destination.Card != nil {
+		payment.CardPayout.CardCountry = strings.TrimSpace(payment.Intent.Destination.Card.Country)
+	}
+	if payment.CardPayout.MaskedPan == "" && payment.Intent.Destination.Card != nil {
+		payment.CardPayout.MaskedPan = strings.TrimSpace(payment.Intent.Destination.Card.MaskedPan)
+	}
+	payment.CardPayout.GatewayReference = strings.TrimSpace(state.GetPayoutId())
+}
+
+func updateCardPayoutPlanSteps(payment *model.Payment, payout *mntxv1.CardPayoutState) bool {
+	if payment == nil || payout == nil || payment.PaymentPlan == nil {
+		return false
+	}
+	plan := ensureExecutionPlanForPlan(payment, payment.PaymentPlan)
+	if plan == nil {
+		return false
+	}
+	payoutID := strings.TrimSpace(payout.GetPayoutId())
+	if payoutID == "" {
+		return false
+	}
+
+	updated := false
+	for idx, planStep := range payment.PaymentPlan.Steps {
+		if planStep == nil {
+			continue
+		}
+		if planStep.Rail != model.RailCardPayout {
+			continue
+		}
+		if planStep.Action != model.RailOperationSend && planStep.Action != model.RailOperationObserveConfirm {
+			continue
+		}
+		if idx >= len(plan.Steps) {
+			continue
+		}
+		execStep := plan.Steps[idx]
+		if execStep == nil {
+			execStep = &model.ExecutionStep{
+				Code:         planStepID(planStep, idx),
+				Description:  describePlanStep(planStep),
+				OperationRef: uuid.New().String(),
+				State:        model.OperationStateCreated,
+			}
+			plan.Steps[idx] = execStep
+		}
+		if execStep.TransferRef == "" {
+			execStep.TransferRef = payoutID
+		}
+		switch payout.GetStatus() {
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_CREATED:
+			setExecutionStepStatus(execStep, model.OperationStateCreated)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_WAITING:
+			setExecutionStepStatus(execStep, model.OperationStateWaiting)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_SUCCESS:
+			setExecutionStepStatus(execStep, model.OperationStateSuccess)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_FAILED:
+			setExecutionStepStatus(execStep, model.OperationStateFailed)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_CANCELLED:
+			setExecutionStepStatus(execStep, model.OperationStateCancelled)
+
+		default:
+			setExecutionStepStatus(execStep, model.OperationStatePlanned)
+		}
+		updated = true
+	}
+	return updated
+}
+
+func applyCardPayoutUpdate(payment *model.Payment, payout *mntxv1.CardPayoutState) {
+	if payment == nil || payout == nil {
+		return
+	}
+	recordCardPayoutState(payment, payout)
+
+	if payment.Execution == nil {
+		payment.Execution = &model.ExecutionRefs{}
+	}
+	if payment.Execution.CardPayoutRef == "" {
+		payment.Execution.CardPayoutRef = strings.TrimSpace(payout.GetPayoutId())
+	}
+
+	updated := updateCardPayoutPlanSteps(payment, payout)
+	plan := ensureExecutionPlan(payment)
+	if plan != nil && !updated {
+		step := findExecutionStepByTransferRef(plan, strings.TrimSpace(payout.GetPayoutId()))
+		if step == nil {
+			step = ensureExecutionStep(plan, stepCodeCardPayout)
+			setExecutionStepRole(step, executionStepRoleConsumer)
+			if step.TransferRef == "" {
+				step.TransferRef = payment.Execution.CardPayoutRef
+			}
+		}
+		switch payout.GetStatus() {
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_CREATED:
+			setExecutionStepStatus(step, model.OperationStatePlanned)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_WAITING:
+			setExecutionStepStatus(step, model.OperationStateWaiting)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_SUCCESS:
+			setExecutionStepStatus(step, model.OperationStateSuccess)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_FAILED:
+			setExecutionStepStatus(step, model.OperationStateFailed)
+
+		case mntxv1.PayoutStatus_PAYOUT_STATUS_CANCELLED:
+			setExecutionStepStatus(step, model.OperationStateCancelled)
+
+		default:
+			setExecutionStepStatus(step, model.OperationStatePlanned)
+		}
+
+	}
+
+	switch payout.GetStatus() {
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_SUCCESS:
+		payment.FailureCode = model.PaymentFailureCodeUnspecified
+		payment.FailureReason = ""
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_FAILED:
+		payment.FailureCode = model.PaymentFailureCodePolicy
+		payment.FailureReason = strings.TrimSpace(payout.GetProviderMessage())
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_CANCELLED:
+		payment.FailureCode = model.PaymentFailureCodePolicy
+		payment.FailureReason = "payout cancelled"
+
+	default:
+		// CREATED / WAITING — keep as is
+	}
+}
+
+func cardPayoutAmount(payment *model.Payment) (*paymenttypes.Money, error) {
+	if payment == nil {
+		return nil, merrors.InvalidArgument("payment is required")
+	}
+	amount := cloneMoney(payment.Intent.Amount)
+	if payment.LastQuote != nil {
+		settlement := payment.LastQuote.ExpectedSettlementAmount
+		if settlement != nil && strings.TrimSpace(settlement.GetAmount()) != "" && strings.TrimSpace(settlement.GetCurrency()) != "" {
+			amount = cloneMoney(settlement)
+		}
+	}
+	if amount == nil || strings.TrimSpace(amount.GetAmount()) == "" || strings.TrimSpace(amount.GetCurrency()) == "" {
+		return nil, merrors.InvalidArgument("card payout: amount is required")
+	}
+	return amount, nil
+}

api/payments/quotation/internal/service/orchestrator/command_factory.go

@@ -0,0 +1,97 @@
+package orchestrator
+
+import (
+	"context"
+	"time"
+
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/mlogger"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+)
+
+type paymentEngine interface {
+	EnsureRepository(ctx context.Context) error
+	BuildPaymentQuote(ctx context.Context, orgRef string, req *orchestratorv1.QuotePaymentRequest) (*orchestratorv1.PaymentQuote, time.Time, error)
+	ResolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, *orchestratorv1.PaymentIntent, error)
+	ExecutePayment(ctx context.Context, store storage.PaymentsStore, payment *model.Payment, quote *orchestratorv1.PaymentQuote) error
+	Repository() storage.Repository
+}
+
+type defaultPaymentEngine struct {
+	svc *Service
+}
+
+func (e defaultPaymentEngine) EnsureRepository(ctx context.Context) error {
+	return e.svc.ensureRepository(ctx)
+}
+
+func (e defaultPaymentEngine) BuildPaymentQuote(ctx context.Context, orgRef string, req *orchestratorv1.QuotePaymentRequest) (*orchestratorv1.PaymentQuote, time.Time, error) {
+	return e.svc.buildPaymentQuote(ctx, orgRef, req)
+}
+
+func (e defaultPaymentEngine) ResolvePaymentQuote(ctx context.Context, in quoteResolutionInput) (*orchestratorv1.PaymentQuote, *orchestratorv1.PaymentIntent, error) {
+	return e.svc.resolvePaymentQuote(ctx, in)
+}
+
+func (e defaultPaymentEngine) ExecutePayment(ctx context.Context, store storage.PaymentsStore, payment *model.Payment, quote *orchestratorv1.PaymentQuote) error {
+	return e.svc.executePayment(ctx, store, payment, quote)
+}
+
+func (e defaultPaymentEngine) Repository() storage.Repository {
+	return e.svc.storage
+}
+
+type paymentCommandFactory struct {
+	engine paymentEngine
+	logger mlogger.Logger
+}
+
+func newPaymentCommandFactory(engine paymentEngine, logger mlogger.Logger) *paymentCommandFactory {
+	return &paymentCommandFactory{
+		engine: engine,
+		logger: logger.Named("commands"),
+	}
+}
+
+func (f *paymentCommandFactory) QuotePayment() *quotePaymentCommand {
+	return &quotePaymentCommand{
+		engine: f.engine,
+		logger: f.logger.Named("quote_payment"),
+	}
+}
+
+func (f *paymentCommandFactory) QuotePayments() *quotePaymentsCommand {
+	return &quotePaymentsCommand{
+		engine: f.engine,
+		logger: f.logger.Named("quote_payments"),
+	}
+}
+
+func (f *paymentCommandFactory) InitiatePayment() *initiatePaymentCommand {
+	return &initiatePaymentCommand{
+		engine: f.engine,
+		logger: f.logger.Named("initiate_payment"),
+	}
+}
+
+func (f *paymentCommandFactory) InitiatePayments() *initiatePaymentsCommand {
+	return &initiatePaymentsCommand{
+		engine: f.engine,
+		logger: f.logger.Named("initiate_payments"),
+	}
+}
+
+func (f *paymentCommandFactory) CancelPayment() *cancelPaymentCommand {
+	return &cancelPaymentCommand{
+		engine: f.engine,
+		logger: f.logger.Named("cancel_payment"),
+	}
+}
+
+func (f *paymentCommandFactory) InitiateConversion() *initiateConversionCommand {
+	return &initiateConversionCommand{
+		engine: f.engine,
+		logger: f.logger.Named("initiate_conversion"),
+	}
+}

api/payments/quotation/internal/service/orchestrator/composite_gateway_registry.go

@@ -0,0 +1,64 @@
+package orchestrator
+
+import (
+	"context"
+	"sort"
+
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/mlogger"
+	"go.uber.org/zap"
+)
+
+type compositeGatewayRegistry struct {
+	logger     mlogger.Logger
+	registries []GatewayRegistry
+}
+
+func NewCompositeGatewayRegistry(logger mlogger.Logger, registries ...GatewayRegistry) GatewayRegistry {
+	items := make([]GatewayRegistry, 0, len(registries))
+	for _, registry := range registries {
+		if registry != nil {
+			items = append(items, registry)
+		}
+	}
+	if len(items) == 0 {
+		return nil
+	}
+	if logger != nil {
+		logger = logger.Named("gateway_registry")
+	}
+	return &compositeGatewayRegistry{
+		logger:     logger,
+		registries: items,
+	}
+}
+
+func (r *compositeGatewayRegistry) List(ctx context.Context) ([]*model.GatewayInstanceDescriptor, error) {
+	if r == nil || len(r.registries) == 0 {
+		return nil, nil
+	}
+	items := map[string]*model.GatewayInstanceDescriptor{}
+	for _, registry := range r.registries {
+		list, err := registry.List(ctx)
+		if err != nil {
+			if r.logger != nil {
+				r.logger.Warn("Failed to list gateway registry", zap.Error(err))
+			}
+			continue
+		}
+		for _, entry := range list {
+			if entry == nil || entry.ID == "" {
+				continue
+			}
+			items[entry.ID] = entry
+		}
+	}
+	result := make([]*model.GatewayInstanceDescriptor, 0, len(items))
+	for _, entry := range items {
+		result = append(result, entry)
+	}
+	sort.Slice(result, func(i, j int) bool {
+		return result[i].ID < result[j].ID
+	})
+	return result, nil
+}

api/payments/quotation/internal/service/orchestrator/convert.go

@@ -0,0 +1,947 @@
+package orchestrator
+
+import (
+	"strings"
+	"time"
+
+	"github.com/tech/sendico/payments/storage/model"
+	chainasset "github.com/tech/sendico/pkg/chain"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"
+	accountingv1 "github.com/tech/sendico/pkg/proto/common/accounting/v1"
+	fxv1 "github.com/tech/sendico/pkg/proto/common/fx/v1"
+	gatewayv1 "github.com/tech/sendico/pkg/proto/common/gateway/v1"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+	oraclev1 "github.com/tech/sendico/pkg/proto/oracle/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"google.golang.org/protobuf/types/known/timestamppb"
+)
+
+func intentFromProto(src *orchestratorv1.PaymentIntent) model.PaymentIntent {
+	if src == nil {
+		return model.PaymentIntent{}
+	}
+	intent := model.PaymentIntent{
+		Ref:                src.GetRef(),
+		Kind:               modelKindFromProto(src.GetKind()),
+		Source:             endpointFromProto(src.GetSource()),
+		Destination:        endpointFromProto(src.GetDestination()),
+		Amount:             moneyFromProto(src.GetAmount()),
+		RequiresFX:         src.GetRequiresFx(),
+		FeePolicy:          feePolicyFromProto(src.GetFeePolicy()),
+		SettlementMode:     settlementModeFromProto(src.GetSettlementMode()),
+		SettlementCurrency: strings.TrimSpace(src.GetSettlementCurrency()),
+		Attributes:         cloneMetadata(src.GetAttributes()),
+		Customer:           customerFromProto(src.GetCustomer()),
+	}
+	if src.GetFx() != nil {
+		intent.FX = fxIntentFromProto(src.GetFx())
+	}
+	return intent
+}
+
+func endpointFromProto(src *orchestratorv1.PaymentEndpoint) model.PaymentEndpoint {
+	if src == nil {
+		return model.PaymentEndpoint{Type: model.EndpointTypeUnspecified}
+	}
+	result := model.PaymentEndpoint{
+		Type:       model.EndpointTypeUnspecified,
+		InstanceID: strings.TrimSpace(src.GetInstanceId()),
+		Metadata:   cloneMetadata(src.GetMetadata()),
+	}
+	if ledger := src.GetLedger(); ledger != nil {
+		result.Type = model.EndpointTypeLedger
+		result.Ledger = &model.LedgerEndpoint{
+			LedgerAccountRef:       strings.TrimSpace(ledger.GetLedgerAccountRef()),
+			ContraLedgerAccountRef: strings.TrimSpace(ledger.GetContraLedgerAccountRef()),
+		}
+		return result
+	}
+	if managed := src.GetManagedWallet(); managed != nil {
+		result.Type = model.EndpointTypeManagedWallet
+		result.ManagedWallet = &model.ManagedWalletEndpoint{
+			ManagedWalletRef: strings.TrimSpace(managed.GetManagedWalletRef()),
+			Asset:            assetFromProto(managed.GetAsset()),
+		}
+		return result
+	}
+	if external := src.GetExternalChain(); external != nil {
+		result.Type = model.EndpointTypeExternalChain
+		result.ExternalChain = &model.ExternalChainEndpoint{
+			Asset:   assetFromProto(external.GetAsset()),
+			Address: strings.TrimSpace(external.GetAddress()),
+			Memo:    strings.TrimSpace(external.GetMemo()),
+		}
+		return result
+	}
+	if card := src.GetCard(); card != nil {
+		result.Type = model.EndpointTypeCard
+		result.Card = &model.CardEndpoint{
+			Pan:               strings.TrimSpace(card.GetPan()),
+			Token:             strings.TrimSpace(card.GetToken()),
+			Cardholder:        strings.TrimSpace(card.GetCardholderName()),
+			CardholderSurname: strings.TrimSpace(card.GetCardholderSurname()),
+			ExpMonth:          card.GetExpMonth(),
+			ExpYear:           card.GetExpYear(),
+			Country:           strings.TrimSpace(card.GetCountry()),
+			MaskedPan:         strings.TrimSpace(card.GetMaskedPan()),
+		}
+		return result
+	}
+	return result
+}
+
+func fxIntentFromProto(src *orchestratorv1.FXIntent) *model.FXIntent {
+	if src == nil {
+		return nil
+	}
+	return &model.FXIntent{
+		Pair:              pairFromProto(src.GetPair()),
+		Side:              fxSideFromProto(src.GetSide()),
+		Firm:              src.GetFirm(),
+		TTLMillis:         src.GetTtlMs(),
+		PreferredProvider: strings.TrimSpace(src.GetPreferredProvider()),
+		MaxAgeMillis:      src.GetMaxAgeMs(),
+	}
+}
+
+func quoteSnapshotToModel(src *orchestratorv1.PaymentQuote) *model.PaymentQuoteSnapshot {
+	if src == nil {
+		return nil
+	}
+	return &model.PaymentQuoteSnapshot{
+		DebitAmount:              moneyFromProto(src.GetDebitAmount()),
+		DebitSettlementAmount:    moneyFromProto(src.GetDebitSettlementAmount()),
+		ExpectedSettlementAmount: moneyFromProto(src.GetExpectedSettlementAmount()),
+		ExpectedFeeTotal:         moneyFromProto(src.GetExpectedFeeTotal()),
+		FeeLines:                 feeLinesFromProto(src.GetFeeLines()),
+		FeeRules:                 feeRulesFromProto(src.GetFeeRules()),
+		FXQuote:                  fxQuoteFromProto(src.GetFxQuote()),
+		NetworkFee:               networkFeeFromProto(src.GetNetworkFee()),
+		QuoteRef:                 strings.TrimSpace(src.GetQuoteRef()),
+	}
+}
+
+func toProtoPayment(src *model.Payment) *orchestratorv1.Payment {
+	if src == nil {
+		return nil
+	}
+	payment := &orchestratorv1.Payment{
+		PaymentRef:     src.PaymentRef,
+		IdempotencyKey: src.IdempotencyKey,
+		Intent:         protoIntentFromModel(src.Intent),
+		State:          protoStateFromModel(src.State),
+		FailureCode:    protoFailureFromModel(src.FailureCode),
+		FailureReason:  src.FailureReason,
+		LastQuote:      modelQuoteToProto(src.LastQuote),
+		Execution:      protoExecutionFromModel(src.Execution),
+		ExecutionPlan:  protoExecutionPlanFromModel(src.ExecutionPlan),
+		PaymentPlan:    protoPaymentPlanFromModel(src.PaymentPlan),
+		Metadata:       cloneMetadata(src.Metadata),
+	}
+	if src.CardPayout != nil {
+		payment.CardPayout = &orchestratorv1.CardPayout{
+			PayoutRef:         src.CardPayout.PayoutRef,
+			ProviderPaymentId: src.CardPayout.ProviderPaymentID,
+			Status:            src.CardPayout.Status,
+			FailureReason:     src.CardPayout.FailureReason,
+			CardCountry:       src.CardPayout.CardCountry,
+			MaskedPan:         src.CardPayout.MaskedPan,
+			ProviderCode:      src.CardPayout.ProviderCode,
+			GatewayReference:  src.CardPayout.GatewayReference,
+		}
+	}
+	if src.CreatedAt.IsZero() {
+		payment.CreatedAt = timestamppb.New(time.Now().UTC())
+	} else {
+		payment.CreatedAt = timestamppb.New(src.CreatedAt.UTC())
+	}
+	if src.UpdatedAt != (time.Time{}) {
+		payment.UpdatedAt = timestamppb.New(src.UpdatedAt.UTC())
+	}
+	return payment
+}
+
+func protoIntentFromModel(src model.PaymentIntent) *orchestratorv1.PaymentIntent {
+	intent := &orchestratorv1.PaymentIntent{
+		Ref:                src.Ref,
+		Kind:               protoKindFromModel(src.Kind),
+		Source:             protoEndpointFromModel(src.Source),
+		Destination:        protoEndpointFromModel(src.Destination),
+		Amount:             protoMoney(src.Amount),
+		RequiresFx:         src.RequiresFX,
+		FeePolicy:          feePolicyToProto(src.FeePolicy),
+		SettlementMode:     settlementModeToProto(src.SettlementMode),
+		SettlementCurrency: strings.TrimSpace(src.SettlementCurrency),
+		Attributes:         cloneMetadata(src.Attributes),
+		Customer:           protoCustomerFromModel(src.Customer),
+	}
+	if src.FX != nil {
+		intent.Fx = protoFXIntentFromModel(src.FX)
+	}
+	return intent
+}
+
+func customerFromProto(src *orchestratorv1.Customer) *model.Customer {
+	if src == nil {
+		return nil
+	}
+	return &model.Customer{
+		ID:         strings.TrimSpace(src.GetId()),
+		FirstName:  strings.TrimSpace(src.GetFirstName()),
+		MiddleName: strings.TrimSpace(src.GetMiddleName()),
+		LastName:   strings.TrimSpace(src.GetLastName()),
+		IP:         strings.TrimSpace(src.GetIp()),
+		Zip:        strings.TrimSpace(src.GetZip()),
+		Country:    strings.TrimSpace(src.GetCountry()),
+		State:      strings.TrimSpace(src.GetState()),
+		City:       strings.TrimSpace(src.GetCity()),
+		Address:    strings.TrimSpace(src.GetAddress()),
+	}
+}
+
+func protoCustomerFromModel(src *model.Customer) *orchestratorv1.Customer {
+	if src == nil {
+		return nil
+	}
+	return &orchestratorv1.Customer{
+		Id:         strings.TrimSpace(src.ID),
+		FirstName:  strings.TrimSpace(src.FirstName),
+		MiddleName: strings.TrimSpace(src.MiddleName),
+		LastName:   strings.TrimSpace(src.LastName),
+		Ip:         strings.TrimSpace(src.IP),
+		Zip:        strings.TrimSpace(src.Zip),
+		Country:    strings.TrimSpace(src.Country),
+		State:      strings.TrimSpace(src.State),
+		City:       strings.TrimSpace(src.City),
+		Address:    strings.TrimSpace(src.Address),
+	}
+}
+
+func protoEndpointFromModel(src model.PaymentEndpoint) *orchestratorv1.PaymentEndpoint {
+	endpoint := &orchestratorv1.PaymentEndpoint{
+		Metadata:   cloneMetadata(src.Metadata),
+		InstanceId: strings.TrimSpace(src.InstanceID),
+	}
+	switch src.Type {
+	case model.EndpointTypeLedger:
+		if src.Ledger != nil {
+			endpoint.Endpoint = &orchestratorv1.PaymentEndpoint_Ledger{
+				Ledger: &orchestratorv1.LedgerEndpoint{
+					LedgerAccountRef:       src.Ledger.LedgerAccountRef,
+					ContraLedgerAccountRef: src.Ledger.ContraLedgerAccountRef,
+				},
+			}
+		}
+	case model.EndpointTypeManagedWallet:
+		if src.ManagedWallet != nil {
+			endpoint.Endpoint = &orchestratorv1.PaymentEndpoint_ManagedWallet{
+				ManagedWallet: &orchestratorv1.ManagedWalletEndpoint{
+					ManagedWalletRef: src.ManagedWallet.ManagedWalletRef,
+					Asset:            assetToProto(src.ManagedWallet.Asset),
+				},
+			}
+		}
+	case model.EndpointTypeExternalChain:
+		if src.ExternalChain != nil {
+			endpoint.Endpoint = &orchestratorv1.PaymentEndpoint_ExternalChain{
+				ExternalChain: &orchestratorv1.ExternalChainEndpoint{
+					Asset:   assetToProto(src.ExternalChain.Asset),
+					Address: src.ExternalChain.Address,
+					Memo:    src.ExternalChain.Memo,
+				},
+			}
+		}
+	case model.EndpointTypeCard:
+		if src.Card != nil {
+			card := &orchestratorv1.CardEndpoint{
+				CardholderName:    src.Card.Cardholder,
+				CardholderSurname: src.Card.CardholderSurname,
+				ExpMonth:          src.Card.ExpMonth,
+				ExpYear:           src.Card.ExpYear,
+				Country:           src.Card.Country,
+				MaskedPan:         src.Card.MaskedPan,
+			}
+			if pan := strings.TrimSpace(src.Card.Pan); pan != "" {
+				card.Card = &orchestratorv1.CardEndpoint_Pan{Pan: pan}
+			}
+			if token := strings.TrimSpace(src.Card.Token); token != "" {
+				card.Card = &orchestratorv1.CardEndpoint_Token{Token: token}
+			}
+			endpoint.Endpoint = &orchestratorv1.PaymentEndpoint_Card{Card: card}
+		}
+	default:
+		// leave unspecified
+	}
+	return endpoint
+}
+
+func protoFXIntentFromModel(src *model.FXIntent) *orchestratorv1.FXIntent {
+	if src == nil {
+		return nil
+	}
+	return &orchestratorv1.FXIntent{
+		Pair:              pairToProto(src.Pair),
+		Side:              fxSideToProto(src.Side),
+		Firm:              src.Firm,
+		TtlMs:             src.TTLMillis,
+		PreferredProvider: src.PreferredProvider,
+		MaxAgeMs:          src.MaxAgeMillis,
+	}
+}
+
+func protoExecutionFromModel(src *model.ExecutionRefs) *orchestratorv1.ExecutionRefs {
+	if src == nil {
+		return nil
+	}
+	return &orchestratorv1.ExecutionRefs{
+		DebitEntryRef:    src.DebitEntryRef,
+		CreditEntryRef:   src.CreditEntryRef,
+		FxEntryRef:       src.FXEntryRef,
+		ChainTransferRef: src.ChainTransferRef,
+		CardPayoutRef:    src.CardPayoutRef,
+		FeeTransferRef:   src.FeeTransferRef,
+	}
+}
+
+func protoExecutionStepFromModel(src *model.ExecutionStep) *orchestratorv1.ExecutionStep {
+	if src == nil {
+		return nil
+	}
+	return &orchestratorv1.ExecutionStep{
+		Code:            src.Code,
+		Description:     src.Description,
+		Amount:          protoMoney(src.Amount),
+		NetworkFee:      protoMoney(src.NetworkFee),
+		SourceWalletRef: src.SourceWalletRef,
+		DestinationRef:  src.DestinationRef,
+		TransferRef:     src.TransferRef,
+		Metadata:        cloneMetadata(src.Metadata),
+		OperationRef:    src.OperationRef,
+	}
+}
+
+func protoExecutionPlanFromModel(src *model.ExecutionPlan) *orchestratorv1.ExecutionPlan {
+	if src == nil {
+		return nil
+	}
+	steps := make([]*orchestratorv1.ExecutionStep, 0, len(src.Steps))
+	for _, step := range src.Steps {
+		if protoStep := protoExecutionStepFromModel(step); protoStep != nil {
+			steps = append(steps, protoStep)
+		}
+	}
+	if len(steps) == 0 {
+		steps = nil
+	}
+	return &orchestratorv1.ExecutionPlan{
+		Steps:           steps,
+		TotalNetworkFee: protoMoney(src.TotalNetworkFee),
+	}
+}
+
+func protoPaymentStepFromModel(src *model.PaymentStep) *orchestratorv1.PaymentStep {
+	if src == nil {
+		return nil
+	}
+	return &orchestratorv1.PaymentStep{
+		Rail:         protoRailFromModel(src.Rail),
+		GatewayId:    strings.TrimSpace(src.GatewayID),
+		Action:       protoRailOperationFromModel(src.Action),
+		Amount:       protoMoney(src.Amount),
+		StepId:       strings.TrimSpace(src.StepID),
+		InstanceId:   strings.TrimSpace(src.InstanceID),
+		DependsOn:    cloneStringList(src.DependsOn),
+		CommitPolicy: strings.TrimSpace(string(src.CommitPolicy)),
+		CommitAfter:  cloneStringList(src.CommitAfter),
+	}
+}
+
+func protoPaymentPlanFromModel(src *model.PaymentPlan) *orchestratorv1.PaymentPlan {
+	if src == nil {
+		return nil
+	}
+	steps := make([]*orchestratorv1.PaymentStep, 0, len(src.Steps))
+	for _, step := range src.Steps {
+		if protoStep := protoPaymentStepFromModel(step); protoStep != nil {
+			steps = append(steps, protoStep)
+		}
+	}
+	if len(steps) == 0 {
+		steps = nil
+	}
+	plan := &orchestratorv1.PaymentPlan{
+		Id:             strings.TrimSpace(src.ID),
+		Steps:          steps,
+		IdempotencyKey: strings.TrimSpace(src.IdempotencyKey),
+		FxQuote:        fxQuoteToProto(src.FXQuote),
+		Fees:           feeLinesToProto(src.Fees),
+	}
+	if !src.CreatedAt.IsZero() {
+		plan.CreatedAt = timestamppb.New(src.CreatedAt.UTC())
+	}
+	return plan
+}
+
+func modelQuoteToProto(src *model.PaymentQuoteSnapshot) *orchestratorv1.PaymentQuote {
+	if src == nil {
+		return nil
+	}
+	return &orchestratorv1.PaymentQuote{
+		DebitAmount:              protoMoney(src.DebitAmount),
+		DebitSettlementAmount:    protoMoney(src.DebitSettlementAmount),
+		ExpectedSettlementAmount: protoMoney(src.ExpectedSettlementAmount),
+		ExpectedFeeTotal:         protoMoney(src.ExpectedFeeTotal),
+		FeeLines:                 feeLinesToProto(src.FeeLines),
+		FeeRules:                 feeRulesToProto(src.FeeRules),
+		FxQuote:                  fxQuoteToProto(src.FXQuote),
+		NetworkFee:               networkFeeToProto(src.NetworkFee),
+		QuoteRef:                 strings.TrimSpace(src.QuoteRef),
+	}
+}
+
+func filterFromProto(req *orchestratorv1.ListPaymentsRequest) *model.PaymentFilter {
+	if req == nil {
+		return &model.PaymentFilter{}
+	}
+	filter := &model.PaymentFilter{
+		SourceRef:       strings.TrimSpace(req.GetSourceRef()),
+		DestinationRef:  strings.TrimSpace(req.GetDestinationRef()),
+		OrganizationRef: strings.TrimSpace(req.GetOrganizationRef()),
+	}
+	if req.GetPage() != nil {
+		filter.Cursor = strings.TrimSpace(req.GetPage().GetCursor())
+		filter.Limit = req.GetPage().GetLimit()
+	}
+	if len(req.GetFilterStates()) > 0 {
+		filter.States = make([]model.PaymentState, 0, len(req.GetFilterStates()))
+		for _, st := range req.GetFilterStates() {
+			filter.States = append(filter.States, modelStateFromProto(st))
+		}
+	}
+	return filter
+}
+
+func protoKindFromModel(kind model.PaymentKind) orchestratorv1.PaymentKind {
+	switch kind {
+	case model.PaymentKindPayout:
+		return orchestratorv1.PaymentKind_PAYMENT_KIND_PAYOUT
+	case model.PaymentKindInternalTransfer:
+		return orchestratorv1.PaymentKind_PAYMENT_KIND_INTERNAL_TRANSFER
+	case model.PaymentKindFXConversion:
+		return orchestratorv1.PaymentKind_PAYMENT_KIND_FX_CONVERSION
+	default:
+		return orchestratorv1.PaymentKind_PAYMENT_KIND_UNSPECIFIED
+	}
+}
+
+func modelKindFromProto(kind orchestratorv1.PaymentKind) model.PaymentKind {
+	switch kind {
+	case orchestratorv1.PaymentKind_PAYMENT_KIND_PAYOUT:
+		return model.PaymentKindPayout
+	case orchestratorv1.PaymentKind_PAYMENT_KIND_INTERNAL_TRANSFER:
+		return model.PaymentKindInternalTransfer
+	case orchestratorv1.PaymentKind_PAYMENT_KIND_FX_CONVERSION:
+		return model.PaymentKindFXConversion
+	default:
+		return model.PaymentKindUnspecified
+	}
+}
+
+func protoRailFromModel(rail model.Rail) gatewayv1.Rail {
+	switch strings.ToUpper(strings.TrimSpace(string(rail))) {
+	case string(model.RailCrypto):
+		return gatewayv1.Rail_RAIL_CRYPTO
+	case string(model.RailProviderSettlement):
+		return gatewayv1.Rail_RAIL_PROVIDER_SETTLEMENT
+	case string(model.RailLedger):
+		return gatewayv1.Rail_RAIL_LEDGER
+	case string(model.RailCardPayout):
+		return gatewayv1.Rail_RAIL_CARD_PAYOUT
+	case string(model.RailFiatOnRamp):
+		return gatewayv1.Rail_RAIL_FIAT_ONRAMP
+	default:
+		return gatewayv1.Rail_RAIL_UNSPECIFIED
+	}
+}
+
+func protoRailOperationFromModel(action model.RailOperation) gatewayv1.RailOperation {
+	switch strings.ToUpper(strings.TrimSpace(string(action))) {
+	case string(model.RailOperationDebit):
+		return gatewayv1.RailOperation_RAIL_OPERATION_DEBIT
+	case string(model.RailOperationCredit):
+		return gatewayv1.RailOperation_RAIL_OPERATION_CREDIT
+	case string(model.RailOperationExternalDebit):
+		return gatewayv1.RailOperation_RAIL_OPERATION_DEBIT
+	case string(model.RailOperationExternalCredit):
+		return gatewayv1.RailOperation_RAIL_OPERATION_CREDIT
+	case string(model.RailOperationMove):
+		return gatewayv1.RailOperation_RAIL_OPERATION_MOVE
+	case string(model.RailOperationSend):
+		return gatewayv1.RailOperation_RAIL_OPERATION_SEND
+	case string(model.RailOperationFee):
+		return gatewayv1.RailOperation_RAIL_OPERATION_FEE
+	case string(model.RailOperationObserveConfirm):
+		return gatewayv1.RailOperation_RAIL_OPERATION_OBSERVE_CONFIRM
+	case string(model.RailOperationFXConvert):
+		return gatewayv1.RailOperation_RAIL_OPERATION_FX_CONVERT
+	case string(model.RailOperationBlock):
+		return gatewayv1.RailOperation_RAIL_OPERATION_BLOCK
+	case string(model.RailOperationRelease):
+		return gatewayv1.RailOperation_RAIL_OPERATION_RELEASE
+	default:
+		return gatewayv1.RailOperation_RAIL_OPERATION_UNSPECIFIED
+	}
+}
+
+func protoStateFromModel(state model.PaymentState) orchestratorv1.PaymentState {
+	switch state {
+	case model.PaymentStateAccepted:
+		return orchestratorv1.PaymentState_PAYMENT_STATE_ACCEPTED
+	case model.PaymentStateFundsReserved:
+		return orchestratorv1.PaymentState_PAYMENT_STATE_FUNDS_RESERVED
+	case model.PaymentStateSubmitted:
+		return orchestratorv1.PaymentState_PAYMENT_STATE_SUBMITTED
+	case model.PaymentStateSettled:
+		return orchestratorv1.PaymentState_PAYMENT_STATE_SETTLED
+	case model.PaymentStateFailed:
+		return orchestratorv1.PaymentState_PAYMENT_STATE_FAILED
+	case model.PaymentStateCancelled:
+		return orchestratorv1.PaymentState_PAYMENT_STATE_CANCELLED
+	default:
+		return orchestratorv1.PaymentState_PAYMENT_STATE_UNSPECIFIED
+	}
+}
+
+func modelStateFromProto(state orchestratorv1.PaymentState) model.PaymentState {
+	switch state {
+	case orchestratorv1.PaymentState_PAYMENT_STATE_ACCEPTED:
+		return model.PaymentStateAccepted
+	case orchestratorv1.PaymentState_PAYMENT_STATE_FUNDS_RESERVED:
+		return model.PaymentStateFundsReserved
+	case orchestratorv1.PaymentState_PAYMENT_STATE_SUBMITTED:
+		return model.PaymentStateSubmitted
+	case orchestratorv1.PaymentState_PAYMENT_STATE_SETTLED:
+		return model.PaymentStateSettled
+	case orchestratorv1.PaymentState_PAYMENT_STATE_FAILED:
+		return model.PaymentStateFailed
+	case orchestratorv1.PaymentState_PAYMENT_STATE_CANCELLED:
+		return model.PaymentStateCancelled
+	default:
+		return model.PaymentStateUnspecified
+	}
+}
+
+func protoFailureFromModel(code model.PaymentFailureCode) orchestratorv1.PaymentFailureCode {
+	switch code {
+	case model.PaymentFailureCodeBalance:
+		return orchestratorv1.PaymentFailureCode_FAILURE_BALANCE
+	case model.PaymentFailureCodeLedger:
+		return orchestratorv1.PaymentFailureCode_FAILURE_LEDGER
+	case model.PaymentFailureCodeFX:
+		return orchestratorv1.PaymentFailureCode_FAILURE_FX
+	case model.PaymentFailureCodeChain:
+		return orchestratorv1.PaymentFailureCode_FAILURE_CHAIN
+	case model.PaymentFailureCodeFees:
+		return orchestratorv1.PaymentFailureCode_FAILURE_FEES
+	case model.PaymentFailureCodePolicy:
+		return orchestratorv1.PaymentFailureCode_FAILURE_POLICY
+	default:
+		return orchestratorv1.PaymentFailureCode_FAILURE_UNSPECIFIED
+	}
+}
+
+func settlementModeFromProto(mode orchestratorv1.SettlementMode) model.SettlementMode {
+	switch mode {
+	case orchestratorv1.SettlementMode_SETTLEMENT_FIX_SOURCE:
+		return model.SettlementModeFixSource
+	case orchestratorv1.SettlementMode_SETTLEMENT_FIX_RECEIVED:
+		return model.SettlementModeFixReceived
+	default:
+		return model.SettlementModeUnspecified
+	}
+}
+
+func settlementModeToProto(mode model.SettlementMode) orchestratorv1.SettlementMode {
+	switch mode {
+	case model.SettlementModeFixSource:
+		return orchestratorv1.SettlementMode_SETTLEMENT_FIX_SOURCE
+	case model.SettlementModeFixReceived:
+		return orchestratorv1.SettlementMode_SETTLEMENT_FIX_RECEIVED
+	default:
+		return orchestratorv1.SettlementMode_SETTLEMENT_UNSPECIFIED
+	}
+}
+
+func moneyFromProto(m *moneyv1.Money) *paymenttypes.Money {
+	if m == nil {
+		return nil
+	}
+	return &paymenttypes.Money{
+		Currency: m.GetCurrency(),
+		Amount:   m.GetAmount(),
+	}
+}
+
+func protoMoney(m *paymenttypes.Money) *moneyv1.Money {
+	if m == nil {
+		return nil
+	}
+	return &moneyv1.Money{
+		Currency: m.GetCurrency(),
+		Amount:   m.GetAmount(),
+	}
+}
+
+func feePolicyFromProto(src *feesv1.PolicyOverrides) *paymenttypes.FeePolicy {
+	if src == nil {
+		return nil
+	}
+	return &paymenttypes.FeePolicy{
+		InsufficientNet: insufficientPolicyFromProto(src.GetInsufficientNet()),
+	}
+}
+
+func feePolicyToProto(src *paymenttypes.FeePolicy) *feesv1.PolicyOverrides {
+	if src == nil {
+		return nil
+	}
+	return &feesv1.PolicyOverrides{
+		InsufficientNet: insufficientPolicyToProto(src.InsufficientNet),
+	}
+}
+
+func insufficientPolicyFromProto(policy feesv1.InsufficientNetPolicy) paymenttypes.InsufficientNetPolicy {
+	switch policy {
+	case feesv1.InsufficientNetPolicy_BLOCK_POSTING:
+		return paymenttypes.InsufficientNetBlockPosting
+	case feesv1.InsufficientNetPolicy_SWEEP_ORG_CASH:
+		return paymenttypes.InsufficientNetSweepOrgCash
+	case feesv1.InsufficientNetPolicy_INVOICE_LATER:
+		return paymenttypes.InsufficientNetInvoiceLater
+	default:
+		return paymenttypes.InsufficientNetUnspecified
+	}
+}
+
+func insufficientPolicyToProto(policy paymenttypes.InsufficientNetPolicy) feesv1.InsufficientNetPolicy {
+	switch policy {
+	case paymenttypes.InsufficientNetBlockPosting:
+		return feesv1.InsufficientNetPolicy_BLOCK_POSTING
+	case paymenttypes.InsufficientNetSweepOrgCash:
+		return feesv1.InsufficientNetPolicy_SWEEP_ORG_CASH
+	case paymenttypes.InsufficientNetInvoiceLater:
+		return feesv1.InsufficientNetPolicy_INVOICE_LATER
+	default:
+		return feesv1.InsufficientNetPolicy_INSUFFICIENT_NET_UNSPECIFIED
+	}
+}
+
+func pairFromProto(pair *fxv1.CurrencyPair) *paymenttypes.CurrencyPair {
+	if pair == nil {
+		return nil
+	}
+	return &paymenttypes.CurrencyPair{
+		Base:  pair.GetBase(),
+		Quote: pair.GetQuote(),
+	}
+}
+
+func pairToProto(pair *paymenttypes.CurrencyPair) *fxv1.CurrencyPair {
+	if pair == nil {
+		return nil
+	}
+	return &fxv1.CurrencyPair{
+		Base:  pair.GetBase(),
+		Quote: pair.GetQuote(),
+	}
+}
+
+func fxSideFromProto(side fxv1.Side) paymenttypes.FXSide {
+	switch side {
+	case fxv1.Side_BUY_BASE_SELL_QUOTE:
+		return paymenttypes.FXSideBuyBaseSellQuote
+	case fxv1.Side_SELL_BASE_BUY_QUOTE:
+		return paymenttypes.FXSideSellBaseBuyQuote
+	default:
+		return paymenttypes.FXSideUnspecified
+	}
+}
+
+func fxSideToProto(side paymenttypes.FXSide) fxv1.Side {
+	switch side {
+	case paymenttypes.FXSideBuyBaseSellQuote:
+		return fxv1.Side_BUY_BASE_SELL_QUOTE
+	case paymenttypes.FXSideSellBaseBuyQuote:
+		return fxv1.Side_SELL_BASE_BUY_QUOTE
+	default:
+		return fxv1.Side_SIDE_UNSPECIFIED
+	}
+}
+
+func fxQuoteFromProto(quote *oraclev1.Quote) *paymenttypes.FXQuote {
+	if quote == nil {
+		return nil
+	}
+	return &paymenttypes.FXQuote{
+		QuoteRef:        strings.TrimSpace(quote.GetQuoteRef()),
+		Pair:            pairFromProto(quote.GetPair()),
+		Side:            fxSideFromProto(quote.GetSide()),
+		Price:           decimalFromProto(quote.GetPrice()),
+		BaseAmount:      moneyFromProto(quote.GetBaseAmount()),
+		QuoteAmount:     moneyFromProto(quote.GetQuoteAmount()),
+		ExpiresAtUnixMs: quote.GetExpiresAtUnixMs(),
+		Provider:        strings.TrimSpace(quote.GetProvider()),
+		RateRef:         strings.TrimSpace(quote.GetRateRef()),
+		Firm:            quote.GetFirm(),
+	}
+}
+
+func fxQuoteToProto(quote *paymenttypes.FXQuote) *oraclev1.Quote {
+	if quote == nil {
+		return nil
+	}
+	return &oraclev1.Quote{
+		QuoteRef:        strings.TrimSpace(quote.QuoteRef),
+		Pair:            pairToProto(quote.Pair),
+		Side:            fxSideToProto(quote.Side),
+		Price:           decimalToProto(quote.Price),
+		BaseAmount:      protoMoney(quote.BaseAmount),
+		QuoteAmount:     protoMoney(quote.QuoteAmount),
+		ExpiresAtUnixMs: quote.ExpiresAtUnixMs,
+		Provider:        strings.TrimSpace(quote.Provider),
+		RateRef:         strings.TrimSpace(quote.RateRef),
+		Firm:            quote.Firm,
+	}
+}
+
+func decimalFromProto(value *moneyv1.Decimal) *paymenttypes.Decimal {
+	if value == nil {
+		return nil
+	}
+	return &paymenttypes.Decimal{Value: value.GetValue()}
+}
+
+func decimalToProto(value *paymenttypes.Decimal) *moneyv1.Decimal {
+	if value == nil {
+		return nil
+	}
+	return &moneyv1.Decimal{Value: value.GetValue()}
+}
+
+func assetFromProto(asset *chainv1.Asset) *paymenttypes.Asset {
+	if asset == nil {
+		return nil
+	}
+	return &paymenttypes.Asset{
+		Chain:           chainasset.NetworkAlias(asset.GetChain()),
+		TokenSymbol:     asset.GetTokenSymbol(),
+		ContractAddress: asset.GetContractAddress(),
+	}
+}
+
+func assetToProto(asset *paymenttypes.Asset) *chainv1.Asset {
+	if asset == nil {
+		return nil
+	}
+	return &chainv1.Asset{
+		Chain:           chainasset.NetworkFromString(asset.Chain),
+		TokenSymbol:     asset.TokenSymbol,
+		ContractAddress: asset.ContractAddress,
+	}
+}
+
+func networkFeeFromProto(resp *chainv1.EstimateTransferFeeResponse) *paymenttypes.NetworkFeeEstimate {
+	if resp == nil {
+		return nil
+	}
+	return &paymenttypes.NetworkFeeEstimate{
+		NetworkFee:        moneyFromProto(resp.GetNetworkFee()),
+		EstimationContext: strings.TrimSpace(resp.GetEstimationContext()),
+	}
+}
+
+func networkFeeToProto(resp *paymenttypes.NetworkFeeEstimate) *chainv1.EstimateTransferFeeResponse {
+	if resp == nil {
+		return nil
+	}
+	return &chainv1.EstimateTransferFeeResponse{
+		NetworkFee:        protoMoney(resp.NetworkFee),
+		EstimationContext: strings.TrimSpace(resp.EstimationContext),
+	}
+}
+
+func feeLinesFromProto(lines []*feesv1.DerivedPostingLine) []*paymenttypes.FeeLine {
+	if len(lines) == 0 {
+		return nil
+	}
+	result := make([]*paymenttypes.FeeLine, 0, len(lines))
+	for _, line := range lines {
+		if line == nil {
+			continue
+		}
+		result = append(result, &paymenttypes.FeeLine{
+			LedgerAccountRef: strings.TrimSpace(line.GetLedgerAccountRef()),
+			Money:            moneyFromProto(line.GetMoney()),
+			LineType:         postingLineTypeFromProto(line.GetLineType()),
+			Side:             entrySideFromProto(line.GetSide()),
+			Meta:             cloneMetadata(line.GetMeta()),
+		})
+	}
+	if len(result) == 0 {
+		return nil
+	}
+	return result
+}
+
+func feeLinesToProto(lines []*paymenttypes.FeeLine) []*feesv1.DerivedPostingLine {
+	if len(lines) == 0 {
+		return nil
+	}
+	result := make([]*feesv1.DerivedPostingLine, 0, len(lines))
+	for _, line := range lines {
+		if line == nil {
+			continue
+		}
+		result = append(result, &feesv1.DerivedPostingLine{
+			LedgerAccountRef: strings.TrimSpace(line.LedgerAccountRef),
+			Money:            protoMoney(line.Money),
+			LineType:         postingLineTypeToProto(line.LineType),
+			Side:             entrySideToProto(line.Side),
+			Meta:             cloneMetadata(line.Meta),
+		})
+	}
+	if len(result) == 0 {
+		return nil
+	}
+	return result
+}
+
+func feeRulesFromProto(rules []*feesv1.AppliedRule) []*paymenttypes.AppliedRule {
+	if len(rules) == 0 {
+		return nil
+	}
+	result := make([]*paymenttypes.AppliedRule, 0, len(rules))
+	for _, rule := range rules {
+		if rule == nil {
+			continue
+		}
+		result = append(result, &paymenttypes.AppliedRule{
+			RuleID:      strings.TrimSpace(rule.GetRuleId()),
+			RuleVersion: strings.TrimSpace(rule.GetRuleVersion()),
+			Formula:     strings.TrimSpace(rule.GetFormula()),
+			Rounding:    roundingModeFromProto(rule.GetRounding()),
+			TaxCode:     strings.TrimSpace(rule.GetTaxCode()),
+			TaxRate:     strings.TrimSpace(rule.GetTaxRate()),
+			Parameters:  cloneMetadata(rule.GetParameters()),
+		})
+	}
+	if len(result) == 0 {
+		return nil
+	}
+	return result
+}
+
+func feeRulesToProto(rules []*paymenttypes.AppliedRule) []*feesv1.AppliedRule {
+	if len(rules) == 0 {
+		return nil
+	}
+	result := make([]*feesv1.AppliedRule, 0, len(rules))
+	for _, rule := range rules {
+		if rule == nil {
+			continue
+		}
+		result = append(result, &feesv1.AppliedRule{
+			RuleId:      strings.TrimSpace(rule.RuleID),
+			RuleVersion: strings.TrimSpace(rule.RuleVersion),
+			Formula:     strings.TrimSpace(rule.Formula),
+			Rounding:    roundingModeToProto(rule.Rounding),
+			TaxCode:     strings.TrimSpace(rule.TaxCode),
+			TaxRate:     strings.TrimSpace(rule.TaxRate),
+			Parameters:  cloneMetadata(rule.Parameters),
+		})
+	}
+	if len(result) == 0 {
+		return nil
+	}
+	return result
+}
+
+func entrySideFromProto(side accountingv1.EntrySide) paymenttypes.EntrySide {
+	switch side {
+	case accountingv1.EntrySide_ENTRY_SIDE_DEBIT:
+		return paymenttypes.EntrySideDebit
+	case accountingv1.EntrySide_ENTRY_SIDE_CREDIT:
+		return paymenttypes.EntrySideCredit
+	default:
+		return paymenttypes.EntrySideUnspecified
+	}
+}
+
+func entrySideToProto(side paymenttypes.EntrySide) accountingv1.EntrySide {
+	switch side {
+	case paymenttypes.EntrySideDebit:
+		return accountingv1.EntrySide_ENTRY_SIDE_DEBIT
+	case paymenttypes.EntrySideCredit:
+		return accountingv1.EntrySide_ENTRY_SIDE_CREDIT
+	default:
+		return accountingv1.EntrySide_ENTRY_SIDE_UNSPECIFIED
+	}
+}
+
+func postingLineTypeFromProto(lineType accountingv1.PostingLineType) paymenttypes.PostingLineType {
+	switch lineType {
+	case accountingv1.PostingLineType_POSTING_LINE_FEE:
+		return paymenttypes.PostingLineTypeFee
+	case accountingv1.PostingLineType_POSTING_LINE_TAX:
+		return paymenttypes.PostingLineTypeTax
+	case accountingv1.PostingLineType_POSTING_LINE_SPREAD:
+		return paymenttypes.PostingLineTypeSpread
+	case accountingv1.PostingLineType_POSTING_LINE_REVERSAL:
+		return paymenttypes.PostingLineTypeReversal
+	default:
+		return paymenttypes.PostingLineTypeUnspecified
+	}
+}
+
+func postingLineTypeToProto(lineType paymenttypes.PostingLineType) accountingv1.PostingLineType {
+	switch lineType {
+	case paymenttypes.PostingLineTypeFee:
+		return accountingv1.PostingLineType_POSTING_LINE_FEE
+	case paymenttypes.PostingLineTypeTax:
+		return accountingv1.PostingLineType_POSTING_LINE_TAX
+	case paymenttypes.PostingLineTypeSpread:
+		return accountingv1.PostingLineType_POSTING_LINE_SPREAD
+	case paymenttypes.PostingLineTypeReversal:
+		return accountingv1.PostingLineType_POSTING_LINE_REVERSAL
+	default:
+		return accountingv1.PostingLineType_POSTING_LINE_TYPE_UNSPECIFIED
+	}
+}
+
+func roundingModeFromProto(mode moneyv1.RoundingMode) paymenttypes.RoundingMode {
+	switch mode {
+	case moneyv1.RoundingMode_ROUND_HALF_EVEN:
+		return paymenttypes.RoundingModeHalfEven
+	case moneyv1.RoundingMode_ROUND_HALF_UP:
+		return paymenttypes.RoundingModeHalfUp
+	case moneyv1.RoundingMode_ROUND_DOWN:
+		return paymenttypes.RoundingModeDown
+	default:
+		return paymenttypes.RoundingModeUnspecified
+	}
+}
+
+func roundingModeToProto(mode paymenttypes.RoundingMode) moneyv1.RoundingMode {
+	switch mode {
+	case paymenttypes.RoundingModeHalfEven:
+		return moneyv1.RoundingMode_ROUND_HALF_EVEN
+	case paymenttypes.RoundingModeHalfUp:
+		return moneyv1.RoundingMode_ROUND_HALF_UP
+	case paymenttypes.RoundingModeDown:
+		return moneyv1.RoundingMode_ROUND_DOWN
+	default:
+		return moneyv1.RoundingMode_ROUNDING_MODE_UNSPECIFIED
+	}
+}

api/payments/quotation/internal/service/orchestrator/discovery_gateway_registry.go

@@ -0,0 +1,137 @@
+package orchestrator
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/discovery"
+	"github.com/tech/sendico/pkg/mlogger"
+)
+
+type discoveryGatewayRegistry struct {
+	logger   mlogger.Logger
+	registry *discovery.Registry
+}
+
+func NewDiscoveryGatewayRegistry(logger mlogger.Logger, registry *discovery.Registry) GatewayRegistry {
+	if registry == nil {
+		return nil
+	}
+	if logger != nil {
+		logger = logger.Named("discovery_gateway_registry")
+	}
+	return &discoveryGatewayRegistry{
+		logger:   logger,
+		registry: registry,
+	}
+}
+
+func (r *discoveryGatewayRegistry) List(_ context.Context) ([]*model.GatewayInstanceDescriptor, error) {
+	if r == nil || r.registry == nil {
+		return nil, nil
+	}
+	entries := r.registry.List(time.Now(), true)
+	items := make([]*model.GatewayInstanceDescriptor, 0, len(entries))
+	for _, entry := range entries {
+		if entry.Rail == "" {
+			continue
+		}
+		rail := railFromDiscovery(entry.Rail)
+		if rail == model.RailUnspecified {
+			continue
+		}
+		items = append(items, &model.GatewayInstanceDescriptor{
+			ID:           entry.ID,
+			InstanceID:   entry.InstanceID,
+			Rail:         rail,
+			Network:      entry.Network,
+			InvokeURI:    strings.TrimSpace(entry.InvokeURI),
+			Currencies:   normalizeCurrencies(entry.Currencies),
+			Capabilities: capabilitiesFromOps(entry.Operations),
+			Limits:       limitsFromDiscovery(entry.Limits),
+			Version:      entry.Version,
+			IsEnabled:    entry.Healthy,
+		})
+	}
+	sort.Slice(items, func(i, j int) bool {
+		return items[i].ID < items[j].ID
+	})
+	return items, nil
+}
+
+func railFromDiscovery(value string) model.Rail {
+	switch strings.ToUpper(strings.TrimSpace(value)) {
+	case string(model.RailCrypto):
+		return model.RailCrypto
+	case string(model.RailProviderSettlement):
+		return model.RailProviderSettlement
+	case string(model.RailLedger):
+		return model.RailLedger
+	case string(model.RailCardPayout):
+		return model.RailCardPayout
+	case string(model.RailFiatOnRamp):
+		return model.RailFiatOnRamp
+	default:
+		return model.RailUnspecified
+	}
+}
+
+func capabilitiesFromOps(ops []string) model.RailCapabilities {
+	var cap model.RailCapabilities
+	for _, op := range ops {
+		switch strings.ToLower(strings.TrimSpace(op)) {
+		case "payin.crypto", "payin.card", "payin.fiat":
+			cap.CanPayIn = true
+		case "payout.crypto", "payout.card", "payout.fiat":
+			cap.CanPayOut = true
+		case "balance.read":
+			cap.CanReadBalance = true
+		case "fee.send":
+			cap.CanSendFee = true
+		case "observe.confirm", "observe.confirmation":
+			cap.RequiresObserveConfirm = true
+		case "block", "funds.block", "balance.block", "ledger.block":
+			cap.CanBlock = true
+		case "release", "funds.release", "balance.release", "ledger.release":
+			cap.CanRelease = true
+		}
+	}
+	return cap
+}
+
+func limitsFromDiscovery(src *discovery.Limits) model.Limits {
+	if src == nil {
+		return model.Limits{}
+	}
+	limits := model.Limits{
+		MinAmount:     strings.TrimSpace(src.MinAmount),
+		MaxAmount:     strings.TrimSpace(src.MaxAmount),
+		VolumeLimit:   map[string]string{},
+		VelocityLimit: map[string]int{},
+	}
+	for key, value := range src.VolumeLimit {
+		k := strings.TrimSpace(key)
+		v := strings.TrimSpace(value)
+		if k == "" || v == "" {
+			continue
+		}
+		limits.VolumeLimit[k] = v
+	}
+	for key, value := range src.VelocityLimit {
+		k := strings.TrimSpace(key)
+		if k == "" {
+			continue
+		}
+		limits.VelocityLimit[k] = value
+	}
+	if len(limits.VolumeLimit) == 0 {
+		limits.VolumeLimit = nil
+	}
+	if len(limits.VelocityLimit) == 0 {
+		limits.VelocityLimit = nil
+	}
+	return limits
+}

api/payments/quotation/internal/service/orchestrator/execution_plan.go

@@ -0,0 +1,163 @@
+package orchestrator
+
+import (
+	"strings"
+
+	"github.com/tech/sendico/payments/storage/model"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+)
+
+const (
+	executionStepMetadataRole   = "role"
+	executionStepMetadataStatus = "status"
+
+	executionStepRoleSource   = "source"
+	executionStepRoleConsumer = "consumer"
+)
+
+func setExecutionStepRole(step *model.ExecutionStep, role string) {
+	role = strings.ToLower(strings.TrimSpace(role))
+	setExecutionStepMetadata(step, executionStepMetadataRole, role)
+}
+
+func setExecutionStepStatus(step *model.ExecutionStep, state model.OperationState) {
+	step.State = state
+	setExecutionStepMetadata(step, executionStepMetadataStatus, string(state))
+}
+
+func executionStepRole(step *model.ExecutionStep) string {
+	if step == nil {
+		return ""
+	}
+	if role := strings.TrimSpace(step.Metadata[executionStepMetadataRole]); role != "" {
+		return strings.ToLower(role)
+	}
+	if strings.EqualFold(step.Code, stepCodeCardPayout) {
+		return executionStepRoleConsumer
+	}
+	return executionStepRoleSource
+}
+
+func isSourceExecutionStep(step *model.ExecutionStep) bool {
+	return executionStepRole(step) == executionStepRoleSource
+}
+
+func sourceStepsConfirmed(plan *model.ExecutionPlan) bool {
+	if plan == nil || len(plan.Steps) == 0 {
+		return false
+	}
+	hasSource := false
+	for _, step := range plan.Steps {
+		if step == nil || !isSourceExecutionStep(step) {
+			continue
+		}
+		if step.State == model.OperationStateSkipped {
+			continue
+		}
+		hasSource = true
+		if step.State != model.OperationStateSuccess {
+			return false
+		}
+	}
+	return hasSource
+}
+
+func findExecutionStepByTransferRef(plan *model.ExecutionPlan, transferRef string) *model.ExecutionStep {
+	if plan == nil {
+		return nil
+	}
+	transferRef = strings.TrimSpace(transferRef)
+	if transferRef == "" {
+		return nil
+	}
+	for _, step := range plan.Steps {
+		if step == nil {
+			continue
+		}
+		if strings.EqualFold(strings.TrimSpace(step.TransferRef), transferRef) {
+			return step
+		}
+	}
+	return nil
+}
+
+func updateExecutionStepFromTransfer(plan *model.ExecutionPlan, event *chainv1.TransferStatusChangedEvent) *model.ExecutionStep {
+	if plan == nil || event == nil || event.GetTransfer() == nil {
+		return nil
+	}
+	transfer := event.GetTransfer()
+	transferRef := strings.TrimSpace(transfer.GetTransferRef())
+	if transferRef == "" {
+		return nil
+	}
+	if status := executionStepStatusFromTransferStatus(transfer.GetStatus()); status != "" {
+		var updated *model.ExecutionStep
+		for _, step := range plan.Steps {
+			if step == nil {
+				continue
+			}
+			if !strings.EqualFold(strings.TrimSpace(step.TransferRef), transferRef) {
+				continue
+			}
+			if step.TransferRef == "" {
+				step.TransferRef = transferRef
+			}
+			setExecutionStepStatus(step, status)
+			if updated == nil {
+				updated = step
+			}
+		}
+		return updated
+	}
+	return nil
+}
+
+func executionStepStatusFromTransferStatus(status chainv1.TransferStatus) model.OperationState {
+	switch status {
+
+	case chainv1.TransferStatus_TRANSFER_CREATED:
+		return model.OperationStatePlanned
+
+	case chainv1.TransferStatus_TRANSFER_PROCESSING:
+		return model.OperationStateProcessing
+
+	case chainv1.TransferStatus_TRANSFER_WAITING:
+		return model.OperationStateWaiting
+
+	case chainv1.TransferStatus_TRANSFER_SUCCESS:
+		return model.OperationStateSuccess
+
+	case chainv1.TransferStatus_TRANSFER_FAILED:
+		return model.OperationStateFailed
+
+	case chainv1.TransferStatus_TRANSFER_CANCELLED:
+		return model.OperationStateCancelled
+
+	default:
+		return model.OperationStatePlanned
+	}
+}
+
+func setExecutionStepMetadata(step *model.ExecutionStep, key, value string) {
+	if step == nil {
+		return
+	}
+	key = strings.TrimSpace(key)
+	if key == "" {
+		return
+	}
+	value = strings.TrimSpace(value)
+	if value == "" {
+		if step.Metadata != nil {
+			delete(step.Metadata, key)
+			if len(step.Metadata) == 0 {
+				step.Metadata = nil
+			}
+		}
+		return
+	}
+	if step.Metadata == nil {
+		step.Metadata = map[string]string{}
+	}
+	step.Metadata[key] = value
+}

api/payments/quotation/internal/service/orchestrator/gateway_execution_consumer.go

@@ -0,0 +1,295 @@
+package orchestrator
+
+import (
+	"context"
+	"fmt"
+	"strings"
+
+	paymodel "github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	cons "github.com/tech/sendico/pkg/messaging/consumer"
+	paymentgateway "github.com/tech/sendico/pkg/messaging/notifications/paymentgateway"
+	np "github.com/tech/sendico/pkg/messaging/notifications/processor"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/model"
+	"github.com/tech/sendico/pkg/payments/rail"
+	"go.uber.org/zap"
+)
+
+func (s *Service) startGatewayConsumers() {
+	if s == nil || s.gatewayBroker == nil {
+		s.logger.Warn("Missing broker. Gateway feedback consumer has NOT started")
+		return
+	}
+	s.logger.Info("Gateway feedback consumer started")
+	processor := paymentgateway.NewPaymentGatewayExecutionProcessor(s.logger, s.onGatewayExecution)
+	s.consumeGatewayProcessor(processor)
+}
+
+func (s *Service) consumeGatewayProcessor(processor np.EnvelopeProcessor) {
+	consumer, err := cons.NewConsumer(s.logger, s.gatewayBroker, processor.GetSubject())
+	if err != nil {
+		s.logger.Warn("Failed to create payment gateway consumer", zap.Error(err), zap.String("event", processor.GetSubject().ToString()))
+		return
+	}
+	s.gatewayConsumers = append(s.gatewayConsumers, consumer)
+	go func() {
+		if err := consumer.ConsumeMessages(processor.Process); err != nil {
+			s.logger.Warn("Payment gateway consumer stopped", zap.Error(err), zap.String("event", processor.GetSubject().ToString()))
+		}
+	}()
+}
+
+func executionPlanSucceeded(plan *paymodel.ExecutionPlan) bool {
+	for _, s := range plan.Steps {
+		if !s.IsTerminal() {
+			return false
+		}
+		if s.State != paymodel.OperationStateSuccess {
+			return false
+		}
+	}
+	return true
+}
+
+func executionPlanFailed(plan *paymodel.ExecutionPlan) bool {
+	hasFailed := false
+
+	for _, s := range plan.Steps {
+		if !s.IsTerminal() {
+			return false
+		}
+		if s.State == paymodel.OperationStateFailed {
+			hasFailed = true
+		}
+	}
+
+	return hasFailed
+}
+
+func (s *Service) onGatewayExecution(ctx context.Context, exec *model.PaymentGatewayExecution) error {
+	if exec == nil {
+		return merrors.InvalidArgument("payment gateway execution is nil", "execution")
+	}
+
+	paymentRef := strings.TrimSpace(exec.PaymentRef)
+	if paymentRef == "" {
+		return merrors.InvalidArgument("payment_ref is required", "payment_ref")
+	}
+
+	store := s.storage.Payments()
+
+	payment, err := store.GetByPaymentRef(ctx, paymentRef)
+	if err != nil {
+		s.logger.Warn("Failed to fetch payment from database", zap.Error(err))
+		return err
+	}
+
+	// --- metadata
+	if payment.Metadata == nil {
+		payment.Metadata = map[string]string{}
+	}
+	payment.Metadata["gateway_operation_result"] = string(exec.Status)
+	payment.Metadata["gateway_operation_ref"] = exec.OperationRef
+	payment.Metadata["gateway_request_idempotency"] = exec.IdempotencyKey
+
+	// --- update exactly ONE step
+
+	if payment.State, err = updateExecutionStepsFromGatewayExecution(s.logger, payment, exec); err != nil {
+		s.logger.Warn("No execution step matched gateway result",
+			zap.String("payment_ref", paymentRef),
+			zap.String("operation_ref", exec.OperationRef),
+			zap.String("idempotency", exec.IdempotencyKey),
+		)
+	}
+
+	if err := store.Update(ctx, payment); err != nil {
+		return err
+	}
+
+	// reload unified state
+	payment, err = store.GetByPaymentRef(ctx, paymentRef)
+	if err != nil {
+		return err
+	}
+
+	// --- if plan can continue — continue
+	if payment.ExecutionPlan != nil && !executionPlanComplete(payment.ExecutionPlan) {
+		return s.resumePaymentPlan(ctx, store, payment)
+	}
+
+	// --- plan is terminal: decide payment fate by aggregation
+	if payment.ExecutionPlan != nil && executionPlanComplete(payment.ExecutionPlan) {
+		switch {
+		case executionPlanSucceeded(payment.ExecutionPlan):
+			payment.State = paymodel.PaymentStateSettled
+
+		case executionPlanFailed(payment.ExecutionPlan):
+			payment.State = paymodel.PaymentStateFailed
+			payment.FailureReason = "execution_plan_failed"
+		}
+
+		return store.Update(ctx, payment)
+	}
+
+	return nil
+}
+
+func updateExecutionStepsFromGatewayExecution(
+	logger mlogger.Logger,
+	payment *paymodel.Payment,
+	exec *model.PaymentGatewayExecution,
+) (paymodel.PaymentState, error) {
+
+	log := logger.With(
+		zap.String("payment_ref", payment.PaymentRef),
+		zap.String("operation_ref", strings.TrimSpace(exec.OperationRef)),
+		zap.String("gateway_status", string(exec.Status)),
+	)
+
+	log.Debug("gateway execution received")
+
+	if payment == nil || payment.PaymentPlan == nil || exec == nil {
+		log.Warn("invalid input: payment/plan/exec is nil")
+		return paymodel.PaymentStateSubmitted,
+			merrors.DataConflict("payment is missing plan or execution step")
+	}
+
+	operationRef := strings.TrimSpace(exec.OperationRef)
+	if operationRef == "" {
+		log.Warn("empty operation_ref from gateway")
+		return paymodel.PaymentStateSubmitted,
+			merrors.InvalidArgument("no operation reference provided")
+	}
+
+	execPlan := ensureExecutionPlanForPlan(payment, payment.PaymentPlan)
+	if execPlan == nil {
+		log.Warn("Execution plan missing")
+		return paymodel.PaymentStateSubmitted, merrors.InvalidArgument("execution plan missing")
+	}
+
+	status := executionStepStatusFromGatewayStatus(exec.Status)
+	if status == "" {
+		log.Warn("Unknown gateway status")
+		return paymodel.PaymentStateSubmitted,
+			merrors.DataConflict(fmt.Sprintf("unknown gateway status: %s", exec.Status))
+	}
+
+	var matched bool
+
+	for idx, execStep := range execPlan.Steps {
+		if execStep == nil {
+			continue
+		}
+
+		if strings.EqualFold(strings.TrimSpace(execStep.OperationRef), operationRef) {
+
+			log.Debug("Execution step matched",
+				zap.Int("step_index", idx),
+				zap.String("step_code", execStep.Code),
+				zap.String("prev_state", string(execStep.State)),
+			)
+
+			if execStep.TransferRef == "" && exec.TransferRef != "" {
+				execStep.TransferRef = strings.TrimSpace(exec.TransferRef)
+				log.Debug("Transfer_ref attached to step", zap.String("transfer_ref", execStep.TransferRef))
+			}
+
+			setExecutionStepStatus(execStep, status)
+			if exec.Error != "" && execStep.Error == "" {
+				execStep.Error = strings.TrimSpace(exec.Error)
+			}
+
+			log.Debug("Execution step state updated",
+				zap.Int("step_index", idx),
+				zap.String("step_code", execStep.Code),
+				zap.String("new_state", string(execStep.State)),
+			)
+
+			matched = true
+			break
+		}
+	}
+
+	if !matched {
+		log.Warn("No execution step found for operation_ref")
+		return paymodel.PaymentStateSubmitted,
+			merrors.InvalidArgument(
+				fmt.Sprintf("execution step not found for operation reference: %s", operationRef),
+			)
+	}
+
+	// -------- GLOBAL REDUCTION --------
+
+	var (
+		hasSuccess bool
+		allDone    = true
+	)
+
+	for idx, step := range execPlan.Steps {
+		if step == nil {
+			continue
+		}
+
+		log.Debug("Evaluating step for payment state",
+			zap.Int("step_index", idx),
+			zap.String("step_code", step.Code),
+			zap.String("step_state", string(step.State)),
+		)
+
+		switch step.State {
+		case paymodel.OperationStateFailed:
+			payment.FailureReason = step.Error
+			log.Info("Payment marked as FAILED due to step failure",
+				zap.String("failed_step_code", step.Code),
+				zap.String("error", step.Error),
+			)
+			return paymodel.PaymentStateFailed, nil
+
+		case paymodel.OperationStateSuccess:
+			hasSuccess = true
+
+		case paymodel.OperationStateSkipped:
+			// ok
+
+		default:
+			allDone = false
+		}
+	}
+
+	if hasSuccess && allDone {
+		log.Info("Payment marked as SUCCESS (all steps completed)")
+		return paymodel.PaymentStateSuccess, nil
+	}
+
+	log.Info("Payment still PROCESSING (steps not finished)")
+	return paymodel.PaymentStateSubmitted, nil
+}
+
+func executionStepStatusFromGatewayStatus(status rail.OperationResult) paymodel.OperationState {
+	switch status {
+
+	case rail.OperationResultSuccess:
+		return paymodel.OperationStateSuccess
+
+	case rail.OperationResultFailed:
+		return paymodel.OperationStateFailed
+
+	case rail.OperationResultCancelled:
+		return paymodel.OperationStateCancelled
+
+	default:
+		return paymodel.OperationStateFailed
+	}
+}
+
+func (s *Service) Shutdown() {
+	if s == nil {
+		return
+	}
+	for _, consumer := range s.gatewayConsumers {
+		if consumer != nil {
+			consumer.Close()
+		}
+	}
+}

api/payments/quotation/internal/service/orchestrator/gateway_registry.go

@@ -0,0 +1,120 @@
+package orchestrator
+
+import (
+	"context"
+	"sort"
+	"strings"
+
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/mlogger"
+)
+
+type gatewayRegistry struct {
+	logger mlogger.Logger
+	static []*model.GatewayInstanceDescriptor
+}
+
+// NewGatewayRegistry aggregates static gateway descriptors.
+func NewGatewayRegistry(logger mlogger.Logger, static []*model.GatewayInstanceDescriptor) GatewayRegistry {
+	if len(static) == 0 {
+		return nil
+	}
+	if logger != nil {
+		logger = logger.Named("gateway_registry")
+	}
+	return &gatewayRegistry{
+		logger: logger,
+		static: cloneGatewayDescriptors(static),
+	}
+}
+
+func (r *gatewayRegistry) List(ctx context.Context) ([]*model.GatewayInstanceDescriptor, error) {
+	items := map[string]*model.GatewayInstanceDescriptor{}
+	for _, gw := range r.static {
+		if gw == nil {
+			continue
+		}
+		id := strings.TrimSpace(gw.ID)
+		if id == "" {
+			continue
+		}
+		items[id] = cloneGatewayDescriptor(gw)
+	}
+
+	result := make([]*model.GatewayInstanceDescriptor, 0, len(items))
+	for _, gw := range items {
+		result = append(result, gw)
+	}
+	sort.Slice(result, func(i, j int) bool {
+		return result[i].ID < result[j].ID
+	})
+	return result, nil
+}
+
+func normalizeCurrencies(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	seen := map[string]bool{}
+	result := make([]string, 0, len(values))
+	for _, value := range values {
+		clean := strings.ToUpper(strings.TrimSpace(value))
+		if clean == "" || seen[clean] {
+			continue
+		}
+		seen[clean] = true
+		result = append(result, clean)
+	}
+	return result
+}
+
+func cloneGatewayDescriptors(src []*model.GatewayInstanceDescriptor) []*model.GatewayInstanceDescriptor {
+	if len(src) == 0 {
+		return nil
+	}
+	result := make([]*model.GatewayInstanceDescriptor, 0, len(src))
+	for _, item := range src {
+		if item == nil {
+			continue
+		}
+		if cloned := cloneGatewayDescriptor(item); cloned != nil {
+			result = append(result, cloned)
+		}
+	}
+	return result
+}
+
+func cloneGatewayDescriptor(src *model.GatewayInstanceDescriptor) *model.GatewayInstanceDescriptor {
+	if src == nil {
+		return nil
+	}
+	dst := *src
+	if src.Currencies != nil {
+		dst.Currencies = append([]string(nil), src.Currencies...)
+	}
+	dst.Limits = cloneLimits(src.Limits)
+	return &dst
+}
+
+func cloneLimits(src model.Limits) model.Limits {
+	dst := src
+	if src.VolumeLimit != nil {
+		dst.VolumeLimit = map[string]string{}
+		for key, value := range src.VolumeLimit {
+			dst.VolumeLimit[key] = value
+		}
+	}
+	if src.VelocityLimit != nil {
+		dst.VelocityLimit = map[string]int{}
+		for key, value := range src.VelocityLimit {
+			dst.VelocityLimit[key] = value
+		}
+	}
+	if src.CurrencyLimits != nil {
+		dst.CurrencyLimits = map[string]model.LimitsOverride{}
+		for key, value := range src.CurrencyLimits {
+			dst.CurrencyLimits[key] = value
+		}
+	}
+	return dst
+}

api/payments/quotation/internal/service/orchestrator/gateway_resolution.go

@@ -0,0 +1,138 @@
+package orchestrator
+
+import (
+	"context"
+	"sort"
+	"strings"
+
+	"github.com/shopspring/decimal"
+	chainclient "github.com/tech/sendico/gateway/chain/client"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+	"go.uber.org/zap"
+)
+
+func (s *Service) resolveChainGatewayClient(ctx context.Context, network string, amount *paymenttypes.Money, actions []model.RailOperation, instanceID string, paymentRef string) (chainclient.Client, *model.GatewayInstanceDescriptor, error) {
+	if s.deps.gatewayRegistry != nil && s.deps.gatewayInvokeResolver != nil {
+		entry, err := selectGatewayForActions(ctx, s.deps.gatewayRegistry, model.RailCrypto, network, amount, actions, instanceID, sendDirectionForRail(model.RailCrypto))
+		if err != nil {
+			return nil, nil, err
+		}
+		invokeURI := strings.TrimSpace(entry.InvokeURI)
+		if invokeURI == "" {
+			return nil, nil, merrors.InvalidArgument("chain gateway: invoke uri is required")
+		}
+		client, err := s.deps.gatewayInvokeResolver.Resolve(ctx, invokeURI)
+		if err != nil {
+			return nil, nil, err
+		}
+		if s.logger != nil {
+			fields := []zap.Field{
+				zap.String("gateway_id", entry.ID),
+				zap.String("instance_id", entry.InstanceID),
+				zap.String("rail", string(entry.Rail)),
+				zap.String("network", entry.Network),
+				zap.String("invoke_uri", invokeURI),
+			}
+			if paymentRef != "" {
+				fields = append(fields, zap.String("payment_ref", paymentRef))
+			}
+			if len(actions) > 0 {
+				fields = append(fields, zap.Strings("actions", railActionNames(actions)))
+			}
+			s.logger.Info("Chain gateway selected", fields...)
+		}
+		return client, entry, nil
+	}
+	if s.deps.gateway.resolver != nil {
+		client, err := s.deps.gateway.resolver.Resolve(ctx, network)
+		if err != nil {
+			return nil, nil, err
+		}
+		return client, nil, nil
+	}
+	return nil, nil, merrors.NoData("chain gateway unavailable")
+}
+
+func selectGatewayForActions(ctx context.Context, registry GatewayRegistry, rail model.Rail, network string, amount *paymenttypes.Money, actions []model.RailOperation, instanceID string, dir sendDirection) (*model.GatewayInstanceDescriptor, error) {
+	if registry == nil {
+		return nil, merrors.NoData("gateway registry unavailable")
+	}
+	all, err := registry.List(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if len(all) == 0 {
+		return nil, merrors.NoData("no gateway instances available")
+	}
+	if len(actions) == 0 {
+		actions = []model.RailOperation{model.RailOperationSend}
+	}
+
+	currency := ""
+	amt := decimal.Zero
+	if amount != nil && strings.TrimSpace(amount.GetAmount()) != "" {
+		amt, err = decimalFromMoney(amount)
+		if err != nil {
+			return nil, err
+		}
+		currency = strings.ToUpper(strings.TrimSpace(amount.GetCurrency()))
+	}
+	network = strings.ToUpper(strings.TrimSpace(network))
+
+	eligible := make([]*model.GatewayInstanceDescriptor, 0)
+	var lastErr error
+	for _, entry := range all {
+		if entry == nil || !entry.IsEnabled {
+			continue
+		}
+		if entry.Rail != rail {
+			continue
+		}
+		if instanceID != "" && !strings.EqualFold(strings.TrimSpace(entry.InstanceID), strings.TrimSpace(instanceID)) {
+			continue
+		}
+		ok := true
+		for _, action := range actions {
+			if err := isGatewayEligible(entry, rail, network, currency, action, dir, amt); err != nil {
+				lastErr = err
+				ok = false
+				break
+			}
+		}
+		if !ok {
+			continue
+		}
+		eligible = append(eligible, entry)
+	}
+
+	if len(eligible) == 0 {
+		if lastErr != nil {
+			return nil, merrors.NoData("no eligible gateway instance found: " + lastErr.Error())
+		}
+		return nil, merrors.NoData("no eligible gateway instance found")
+	}
+	sort.Slice(eligible, func(i, j int) bool {
+		return eligible[i].ID < eligible[j].ID
+	})
+	return eligible[0], nil
+}
+
+func railActionNames(actions []model.RailOperation) []string {
+	if len(actions) == 0 {
+		return nil
+	}
+	names := make([]string, 0, len(actions))
+	for _, action := range actions {
+		name := strings.TrimSpace(string(action))
+		if name == "" {
+			continue
+		}
+		names = append(names, name)
+	}
+	if len(names) == 0 {
+		return nil
+	}
+	return names
+}

api/payments/quotation/internal/service/orchestrator/handlers_commands.go

@@ -0,0 +1,922 @@
+package orchestrator
+
+import (
+	"context"
+	"crypto/sha256"
+	"encoding/hex"
+	"errors"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/google/uuid"
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/api/routers/gsresponse"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/mservice"
+	"github.com/tech/sendico/pkg/mutil/mzap"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"go.mongodb.org/mongo-driver/v2/bson"
+	"go.uber.org/zap"
+	"google.golang.org/protobuf/proto"
+)
+
+type quotePaymentCommand struct {
+	engine paymentEngine
+	logger mlogger.Logger
+}
+
+var (
+	errIdempotencyRequired      = errors.New("idempotency key is required")
+	errPreviewWithIdempotency   = errors.New("preview requests must not use idempotency key")
+	errIdempotencyParamMismatch = errors.New("idempotency key reuse with different parameters")
+)
+
+type quoteCtx struct {
+	orgID          string
+	orgRef         bson.ObjectID
+	intent         *orchestratorv1.PaymentIntent
+	previewOnly    bool
+	idempotencyKey string
+	hash           string
+}
+
+func (h *quotePaymentCommand) Execute(
+	ctx context.Context,
+	req *orchestratorv1.QuotePaymentRequest,
+) gsresponse.Responder[orchestratorv1.QuotePaymentResponse] {
+
+	if err := h.engine.EnsureRepository(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.QuotePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.QuotePaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+
+	qc, err := h.prepareQuoteCtx(req)
+	if err != nil {
+		return h.mapQuoteErr(err)
+	}
+
+	quotesStore, err := ensureQuotesStore(h.engine.Repository())
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.QuotePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	quoteProto, err := h.quotePayment(ctx, quotesStore, qc, req)
+	if err != nil {
+		return h.mapQuoteErr(err)
+	}
+
+	return gsresponse.Success(&orchestratorv1.QuotePaymentResponse{
+		IdempotencyKey: req.GetIdempotencyKey(),
+		Quote:          quoteProto,
+	})
+}
+
+func (h *quotePaymentCommand) prepareQuoteCtx(req *orchestratorv1.QuotePaymentRequest) (*quoteCtx, error) {
+	orgRef, orgID, err := validateMetaAndOrgRef(req.GetMeta())
+	if err != nil {
+		return nil, err
+	}
+	if err := requireNonNilIntent(req.GetIntent()); err != nil {
+		return nil, err
+	}
+
+	intent := req.GetIntent()
+	preview := req.GetPreviewOnly()
+	idem := strings.TrimSpace(req.GetIdempotencyKey())
+
+	if preview && idem != "" {
+		return nil, errPreviewWithIdempotency
+	}
+	if !preview && idem == "" {
+		return nil, errIdempotencyRequired
+	}
+
+	return &quoteCtx{
+		orgID:          orgRef,
+		orgRef:         orgID,
+		intent:         intent,
+		previewOnly:    preview,
+		idempotencyKey: idem,
+		hash:           hashQuoteRequest(req),
+	}, nil
+}
+
+func (h *quotePaymentCommand) quotePayment(
+	ctx context.Context,
+	quotesStore storage.QuotesStore,
+	qc *quoteCtx,
+	req *orchestratorv1.QuotePaymentRequest,
+) (*orchestratorv1.PaymentQuote, error) {
+
+	if qc.previewOnly {
+		quote, _, err := h.engine.BuildPaymentQuote(ctx, qc.orgID, req)
+		if err != nil {
+			h.logger.Warn("Failed to build preview payment quote", zap.Error(err), zap.String("org_ref", qc.orgID))
+			return nil, err
+		}
+		quote.QuoteRef = bson.NewObjectID().Hex()
+		return quote, nil
+	}
+
+	existing, err := quotesStore.GetByIdempotencyKey(ctx, qc.orgRef, qc.idempotencyKey)
+	if err != nil && !errors.Is(err, storage.ErrQuoteNotFound) && !errors.Is(err, merrors.ErrNoData) {
+		h.logger.Warn("Failed to lookup quote by idempotency key", zap.Error(err),
+			mzap.ObjRef("org_ref", qc.orgRef), zap.String("idempotency_key", qc.idempotencyKey),
+		)
+		return nil, err
+	}
+	if existing != nil {
+		if existing.Hash != qc.hash {
+			return nil, errIdempotencyParamMismatch
+		}
+		h.logger.Debug(
+			"Idempotent quote reused",
+			mzap.ObjRef("org_ref", qc.orgRef),
+			zap.String("idempotency_key", qc.idempotencyKey),
+			zap.String("quote_ref", existing.QuoteRef),
+		)
+		return modelQuoteToProto(existing.Quote), nil
+	}
+
+	quote, expiresAt, err := h.engine.BuildPaymentQuote(ctx, qc.orgID, req)
+	if err != nil {
+		h.logger.Warn(
+			"Failed to build payment quote",
+			zap.Error(err),
+			mzap.ObjRef("org_ref", qc.orgRef),
+			zap.String("idempotency_key", qc.idempotencyKey),
+		)
+		return nil, err
+	}
+
+	quoteRef := bson.NewObjectID().Hex()
+	quote.QuoteRef = quoteRef
+
+	record := &model.PaymentQuoteRecord{
+		QuoteRef:       quoteRef,
+		IdempotencyKey: qc.idempotencyKey,
+		Hash:           qc.hash,
+		Intent:         intentFromProto(qc.intent),
+		Quote:          quoteSnapshotToModel(quote),
+		ExpiresAt:      expiresAt,
+	}
+	record.SetID(bson.NewObjectID())
+	record.SetOrganizationRef(qc.orgRef)
+
+	if err := quotesStore.Create(ctx, record); err != nil {
+		if errors.Is(err, storage.ErrDuplicateQuote) {
+			existing, getErr := quotesStore.GetByIdempotencyKey(ctx, qc.orgRef, qc.idempotencyKey)
+			if getErr == nil && existing != nil {
+				if existing.Hash != qc.hash {
+					return nil, errIdempotencyParamMismatch
+				}
+				return modelQuoteToProto(existing.Quote), nil
+			}
+		}
+		return nil, err
+	}
+
+	h.logger.Info(
+		"Stored payment quote",
+		zap.String("quote_ref", quoteRef),
+		mzap.ObjRef("org_ref", qc.orgRef),
+		zap.String("idempotency_key", qc.idempotencyKey),
+		zap.String("kind", qc.intent.GetKind().String()),
+	)
+
+	return quote, nil
+}
+
+func (h *quotePaymentCommand) mapQuoteErr(err error) gsresponse.Responder[orchestratorv1.QuotePaymentResponse] {
+	if errors.Is(err, errIdempotencyRequired) ||
+		errors.Is(err, errPreviewWithIdempotency) ||
+		errors.Is(err, errIdempotencyParamMismatch) {
+		return gsresponse.InvalidArgument[orchestratorv1.QuotePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	return gsresponse.Auto[orchestratorv1.QuotePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+}
+
+// TODO: temprorarary hashing function, replace with a proper solution later
+func hashQuoteRequest(req *orchestratorv1.QuotePaymentRequest) string {
+	cloned := proto.Clone(req).(*orchestratorv1.QuotePaymentRequest)
+	cloned.Meta = nil
+	cloned.IdempotencyKey = ""
+	cloned.PreviewOnly = false
+
+	b, err := proto.MarshalOptions{Deterministic: true}.Marshal(cloned)
+	if err != nil {
+		sum := sha256.Sum256([]byte("marshal_error"))
+		return hex.EncodeToString(sum[:])
+	}
+
+	sum := sha256.Sum256(b)
+	return hex.EncodeToString(sum[:])
+}
+
+type quotePaymentsCommand struct {
+	engine paymentEngine
+	logger mlogger.Logger
+}
+
+var (
+	errBatchIdempotencyRequired      = errors.New("idempotency key is required")
+	errBatchPreviewWithIdempotency   = errors.New("preview requests must not use idempotency key")
+	errBatchIdempotencyParamMismatch = errors.New("idempotency key reuse with different parameters")
+	errBatchIdempotencyShapeMismatch = errors.New("idempotency key already used for a different quote shape")
+)
+
+type quotePaymentsCtx struct {
+	orgID          string
+	orgRef         bson.ObjectID
+	previewOnly    bool
+	idempotencyKey string
+	hash           string
+	intentCount    int
+}
+
+func (h *quotePaymentsCommand) Execute(
+	ctx context.Context,
+	req *orchestratorv1.QuotePaymentsRequest,
+) gsresponse.Responder[orchestratorv1.QuotePaymentsResponse] {
+
+	if err := h.engine.EnsureRepository(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+
+	qc, intents, err := h.prepare(req)
+	if err != nil {
+		return h.mapErr(err)
+	}
+
+	quotesStore, err := ensureQuotesStore(h.engine.Repository())
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	if qc.previewOnly {
+		quotes, expires, err := h.buildQuotes(ctx, req.GetMeta(), qc.idempotencyKey, intents, true)
+		if err != nil {
+			return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+		aggregate, expiresAt, err := h.aggregate(quotes, expires)
+		if err != nil {
+			return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+		_ = expiresAt
+		return gsresponse.Success(&orchestratorv1.QuotePaymentsResponse{
+			QuoteRef:  "",
+			Aggregate: aggregate,
+			Quotes:    quotes,
+		})
+	}
+
+	if rec, ok, err := h.tryReuse(ctx, quotesStore, qc); err != nil {
+		return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	} else if ok {
+		return gsresponse.Success(h.responseFromRecord(rec))
+	}
+
+	quotes, expires, err := h.buildQuotes(ctx, req.GetMeta(), qc.idempotencyKey, intents, false)
+	if err != nil {
+		return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	aggregate, expiresAt, err := h.aggregate(quotes, expires)
+	if err != nil {
+		return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	quoteRef := bson.NewObjectID().Hex()
+	for _, q := range quotes {
+		if q != nil {
+			q.QuoteRef = quoteRef
+		}
+	}
+
+	rec, err := h.storeBatch(ctx, quotesStore, qc, quoteRef, intents, quotes, expiresAt)
+	if err != nil {
+		return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	if rec != nil {
+		return gsresponse.Success(h.responseFromRecord(rec))
+	}
+
+	h.logger.Info(
+		"Stored payment quotes",
+		h.logFields(qc, quoteRef, expiresAt, len(quotes))...,
+	)
+
+	return gsresponse.Success(&orchestratorv1.QuotePaymentsResponse{
+		IdempotencyKey: req.GetIdempotencyKey(),
+		QuoteRef:       quoteRef,
+		Aggregate:      aggregate,
+		Quotes:         quotes,
+	})
+}
+
+func (h *quotePaymentsCommand) prepare(req *orchestratorv1.QuotePaymentsRequest) (*quotePaymentsCtx, []*orchestratorv1.PaymentIntent, error) {
+	orgRefStr, orgID, err := validateMetaAndOrgRef(req.GetMeta())
+	if err != nil {
+		return nil, nil, err
+	}
+
+	intents := req.GetIntents()
+	if len(intents) == 0 {
+		return nil, nil, merrors.InvalidArgument("intents are required")
+	}
+	for _, intent := range intents {
+		if err := requireNonNilIntent(intent); err != nil {
+			return nil, nil, err
+		}
+	}
+
+	preview := req.GetPreviewOnly()
+	idem := strings.TrimSpace(req.GetIdempotencyKey())
+
+	if preview && idem != "" {
+		return nil, nil, errBatchPreviewWithIdempotency
+	}
+	if !preview && idem == "" {
+		return nil, nil, errBatchIdempotencyRequired
+	}
+
+	hash, err := hashQuotePaymentsIntents(intents)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	return &quotePaymentsCtx{
+		orgID:          orgRefStr,
+		orgRef:         orgID,
+		previewOnly:    preview,
+		idempotencyKey: idem,
+		hash:           hash,
+		intentCount:    len(intents),
+	}, intents, nil
+}
+
+func (h *quotePaymentsCommand) tryReuse(
+	ctx context.Context,
+	quotesStore storage.QuotesStore,
+	qc *quotePaymentsCtx,
+) (*model.PaymentQuoteRecord, bool, error) {
+
+	rec, err := quotesStore.GetByIdempotencyKey(ctx, qc.orgRef, qc.idempotencyKey)
+	if err != nil {
+		if errors.Is(err, storage.ErrQuoteNotFound) {
+			return nil, false, nil
+		}
+		h.logger.Warn(
+			"Failed to lookup payment quotes by idempotency key",
+			h.logFields(qc, "", time.Time{}, 0)...,
+		)
+		return nil, false, err
+	}
+
+	if len(rec.Quotes) == 0 {
+		return nil, false, errBatchIdempotencyShapeMismatch
+	}
+	if rec.Hash != qc.hash {
+		return nil, false, errBatchIdempotencyParamMismatch
+	}
+
+	h.logger.Debug(
+		"Idempotent payment quotes reused",
+		h.logFields(qc, rec.QuoteRef, rec.ExpiresAt, len(rec.Quotes))...,
+	)
+
+	return rec, true, nil
+}
+
+func (h *quotePaymentsCommand) buildQuotes(
+	ctx context.Context,
+	meta *orchestratorv1.RequestMeta,
+	baseKey string,
+	intents []*orchestratorv1.PaymentIntent,
+	preview bool,
+) ([]*orchestratorv1.PaymentQuote, []time.Time, error) {
+
+	quotes := make([]*orchestratorv1.PaymentQuote, 0, len(intents))
+	expires := make([]time.Time, 0, len(intents))
+
+	for i, intent := range intents {
+		req := &orchestratorv1.QuotePaymentRequest{
+			Meta:           meta,
+			IdempotencyKey: perIntentIdempotencyKey(baseKey, i, len(intents)),
+			Intent:         intent,
+			PreviewOnly:    preview,
+		}
+		q, exp, err := h.engine.BuildPaymentQuote(ctx, meta.GetOrganizationRef(), req)
+		if err != nil {
+			h.logger.Warn(
+				"Failed to build payment quote (batch item)",
+				zap.Int("idx", i),
+				zap.Error(err),
+			)
+			return nil, nil, err
+		}
+		quotes = append(quotes, q)
+		expires = append(expires, exp)
+	}
+
+	return quotes, expires, nil
+}
+
+func (h *quotePaymentsCommand) aggregate(
+	quotes []*orchestratorv1.PaymentQuote,
+	expires []time.Time,
+) (*orchestratorv1.PaymentQuoteAggregate, time.Time, error) {
+
+	agg, err := aggregatePaymentQuotes(quotes)
+	if err != nil {
+		return nil, time.Time{}, merrors.InternalWrap(err, "quote aggregation failed")
+	}
+
+	expiresAt, ok := minQuoteExpiry(expires)
+	if !ok {
+		return nil, time.Time{}, merrors.Internal("quote expiry missing")
+	}
+
+	return agg, expiresAt, nil
+}
+
+func (h *quotePaymentsCommand) storeBatch(
+	ctx context.Context,
+	quotesStore storage.QuotesStore,
+	qc *quotePaymentsCtx,
+	quoteRef string,
+	intents []*orchestratorv1.PaymentIntent,
+	quotes []*orchestratorv1.PaymentQuote,
+	expiresAt time.Time,
+) (*model.PaymentQuoteRecord, error) {
+
+	record := &model.PaymentQuoteRecord{
+		QuoteRef:       quoteRef,
+		IdempotencyKey: qc.idempotencyKey,
+		Hash:           qc.hash,
+		Intents:        intentsFromProto(intents),
+		Quotes:         quoteSnapshotsFromProto(quotes),
+		ExpiresAt:      expiresAt,
+	}
+	record.SetID(bson.NewObjectID())
+	record.SetOrganizationRef(qc.orgRef)
+
+	if err := quotesStore.Create(ctx, record); err != nil {
+		if errors.Is(err, storage.ErrDuplicateQuote) {
+			rec, ok, reuseErr := h.tryReuse(ctx, quotesStore, qc)
+			if reuseErr != nil {
+				return nil, reuseErr
+			}
+			if ok {
+				return rec, nil
+			}
+			return nil, err
+		}
+		return nil, err
+	}
+
+	return nil, nil
+}
+
+func (h *quotePaymentsCommand) responseFromRecord(rec *model.PaymentQuoteRecord) *orchestratorv1.QuotePaymentsResponse {
+	quotes := modelQuotesToProto(rec.Quotes)
+	for _, q := range quotes {
+		if q != nil {
+			q.QuoteRef = rec.QuoteRef
+		}
+	}
+	aggregate, _ := aggregatePaymentQuotes(quotes)
+
+	return &orchestratorv1.QuotePaymentsResponse{
+		QuoteRef:  rec.QuoteRef,
+		Aggregate: aggregate,
+		Quotes:    quotes,
+	}
+}
+
+func (h *quotePaymentsCommand) logFields(qc *quotePaymentsCtx, quoteRef string, expiresAt time.Time, quoteCount int) []zap.Field {
+	fields := []zap.Field{
+		mzap.ObjRef("org_ref", qc.orgRef),
+		zap.String("org_ref_str", qc.orgID),
+		zap.String("idempotency_key", qc.idempotencyKey),
+		zap.String("hash", qc.hash),
+		zap.Bool("preview_only", qc.previewOnly),
+		zap.Int("intent_count", qc.intentCount),
+	}
+	if quoteRef != "" {
+		fields = append(fields, zap.String("quote_ref", quoteRef))
+	}
+	if !expiresAt.IsZero() {
+		fields = append(fields, zap.Time("expires_at", expiresAt))
+	}
+	if quoteCount > 0 {
+		fields = append(fields, zap.Int("quote_count", quoteCount))
+	}
+	return fields
+}
+
+func (h *quotePaymentsCommand) mapErr(err error) gsresponse.Responder[orchestratorv1.QuotePaymentsResponse] {
+	if errors.Is(err, errBatchIdempotencyRequired) ||
+		errors.Is(err, errBatchPreviewWithIdempotency) ||
+		errors.Is(err, errBatchIdempotencyParamMismatch) ||
+		errors.Is(err, errBatchIdempotencyShapeMismatch) {
+		return gsresponse.InvalidArgument[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	return gsresponse.Auto[orchestratorv1.QuotePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+}
+
+func modelQuotesToProto(snaps []*model.PaymentQuoteSnapshot) []*orchestratorv1.PaymentQuote {
+	if len(snaps) == 0 {
+		return nil
+	}
+	out := make([]*orchestratorv1.PaymentQuote, 0, len(snaps))
+	for _, s := range snaps {
+		out = append(out, modelQuoteToProto(s))
+	}
+	return out
+}
+
+func hashQuotePaymentsIntents(intents []*orchestratorv1.PaymentIntent) (string, error) {
+	type item struct {
+		Idx int
+		H   [32]byte
+	}
+	items := make([]item, 0, len(intents))
+
+	for i, intent := range intents {
+		b, err := proto.MarshalOptions{Deterministic: true}.Marshal(intent)
+		if err != nil {
+			return "", err
+		}
+		items = append(items, item{Idx: i, H: sha256.Sum256(b)})
+	}
+
+	sort.Slice(items, func(i, j int) bool { return items[i].Idx < items[j].Idx })
+
+	h := sha256.New()
+	h.Write([]byte("quote-payments-fp/v1"))
+	h.Write([]byte{0})
+	for _, it := range items {
+		h.Write(it.H[:])
+		h.Write([]byte{0})
+	}
+
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+type initiatePaymentsCommand struct {
+	engine paymentEngine
+	logger mlogger.Logger
+}
+
+func (h *initiatePaymentsCommand) Execute(ctx context.Context, req *orchestratorv1.InitiatePaymentsRequest) gsresponse.Responder[orchestratorv1.InitiatePaymentsResponse] {
+	if err := h.engine.EnsureRepository(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+	_, orgRef, err := validateMetaAndOrgRef(req.GetMeta())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	idempotencyKey, err := requireIdempotencyKey(req.GetIdempotencyKey())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	quoteRef := strings.TrimSpace(req.GetQuoteRef())
+	if quoteRef == "" {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("quote_ref is required"))
+	}
+
+	quotesStore, err := ensureQuotesStore(h.engine.Repository())
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	record, err := quotesStore.GetByRef(ctx, orgRef, quoteRef)
+	if err != nil {
+		if errors.Is(err, storage.ErrQuoteNotFound) {
+			return gsresponse.FailedPrecondition[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, "quote_not_found", merrors.InvalidArgument("quote_ref not found or expired"))
+		}
+		return gsresponse.Auto[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	intents := record.Intents
+	quotes := record.Quotes
+	if len(intents) == 0 && record.Intent.Kind != "" && record.Intent.Kind != model.PaymentKindUnspecified {
+		intents = []model.PaymentIntent{record.Intent}
+	}
+	if len(quotes) == 0 && record.Quote != nil {
+		quotes = []*model.PaymentQuoteSnapshot{record.Quote}
+	}
+	if len(intents) == 0 || len(quotes) == 0 || len(intents) != len(quotes) {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("stored quote payload is incomplete"))
+	}
+
+	store, err := ensurePaymentsStore(h.engine.Repository())
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	payments := make([]*orchestratorv1.Payment, 0, len(intents))
+	for i := range intents {
+		intentProto := protoIntentFromModel(intents[i])
+		if err := requireNonNilIntent(intentProto); err != nil {
+			return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+		quoteProto := modelQuoteToProto(quotes[i])
+		if quoteProto == nil {
+			return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("stored quote is empty"))
+		}
+		quoteProto.QuoteRef = quoteRef
+
+		perKey := perIntentIdempotencyKey(idempotencyKey, i, len(intents))
+		if existing, err := getPaymentByIdempotencyKey(ctx, store, orgRef, perKey); err == nil && existing != nil {
+			payments = append(payments, toProtoPayment(existing))
+			continue
+		} else if err != nil && !errors.Is(err, storage.ErrPaymentNotFound) {
+			return gsresponse.Auto[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+
+		entity := newPayment(orgRef, intentProto, perKey, req.GetMetadata(), quoteProto)
+		if err = store.Create(ctx, entity); err != nil {
+			if errors.Is(err, storage.ErrDuplicatePayment) {
+				return gsresponse.Auto[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.DataConflict("payment already exists"))
+			}
+			return gsresponse.Auto[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+
+		if err := h.engine.ExecutePayment(ctx, store, entity, quoteProto); err != nil {
+			return gsresponse.Auto[orchestratorv1.InitiatePaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+
+		payments = append(payments, toProtoPayment(entity))
+	}
+
+	h.logger.Info(
+		"Payments initiated",
+		mzap.ObjRef("org_ref", orgRef),
+		zap.String("quote_ref", quoteRef),
+		zap.String("idempotency_key", idempotencyKey),
+		zap.Int("payment_count", len(payments)),
+	)
+	return gsresponse.Success(&orchestratorv1.InitiatePaymentsResponse{Payments: payments})
+}
+
+type initiatePaymentCommand struct {
+	engine paymentEngine
+	logger mlogger.Logger
+}
+
+func (h *initiatePaymentCommand) Execute(ctx context.Context, req *orchestratorv1.InitiatePaymentRequest) gsresponse.Responder[orchestratorv1.InitiatePaymentResponse] {
+	if err := h.engine.EnsureRepository(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+	orgRef, orgID, err := validateMetaAndOrgRef(req.GetMeta())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	intent := req.GetIntent()
+	quoteRef := strings.TrimSpace(req.GetQuoteRef())
+	hasIntent := intent != nil
+	hasQuote := quoteRef != ""
+	switch {
+	case !hasIntent && !hasQuote:
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("intent or quote_ref is required"))
+	case hasIntent && hasQuote:
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("intent and quote_ref are mutually exclusive"))
+	}
+	if hasIntent {
+		if err := requireNonNilIntent(intent); err != nil {
+			return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+	}
+	idempotencyKey, err := requireIdempotencyKey(req.GetIdempotencyKey())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	h.logger.Debug(
+		"Initiate payment request accepted",
+		mzap.ObjRef("org_ref", orgID),
+		zap.String("idempotency_key", idempotencyKey),
+		zap.String("quote_ref", quoteRef),
+		zap.Bool("has_intent", hasIntent),
+	)
+
+	store, err := ensurePaymentsStore(h.engine.Repository())
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	if existing, err := getPaymentByIdempotencyKey(ctx, store, orgID, idempotencyKey); err == nil && existing != nil {
+		h.logger.Debug(
+			"idempotent payment request reused",
+			zap.String("payment_ref", existing.PaymentRef),
+			mzap.ObjRef("org_ref", orgID),
+			zap.String("idempotency_key", idempotencyKey),
+			zap.String("quote_ref", quoteRef),
+		)
+		return gsresponse.Success(&orchestratorv1.InitiatePaymentResponse{Payment: toProtoPayment(existing)})
+	} else if err != nil && !errors.Is(err, storage.ErrPaymentNotFound) {
+		return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	quoteSnapshot, resolvedIntent, err := h.engine.ResolvePaymentQuote(ctx, quoteResolutionInput{
+		OrgRef:         orgRef,
+		OrgID:          orgID,
+		Meta:           req.GetMeta(),
+		Intent:         intent,
+		QuoteRef:       quoteRef,
+		IdempotencyKey: req.GetIdempotencyKey(),
+	})
+	if err != nil {
+		if qerr, ok := err.(quoteResolutionError); ok {
+			switch qerr.code {
+			case "quote_not_found":
+				return gsresponse.FailedPrecondition[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, qerr.code, qerr.err)
+			case "quote_expired":
+				return gsresponse.FailedPrecondition[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, qerr.code, qerr.err)
+			case "quote_intent_mismatch":
+				return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, qerr.err)
+			default:
+				return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, qerr.err)
+			}
+		}
+		return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if quoteSnapshot == nil {
+		quoteSnapshot = &orchestratorv1.PaymentQuote{}
+	}
+	if err := requireNonNilIntent(resolvedIntent); err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	h.logger.Debug(
+		"Payment quote resolved",
+		mzap.ObjRef("org_ref", orgID),
+		zap.String("quote_ref", quoteRef),
+		zap.Bool("quote_ref_used", quoteRef != ""),
+	)
+
+	entity := newPayment(orgID, resolvedIntent, idempotencyKey, req.GetMetadata(), quoteSnapshot)
+
+	if err = store.Create(ctx, entity); err != nil {
+		if errors.Is(err, storage.ErrDuplicatePayment) {
+			return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.DataConflict("payment already exists"))
+		}
+		return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	if err := h.engine.ExecutePayment(ctx, store, entity, quoteSnapshot); err != nil {
+		return gsresponse.Auto[orchestratorv1.InitiatePaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	h.logger.Info(
+		"Payment initiated",
+		zap.String("payment_ref", entity.PaymentRef),
+		mzap.ObjRef("org_ref", orgID),
+		zap.String("kind", resolvedIntent.GetKind().String()),
+		zap.String("quote_ref", quoteSnapshot.GetQuoteRef()),
+		zap.String("idempotency_key", idempotencyKey),
+	)
+	return gsresponse.Success(&orchestratorv1.InitiatePaymentResponse{
+		Payment: toProtoPayment(entity),
+	})
+}
+
+type cancelPaymentCommand struct {
+	engine paymentEngine
+	logger mlogger.Logger
+}
+
+func (h *cancelPaymentCommand) Execute(ctx context.Context, req *orchestratorv1.CancelPaymentRequest) gsresponse.Responder[orchestratorv1.CancelPaymentResponse] {
+	if err := h.engine.EnsureRepository(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.CancelPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.CancelPaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+	paymentRef, err := requirePaymentRef(req.GetPaymentRef())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.CancelPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	store, err := ensurePaymentsStore(h.engine.Repository())
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.CancelPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	payment, err := store.GetByPaymentRef(ctx, paymentRef)
+	if err != nil {
+		return paymentNotFoundResponder[orchestratorv1.CancelPaymentResponse](mservice.PaymentOrchestrator, h.logger, err)
+	}
+	if payment.State != model.PaymentStateAccepted {
+		reason := merrors.InvalidArgument("payment cannot be cancelled in current state")
+		return gsresponse.FailedPrecondition[orchestratorv1.CancelPaymentResponse](h.logger, mservice.PaymentOrchestrator, "payment_not_cancellable", reason)
+	}
+	payment.State = model.PaymentStateCancelled
+	payment.FailureCode = model.PaymentFailureCodePolicy
+	payment.FailureReason = strings.TrimSpace(req.GetReason())
+	if err := store.Update(ctx, payment); err != nil {
+		return gsresponse.Auto[orchestratorv1.CancelPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	h.logger.Info("Payment cancelled", zap.String("payment_ref", payment.PaymentRef), zap.String("org_ref", payment.OrganizationRef.Hex()))
+	return gsresponse.Success(&orchestratorv1.CancelPaymentResponse{Payment: toProtoPayment(payment)})
+}
+
+type initiateConversionCommand struct {
+	engine paymentEngine
+	logger mlogger.Logger
+}
+
+func (h *initiateConversionCommand) Execute(ctx context.Context, req *orchestratorv1.InitiateConversionRequest) gsresponse.Responder[orchestratorv1.InitiateConversionResponse] {
+	if err := h.engine.EnsureRepository(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+	orgRef, orgID, err := validateMetaAndOrgRef(req.GetMeta())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	idempotencyKey, err := requireIdempotencyKey(req.GetIdempotencyKey())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req.GetSource() == nil || req.GetSource().GetLedger() == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("source ledger endpoint is required"))
+	}
+	if req.GetDestination() == nil || req.GetDestination().GetLedger() == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("destination ledger endpoint is required"))
+	}
+	fxIntent := req.GetFx()
+	if fxIntent == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("fx intent is required"))
+	}
+
+	store, err := ensurePaymentsStore(h.engine.Repository())
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	if existing, err := getPaymentByIdempotencyKey(ctx, store, orgID, idempotencyKey); err == nil && existing != nil {
+		h.logger.Debug("Idempotent conversion request reused", zap.String("payment_ref", existing.PaymentRef), mzap.ObjRef("org_ref", orgID))
+		return gsresponse.Success(&orchestratorv1.InitiateConversionResponse{Conversion: toProtoPayment(existing)})
+	} else if err != nil && !errors.Is(err, storage.ErrPaymentNotFound) {
+		return gsresponse.Auto[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	amount, err := conversionAmountFromMetadata(req.GetMetadata(), fxIntent)
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	intentProto := &orchestratorv1.PaymentIntent{
+		Ref:                uuid.New().String(),
+		Kind:               orchestratorv1.PaymentKind_PAYMENT_KIND_FX_CONVERSION,
+		Source:             req.GetSource(),
+		Destination:        req.GetDestination(),
+		Amount:             amount,
+		RequiresFx:         true,
+		Fx:                 fxIntent,
+		FeePolicy:          req.GetFeePolicy(),
+		SettlementCurrency: strings.TrimSpace(amount.GetCurrency()),
+	}
+
+	quote, _, err := h.engine.BuildPaymentQuote(ctx, orgRef, &orchestratorv1.QuotePaymentRequest{
+		Meta:           req.GetMeta(),
+		IdempotencyKey: req.GetIdempotencyKey(),
+		Intent:         intentProto,
+	})
+	if err != nil {
+		return gsresponse.Auto[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	entity := newPayment(orgID, intentProto, idempotencyKey, req.GetMetadata(), quote)
+
+	if err = store.Create(ctx, entity); err != nil {
+		if errors.Is(err, storage.ErrDuplicatePayment) {
+			return gsresponse.Auto[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, merrors.DataConflict("payment already exists"))
+		}
+		return gsresponse.Auto[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	if err := h.engine.ExecutePayment(ctx, store, entity, quote); err != nil {
+		return gsresponse.Auto[orchestratorv1.InitiateConversionResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	h.logger.Info("Conversion initiated", zap.String("payment_ref", entity.PaymentRef), mzap.ObjRef("org_ref", orgID))
+	return gsresponse.Success(&orchestratorv1.InitiateConversionResponse{
+		Conversion: toProtoPayment(entity),
+	})
+}

api/payments/quotation/internal/service/orchestrator/handlers_events.go

@@ -0,0 +1,318 @@
+package orchestrator
+
+import (
+	"context"
+	"strings"
+
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/api/routers/gsresponse"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/mservice"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"go.uber.org/zap"
+)
+
+type paymentEventHandler struct {
+	repo             storage.Repository
+	ensureRepo       func(ctx context.Context) error
+	logger           mlogger.Logger
+	submitCardPayout func(ctx context.Context, operationRef string, payment *model.Payment) error
+	resumePlan       func(ctx context.Context, store storage.PaymentsStore, payment *model.Payment) error
+	releaseHold      func(ctx context.Context, store storage.PaymentsStore, payment *model.Payment) error
+}
+
+func newPaymentEventHandler(repo storage.Repository, ensure func(ctx context.Context) error, logger mlogger.Logger, submitCardPayout func(ctx context.Context, operationRef string, payment *model.Payment) error, resumePlan func(ctx context.Context, store storage.PaymentsStore, payment *model.Payment) error, releaseHold func(ctx context.Context, store storage.PaymentsStore, payment *model.Payment) error) *paymentEventHandler {
+	return &paymentEventHandler{
+		repo:             repo,
+		ensureRepo:       ensure,
+		logger:           logger,
+		submitCardPayout: submitCardPayout,
+		resumePlan:       resumePlan,
+		releaseHold:      releaseHold,
+	}
+}
+
+func (h *paymentEventHandler) processTransferUpdate(ctx context.Context, req *orchestratorv1.ProcessTransferUpdateRequest) gsresponse.Responder[orchestratorv1.ProcessTransferUpdateResponse] {
+	if err := h.ensureRepo(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil || req.GetEvent() == nil || req.GetEvent().GetTransfer() == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("transfer event is required"))
+	}
+	transfer := req.GetEvent().GetTransfer()
+	transferRef := strings.TrimSpace(transfer.GetTransferRef())
+	if transferRef == "" {
+		return gsresponse.InvalidArgument[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("transfer_ref is required"))
+	}
+	store := h.repo.Payments()
+	if store == nil {
+		return gsresponse.Unavailable[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, errStorageUnavailable)
+	}
+	payment, err := store.GetByChainTransferRef(ctx, transferRef)
+	if err != nil {
+		return paymentNotFoundResponder[orchestratorv1.ProcessTransferUpdateResponse](mservice.PaymentOrchestrator, h.logger, err)
+	}
+	if payment.PaymentPlan != nil && len(payment.PaymentPlan.Steps) > 0 {
+		if payment.ExecutionPlan == nil || len(payment.ExecutionPlan.Steps) != len(payment.PaymentPlan.Steps) {
+			ensureExecutionPlanForPlan(payment, payment.PaymentPlan)
+		}
+		updateExecutionStepFromTransfer(payment.ExecutionPlan, req.GetEvent())
+		if payment.Execution == nil {
+			payment.Execution = &model.ExecutionRefs{}
+		}
+		if payment.Execution.ChainTransferRef == "" {
+			payment.Execution.ChainTransferRef = transferRef
+		}
+		reason := transferFailureReason(req.GetEvent())
+		switch transfer.GetStatus() {
+		case chainv1.TransferStatus_TRANSFER_FAILED:
+			payment.State = model.PaymentStateFailed
+			payment.FailureCode = model.PaymentFailureCodeChain
+			payment.FailureReason = reason
+			if err := store.Update(ctx, payment); err != nil {
+				return gsresponse.Auto[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+			}
+			return gsresponse.Success(&orchestratorv1.ProcessTransferUpdateResponse{Payment: toProtoPayment(payment)})
+		case chainv1.TransferStatus_TRANSFER_CANCELLED:
+			payment.State = model.PaymentStateCancelled
+			payment.FailureCode = model.PaymentFailureCodePolicy
+			payment.FailureReason = reason
+			if err := store.Update(ctx, payment); err != nil {
+				return gsresponse.Auto[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+			}
+			return gsresponse.Success(&orchestratorv1.ProcessTransferUpdateResponse{Payment: toProtoPayment(payment)})
+		case chainv1.TransferStatus_TRANSFER_SUCCESS:
+			if h.resumePlan != nil {
+				if err := h.resumePlan(ctx, store, payment); err != nil {
+					return gsresponse.Auto[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+				}
+			}
+			return gsresponse.Success(&orchestratorv1.ProcessTransferUpdateResponse{Payment: toProtoPayment(payment)})
+		case chainv1.TransferStatus_TRANSFER_WAITING:
+			return gsresponse.Success(&orchestratorv1.ProcessTransferUpdateResponse{Payment: toProtoPayment(payment)})
+		default:
+			if err := store.Update(ctx, payment); err != nil {
+				return gsresponse.Auto[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+			}
+			return gsresponse.Success(&orchestratorv1.ProcessTransferUpdateResponse{Payment: toProtoPayment(payment)})
+		}
+	}
+
+	updateExecutionStepFromTransfer(payment.ExecutionPlan, req.GetEvent())
+	if payment.Intent.Destination.Type == model.EndpointTypeCard {
+		if payment.Execution == nil {
+			payment.Execution = &model.ExecutionRefs{}
+		}
+		if payment.Execution.ChainTransferRef == "" {
+			payment.Execution.ChainTransferRef = transferRef
+		}
+		reason := transferFailureReason(req.GetEvent())
+		switch transfer.GetStatus() {
+		case chainv1.TransferStatus_TRANSFER_FAILED:
+			payment.State = model.PaymentStateFailed
+			payment.FailureCode = model.PaymentFailureCodeChain
+			payment.FailureReason = reason
+		case chainv1.TransferStatus_TRANSFER_CANCELLED:
+			payment.State = model.PaymentStateCancelled
+			payment.FailureCode = model.PaymentFailureCodePolicy
+			payment.FailureReason = reason
+		case chainv1.TransferStatus_TRANSFER_SUCCESS:
+			if payment.State != model.PaymentStateFailed && payment.State != model.PaymentStateCancelled && payment.State != model.PaymentStateSettled {
+				if cardPayoutDependenciesConfirmed(payment.PaymentPlan, payment.ExecutionPlan) {
+					if payment.Execution.CardPayoutRef == "" {
+						payment.State = model.PaymentStateFundsReserved
+						if h.submitCardPayout == nil {
+							h.logger.Warn("card payout execution skipped", zap.String("payment_ref", payment.PaymentRef))
+						} else if err := h.submitCardPayout(ctx, transfer.GetOperationRef(), payment); err != nil {
+							payment.State = model.PaymentStateFailed
+							payment.FailureCode = model.PaymentFailureCodePolicy
+							payment.FailureReason = strings.TrimSpace(err.Error())
+							h.logger.Warn("card payout execution failed", zap.Error(err), zap.String("payment_ref", payment.PaymentRef))
+						}
+					}
+				}
+			}
+		case chainv1.TransferStatus_TRANSFER_WAITING:
+		default:
+			// keep current state
+		}
+		if err := store.Update(ctx, payment); err != nil {
+			return gsresponse.Auto[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+		h.logger.Info("transfer update applied", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", transferRef), zap.Any("state", payment.State))
+		return gsresponse.Success(&orchestratorv1.ProcessTransferUpdateResponse{Payment: toProtoPayment(payment)})
+	}
+
+	applyTransferStatus(req.GetEvent(), payment)
+	if err := store.Update(ctx, payment); err != nil {
+		return gsresponse.Auto[orchestratorv1.ProcessTransferUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	h.logger.Info("transfer update applied", zap.String("payment_ref", payment.PaymentRef), zap.String("transfer_ref", transferRef), zap.Any("state", payment.State))
+	return gsresponse.Success(&orchestratorv1.ProcessTransferUpdateResponse{Payment: toProtoPayment(payment)})
+}
+
+func (h *paymentEventHandler) processDepositObserved(ctx context.Context, req *orchestratorv1.ProcessDepositObservedRequest) gsresponse.Responder[orchestratorv1.ProcessDepositObservedResponse] {
+	if err := h.ensureRepo(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.ProcessDepositObservedResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil || req.GetEvent() == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.ProcessDepositObservedResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("deposit event is required"))
+	}
+	event := req.GetEvent()
+	walletRef := strings.TrimSpace(event.GetWalletRef())
+	if walletRef == "" {
+		return gsresponse.InvalidArgument[orchestratorv1.ProcessDepositObservedResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("wallet_ref is required"))
+	}
+	store := h.repo.Payments()
+	if store == nil {
+		return gsresponse.Unavailable[orchestratorv1.ProcessDepositObservedResponse](h.logger, mservice.PaymentOrchestrator, errStorageUnavailable)
+	}
+	filter := &model.PaymentFilter{
+		States:         []model.PaymentState{model.PaymentStateSubmitted, model.PaymentStateFundsReserved},
+		DestinationRef: walletRef,
+	}
+	result, err := store.List(ctx, filter)
+	if err != nil {
+		return gsresponse.Auto[orchestratorv1.ProcessDepositObservedResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	for _, payment := range result.Items {
+		if payment.Intent.Destination.Type != model.EndpointTypeManagedWallet {
+			continue
+		}
+		if !moneyEquals(payment.Intent.Amount, event.GetAmount()) {
+			continue
+		}
+		payment.State = model.PaymentStateSettled
+		payment.FailureCode = model.PaymentFailureCodeUnspecified
+		payment.FailureReason = ""
+		if payment.Execution == nil {
+			payment.Execution = &model.ExecutionRefs{}
+		}
+		if payment.Execution.ChainTransferRef == "" {
+			payment.Execution.ChainTransferRef = strings.TrimSpace(event.GetTransactionHash())
+		}
+		if err := store.Update(ctx, payment); err != nil {
+			return gsresponse.Auto[orchestratorv1.ProcessDepositObservedResponse](h.logger, mservice.PaymentOrchestrator, err)
+		}
+		h.logger.Info("deposit observed matched payment", zap.String("payment_ref", payment.PaymentRef), zap.String("wallet_ref", walletRef))
+		return gsresponse.Success(&orchestratorv1.ProcessDepositObservedResponse{Payment: toProtoPayment(payment)})
+	}
+	return gsresponse.Success(&orchestratorv1.ProcessDepositObservedResponse{})
+}
+
+func (h *paymentEventHandler) processCardPayoutUpdate(ctx context.Context, req *orchestratorv1.ProcessCardPayoutUpdateRequest) gsresponse.Responder[orchestratorv1.ProcessCardPayoutUpdateResponse] {
+	if err := h.ensureRepo(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.ProcessCardPayoutUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil || req.GetEvent() == nil || req.GetEvent().GetPayout() == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.ProcessCardPayoutUpdateResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("event is required"))
+	}
+	payout := req.GetEvent().GetPayout()
+	paymentRef := strings.TrimSpace(payout.GetPayoutId())
+	if paymentRef == "" {
+		return gsresponse.InvalidArgument[orchestratorv1.ProcessCardPayoutUpdateResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("payout_id is required"))
+	}
+
+	store := h.repo.Payments()
+	if store == nil {
+		return gsresponse.Unavailable[orchestratorv1.ProcessCardPayoutUpdateResponse](h.logger, mservice.PaymentOrchestrator, errStorageUnavailable)
+	}
+	payment, err := store.GetByPaymentRef(ctx, paymentRef)
+	if err != nil {
+		return paymentNotFoundResponder[orchestratorv1.ProcessCardPayoutUpdateResponse](mservice.PaymentOrchestrator, h.logger, err)
+	}
+
+	applyCardPayoutUpdate(payment, payout)
+
+	switch payout.GetStatus() {
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_SUCCESS:
+		h.logger.Info("card payout success received",
+			zap.String("payment_ref", payment.PaymentRef),
+			zap.String("payout_ref", payout.GetPayoutId()),
+			zap.String("payment_state_before", string(payment.State)),
+			zap.Bool("has_plan", payment.PaymentPlan != nil && len(payment.PaymentPlan.Steps) > 0),
+			zap.Bool("resume_plan_present", h.resumePlan != nil),
+		)
+
+		if h.resumePlan != nil && payment.PaymentPlan != nil && len(payment.PaymentPlan.Steps) > 0 {
+			if err := h.resumePlan(ctx, store, payment); err != nil {
+				h.logger.Error("resumePlan failed after payout success",
+					zap.String("payment_ref", payment.PaymentRef),
+					zap.String("payout_ref", payout.GetPayoutId()),
+					zap.Error(err),
+				)
+				return gsresponse.Auto[orchestratorv1.ProcessCardPayoutUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+			}
+			h.logger.Info("resumePlan executed after payout success",
+				zap.String("payment_ref", payment.PaymentRef),
+				zap.String("payout_ref", payout.GetPayoutId()),
+			)
+		} else {
+			h.logger.Warn("payout success but plan cannot be resumed",
+				zap.String("payment_ref", payment.PaymentRef),
+				zap.String("payout_ref", payout.GetPayoutId()),
+				zap.Bool("resume_plan_present", h.resumePlan != nil),
+				zap.Bool("has_plan", payment.PaymentPlan != nil && len(payment.PaymentPlan.Steps) > 0),
+			)
+		}
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_FAILED:
+		h.logger.Warn("card payout failed",
+			zap.String("payment_ref", payment.PaymentRef),
+			zap.String("payout_ref", payout.GetPayoutId()),
+			zap.String("provider_message", payout.GetProviderMessage()),
+		)
+
+		payment.State = model.PaymentStateFailed
+		payment.FailureCode = model.PaymentFailureCodePolicy
+		payment.FailureReason = strings.TrimSpace(payout.GetProviderMessage())
+
+		if h.releaseHold != nil && payment.PaymentPlan != nil && len(payment.PaymentPlan.Steps) > 0 {
+			h.logger.Info("releasing hold after payout failure",
+				zap.String("payment_ref", payment.PaymentRef),
+				zap.String("payout_ref", payout.GetPayoutId()),
+			)
+
+			if err := h.releaseHold(ctx, store, payment); err != nil {
+				h.logger.Error("releaseHold failed after payout failure",
+					zap.String("payment_ref", payment.PaymentRef),
+					zap.String("payout_ref", payout.GetPayoutId()),
+					zap.Error(err),
+				)
+				return gsresponse.Auto[orchestratorv1.ProcessCardPayoutUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+			}
+		} else {
+			h.logger.Warn("payout failed but hold cannot be released",
+				zap.String("payment_ref", payment.PaymentRef),
+				zap.String("payout_ref", payout.GetPayoutId()),
+				zap.Bool("release_hold_present", h.releaseHold != nil),
+				zap.Bool("has_plan", payment.PaymentPlan != nil && len(payment.PaymentPlan.Steps) > 0),
+			)
+		}
+	}
+
+	if err := store.Update(ctx, payment); err != nil {
+		return gsresponse.Auto[orchestratorv1.ProcessCardPayoutUpdateResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+
+	h.logger.Info("card payout update applied", zap.String("payment_ref", payment.PaymentRef), zap.String("payout_id", paymentRef), zap.Any("state", payment.State))
+	return gsresponse.Success(&orchestratorv1.ProcessCardPayoutUpdateResponse{
+		Payment: toProtoPayment(payment),
+	})
+}
+
+func transferFailureReason(event *chainv1.TransferStatusChangedEvent) string {
+	if event == nil || event.GetTransfer() == nil {
+		return ""
+	}
+	reason := strings.TrimSpace(event.GetReason())
+	if reason != "" {
+		return reason
+	}
+	return strings.TrimSpace(event.GetTransfer().GetFailureReason())
+}

api/payments/quotation/internal/service/orchestrator/handlers_queries.go

@@ -0,0 +1,80 @@
+package orchestrator
+
+import (
+	"context"
+
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/pkg/api/routers/gsresponse"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/mservice"
+	paginationv1 "github.com/tech/sendico/pkg/proto/common/pagination/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"go.uber.org/zap"
+)
+
+type paymentQueryHandler struct {
+	repo       storage.Repository
+	ensureRepo func(ctx context.Context) error
+	logger     mlogger.Logger
+}
+
+func newPaymentQueryHandler(repo storage.Repository, ensure func(ctx context.Context) error, logger mlogger.Logger) *paymentQueryHandler {
+	return &paymentQueryHandler{
+		repo:       repo,
+		ensureRepo: ensure,
+		logger:     logger,
+	}
+}
+
+func (h *paymentQueryHandler) getPayment(ctx context.Context, req *orchestratorv1.GetPaymentRequest) gsresponse.Responder[orchestratorv1.GetPaymentResponse] {
+	if err := h.ensureRepo(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.GetPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.GetPaymentResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+	paymentRef, err := requirePaymentRef(req.GetPaymentRef())
+	if err != nil {
+		return gsresponse.InvalidArgument[orchestratorv1.GetPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	store, err := ensurePaymentsStore(h.repo)
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.GetPaymentResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	entity, err := store.GetByPaymentRef(ctx, paymentRef)
+	if err != nil {
+		return paymentNotFoundResponder[orchestratorv1.GetPaymentResponse](mservice.PaymentOrchestrator, h.logger, err)
+	}
+	h.logger.Debug("payment fetched", zap.String("payment_ref", paymentRef))
+	return gsresponse.Success(&orchestratorv1.GetPaymentResponse{Payment: toProtoPayment(entity)})
+}
+
+func (h *paymentQueryHandler) listPayments(ctx context.Context, req *orchestratorv1.ListPaymentsRequest) gsresponse.Responder[orchestratorv1.ListPaymentsResponse] {
+	if err := h.ensureRepo(ctx); err != nil {
+		return gsresponse.Unavailable[orchestratorv1.ListPaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	if req == nil {
+		return gsresponse.InvalidArgument[orchestratorv1.ListPaymentsResponse](h.logger, mservice.PaymentOrchestrator, merrors.InvalidArgument("nil request"))
+	}
+	store, err := ensurePaymentsStore(h.repo)
+	if err != nil {
+		return gsresponse.Unavailable[orchestratorv1.ListPaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	filter := filterFromProto(req)
+	result, err := store.List(ctx, filter)
+	if err != nil {
+		return gsresponse.Auto[orchestratorv1.ListPaymentsResponse](h.logger, mservice.PaymentOrchestrator, err)
+	}
+	resp := &orchestratorv1.ListPaymentsResponse{
+		Page: &paginationv1.CursorPageResponse{
+			NextCursor: result.NextCursor,
+		},
+	}
+	resp.Payments = make([]*orchestratorv1.Payment, 0, len(result.Items))
+	for _, item := range result.Items {
+		resp.Payments = append(resp.Payments, toProtoPayment(item))
+	}
+	h.logger.Debug("payments listed", zap.Int("count", len(resp.Payments)), zap.String("next_cursor", resp.GetPage().GetNextCursor()))
+	return gsresponse.Success(resp)
+}

api/payments/quotation/internal/service/orchestrator/helpers.go

@@ -0,0 +1,463 @@
+package orchestrator
+
+import (
+	"strings"
+	"time"
+
+	"github.com/shopspring/decimal"
+	oracleclient "github.com/tech/sendico/fx/oracle/client"
+	"github.com/tech/sendico/pkg/merrors"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+	ledgerv1 "github.com/tech/sendico/pkg/proto/ledger/v1"
+	oraclev1 "github.com/tech/sendico/pkg/proto/oracle/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"google.golang.org/protobuf/proto"
+
+	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"
+	accountingv1 "github.com/tech/sendico/pkg/proto/common/accounting/v1"
+	fxv1 "github.com/tech/sendico/pkg/proto/common/fx/v1"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+)
+
+type moneyGetter interface {
+	GetAmount() string
+	GetCurrency() string
+}
+
+const (
+	feeLineMetaTarget     = "fee_target"
+	feeLineTargetWallet   = "wallet"
+	feeLineMetaWalletRef  = "fee_wallet_ref"
+	feeLineMetaWalletType = "fee_wallet_type"
+)
+
+func cloneProtoMoney(input *moneyv1.Money) *moneyv1.Money {
+	if input == nil {
+		return nil
+	}
+	return &moneyv1.Money{
+		Currency: input.GetCurrency(),
+		Amount:   input.GetAmount(),
+	}
+}
+
+func cloneMetadata(input map[string]string) map[string]string {
+	if len(input) == 0 {
+		return nil
+	}
+	clone := make(map[string]string, len(input))
+	for k, v := range input {
+		clone[k] = v
+	}
+	return clone
+}
+
+func cloneStringList(values []string) []string {
+	if len(values) == 0 {
+		return nil
+	}
+	result := make([]string, 0, len(values))
+	for _, value := range values {
+		clean := strings.TrimSpace(value)
+		if clean == "" {
+			continue
+		}
+		result = append(result, clean)
+	}
+	if len(result) == 0 {
+		return nil
+	}
+	return result
+}
+
+func cloneFeeLines(lines []*feesv1.DerivedPostingLine) []*feesv1.DerivedPostingLine {
+	if len(lines) == 0 {
+		return nil
+	}
+	out := make([]*feesv1.DerivedPostingLine, 0, len(lines))
+	for _, line := range lines {
+		if line == nil {
+			continue
+		}
+		if cloned, ok := proto.Clone(line).(*feesv1.DerivedPostingLine); ok {
+			out = append(out, cloned)
+		}
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func cloneFeeRules(rules []*feesv1.AppliedRule) []*feesv1.AppliedRule {
+	if len(rules) == 0 {
+		return nil
+	}
+	out := make([]*feesv1.AppliedRule, 0, len(rules))
+	for _, rule := range rules {
+		if rule == nil {
+			continue
+		}
+		if cloned, ok := proto.Clone(rule).(*feesv1.AppliedRule); ok {
+			out = append(out, cloned)
+		}
+	}
+	if len(out) == 0 {
+		return nil
+	}
+	return out
+}
+
+func extractFeeTotal(lines []*feesv1.DerivedPostingLine, currency string) *moneyv1.Money {
+	if len(lines) == 0 || currency == "" {
+		return nil
+	}
+	total := decimal.Zero
+	for _, line := range lines {
+		if line == nil || line.GetMoney() == nil {
+			continue
+		}
+		if !strings.EqualFold(line.GetMoney().GetCurrency(), currency) {
+			continue
+		}
+		amount, err := decimal.NewFromString(line.GetMoney().GetAmount())
+		if err != nil {
+			continue
+		}
+		switch line.GetSide() {
+		case accountingv1.EntrySide_ENTRY_SIDE_CREDIT:
+			total = total.Sub(amount.Abs())
+		default:
+			total = total.Add(amount.Abs())
+		}
+	}
+	if total.IsZero() {
+		return nil
+	}
+	return &moneyv1.Money{
+		Currency: currency,
+		Amount:   total.String(),
+	}
+}
+
+func resolveTradeAmounts(intentAmount *moneyv1.Money, fxQuote *oraclev1.Quote, side fxv1.Side) (*moneyv1.Money, *moneyv1.Money) {
+	if fxQuote == nil {
+		return cloneProtoMoney(intentAmount), cloneProtoMoney(intentAmount)
+	}
+	qSide := fxQuote.GetSide()
+	if qSide == fxv1.Side_SIDE_UNSPECIFIED {
+		qSide = side
+	}
+
+	switch qSide {
+	case fxv1.Side_BUY_BASE_SELL_QUOTE:
+		pay := cloneProtoMoney(fxQuote.GetQuoteAmount())
+		settle := cloneProtoMoney(fxQuote.GetBaseAmount())
+		if pay == nil {
+			pay = cloneProtoMoney(intentAmount)
+		}
+		if settle == nil {
+			settle = cloneProtoMoney(intentAmount)
+		}
+		return pay, settle
+	case fxv1.Side_SELL_BASE_BUY_QUOTE:
+		pay := cloneProtoMoney(fxQuote.GetBaseAmount())
+		settle := cloneProtoMoney(fxQuote.GetQuoteAmount())
+		if pay == nil {
+			pay = cloneProtoMoney(intentAmount)
+		}
+		if settle == nil {
+			settle = cloneProtoMoney(intentAmount)
+		}
+		return pay, settle
+	default:
+		return cloneProtoMoney(intentAmount), cloneProtoMoney(intentAmount)
+	}
+}
+
+func computeAggregates(pay, settlement, fee *moneyv1.Money, network *chainv1.EstimateTransferFeeResponse, fxQuote *oraclev1.Quote, mode orchestratorv1.SettlementMode) (*moneyv1.Money, *moneyv1.Money) {
+	if pay == nil {
+		return nil, nil
+	}
+	debitDecimal, err := decimalFromMoney(pay)
+	if err != nil {
+		return cloneProtoMoney(pay), cloneProtoMoney(settlement)
+	}
+
+	settlementCurrency := pay.GetCurrency()
+	if settlement != nil && strings.TrimSpace(settlement.GetCurrency()) != "" {
+		settlementCurrency = settlement.GetCurrency()
+	}
+
+	settlementDecimal := debitDecimal
+	if settlement != nil {
+		if val, err := decimalFromMoney(settlement); err == nil {
+			settlementDecimal = val
+		}
+	}
+
+	applyChargeToDebit := func(m *moneyv1.Money) {
+		converted, err := ensureCurrency(m, pay.GetCurrency(), fxQuote)
+		if err != nil || converted == nil {
+			return
+		}
+		if val, err := decimalFromMoney(converted); err == nil {
+			debitDecimal = debitDecimal.Add(val)
+		}
+	}
+
+	applyChargeToSettlement := func(m *moneyv1.Money) {
+		converted, err := ensureCurrency(m, settlementCurrency, fxQuote)
+		if err != nil || converted == nil {
+			return
+		}
+		if val, err := decimalFromMoney(converted); err == nil {
+			settlementDecimal = settlementDecimal.Sub(val)
+		}
+	}
+
+	switch mode {
+	case orchestratorv1.SettlementMode_SETTLEMENT_FIX_RECEIVED:
+		// Sender pays the fee: keep settlement fixed, increase debit.
+		applyChargeToDebit(fee)
+	default:
+		// Recipient pays the fee (default): reduce settlement, keep debit fixed.
+		applyChargeToSettlement(fee)
+	}
+
+	if network != nil && network.GetNetworkFee() != nil {
+		switch mode {
+		case orchestratorv1.SettlementMode_SETTLEMENT_FIX_RECEIVED:
+			applyChargeToDebit(network.GetNetworkFee())
+		default:
+			applyChargeToSettlement(network.GetNetworkFee())
+		}
+	}
+
+	return makeMoney(pay.GetCurrency(), debitDecimal), makeMoney(settlementCurrency, settlementDecimal)
+}
+
+func decimalFromMoney(m moneyGetter) (decimal.Decimal, error) {
+	if m == nil {
+		return decimal.Zero, nil
+	}
+	return decimal.NewFromString(m.GetAmount())
+}
+
+func makeMoney(currency string, value decimal.Decimal) *moneyv1.Money {
+	return &moneyv1.Money{
+		Currency: currency,
+		Amount:   value.String(),
+	}
+}
+
+func ensureCurrency(m *moneyv1.Money, targetCurrency string, quote *oraclev1.Quote) (*moneyv1.Money, error) {
+	if m == nil || strings.TrimSpace(targetCurrency) == "" {
+		return nil, nil
+	}
+	if strings.EqualFold(m.GetCurrency(), targetCurrency) {
+		return cloneProtoMoney(m), nil
+	}
+	return convertWithQuote(m, quote, targetCurrency)
+}
+
+func convertWithQuote(m *moneyv1.Money, quote *oraclev1.Quote, targetCurrency string) (*moneyv1.Money, error) {
+	if m == nil || quote == nil || quote.GetPair() == nil || quote.GetPrice() == nil {
+		return nil, nil
+	}
+
+	base := strings.TrimSpace(quote.GetPair().GetBase())
+	qt := strings.TrimSpace(quote.GetPair().GetQuote())
+	if base == "" || qt == "" || strings.TrimSpace(targetCurrency) == "" {
+		return nil, nil
+	}
+
+	price, err := decimal.NewFromString(quote.GetPrice().GetValue())
+	if err != nil || price.IsZero() {
+		return nil, err
+	}
+	value, err := decimalFromMoney(m)
+	if err != nil {
+		return nil, err
+	}
+
+	switch {
+	case strings.EqualFold(m.GetCurrency(), base) && strings.EqualFold(targetCurrency, qt):
+		return makeMoney(targetCurrency, value.Mul(price)), nil
+	case strings.EqualFold(m.GetCurrency(), qt) && strings.EqualFold(targetCurrency, base):
+		return makeMoney(targetCurrency, value.Div(price)), nil
+	default:
+		return nil, nil
+	}
+}
+
+func quoteToProto(src *oracleclient.Quote) *oraclev1.Quote {
+	if src == nil {
+		return nil
+	}
+	return &oraclev1.Quote{
+		QuoteRef:        src.QuoteRef,
+		Pair:            src.Pair,
+		Side:            src.Side,
+		Price:           &moneyv1.Decimal{Value: src.Price},
+		BaseAmount:      cloneProtoMoney(src.BaseAmount),
+		QuoteAmount:     cloneProtoMoney(src.QuoteAmount),
+		ExpiresAtUnixMs: src.ExpiresAt.UnixMilli(),
+		Provider:        src.Provider,
+		RateRef:         src.RateRef,
+		Firm:            src.Firm,
+	}
+}
+
+func setFeeLineTarget(lines []*feesv1.DerivedPostingLine, target string) {
+	target = strings.TrimSpace(target)
+	if target == "" || len(lines) == 0 {
+		return
+	}
+	for _, line := range lines {
+		if line == nil {
+			continue
+		}
+		if line.Meta == nil {
+			line.Meta = map[string]string{}
+		}
+		line.Meta[feeLineMetaTarget] = target
+		if strings.EqualFold(target, feeLineTargetWallet) {
+			line.LedgerAccountRef = ""
+		}
+	}
+}
+
+func feeLineTarget(line *feesv1.DerivedPostingLine) string {
+	if line == nil {
+		return ""
+	}
+	return strings.TrimSpace(line.GetMeta()[feeLineMetaTarget])
+}
+
+func isWalletTargetFeeLine(line *feesv1.DerivedPostingLine) bool {
+	return strings.EqualFold(feeLineTarget(line), feeLineTargetWallet)
+}
+
+func setFeeLineWalletRef(lines []*feesv1.DerivedPostingLine, walletRef, walletType string) {
+	walletRef = strings.TrimSpace(walletRef)
+	walletType = strings.TrimSpace(walletType)
+	if walletRef == "" || len(lines) == 0 {
+		return
+	}
+	for _, line := range lines {
+		if line == nil {
+			continue
+		}
+		if line.Meta == nil {
+			line.Meta = map[string]string{}
+		}
+		line.Meta[feeLineMetaWalletRef] = walletRef
+		if walletType != "" {
+			line.Meta[feeLineMetaWalletType] = walletType
+		}
+	}
+}
+
+func ledgerChargesFromFeeLines(lines []*feesv1.DerivedPostingLine) []*ledgerv1.PostingLine {
+	if len(lines) == 0 {
+		return nil
+	}
+	charges := make([]*ledgerv1.PostingLine, 0, len(lines))
+	for _, line := range lines {
+		if line == nil || isWalletTargetFeeLine(line) || strings.TrimSpace(line.GetLedgerAccountRef()) == "" {
+			continue
+		}
+		money := cloneProtoMoney(line.GetMoney())
+		if money == nil {
+			continue
+		}
+		charges = append(charges, &ledgerv1.PostingLine{
+			LedgerAccountRef: strings.TrimSpace(line.GetLedgerAccountRef()),
+			Money:            money,
+			LineType:         ledgerLineTypeFromAccounting(line.GetLineType()),
+		})
+	}
+	if len(charges) == 0 {
+		return nil
+	}
+	return charges
+}
+
+func ledgerLineTypeFromAccounting(lineType accountingv1.PostingLineType) ledgerv1.LineType {
+	switch lineType {
+	case accountingv1.PostingLineType_POSTING_LINE_SPREAD:
+		return ledgerv1.LineType_LINE_SPREAD
+	case accountingv1.PostingLineType_POSTING_LINE_REVERSAL:
+		return ledgerv1.LineType_LINE_REVERSAL
+	case accountingv1.PostingLineType_POSTING_LINE_FEE,
+		accountingv1.PostingLineType_POSTING_LINE_TAX:
+		return ledgerv1.LineType_LINE_FEE
+	default:
+		return ledgerv1.LineType_LINE_MAIN
+	}
+}
+
+func quoteExpiry(now time.Time, feeQuote *feesv1.PrecomputeFeesResponse, fxQuote *oraclev1.Quote) time.Time {
+	expiry := time.Time{}
+	if feeQuote != nil && feeQuote.GetExpiresAt() != nil {
+		expiry = feeQuote.GetExpiresAt().AsTime()
+	}
+	if expiry.IsZero() {
+		expiry = now.Add(time.Duration(defaultFeeQuoteTTLMillis) * time.Millisecond)
+	}
+	if fxQuote != nil && fxQuote.GetExpiresAtUnixMs() > 0 {
+		fxExpiry := time.UnixMilli(fxQuote.GetExpiresAtUnixMs()).UTC()
+		if fxExpiry.Before(expiry) {
+			expiry = fxExpiry
+		}
+	}
+	return expiry
+}
+
+func assignLedgerAccounts(lines []*feesv1.DerivedPostingLine, account string) []*feesv1.DerivedPostingLine {
+	if account == "" || len(lines) == 0 {
+		return lines
+	}
+	for _, line := range lines {
+		if line == nil || isWalletTargetFeeLine(line) {
+			continue
+		}
+		if strings.TrimSpace(line.GetLedgerAccountRef()) != "" {
+			continue
+		}
+		line.LedgerAccountRef = account
+	}
+	return lines
+}
+
+func moneyEquals(a, b moneyGetter) bool {
+	if a == nil || b == nil {
+		return false
+	}
+	if !strings.EqualFold(a.GetCurrency(), b.GetCurrency()) {
+		return false
+	}
+	return strings.TrimSpace(a.GetAmount()) == strings.TrimSpace(b.GetAmount())
+}
+
+func conversionAmountFromMetadata(meta map[string]string, fx *orchestratorv1.FXIntent) (*moneyv1.Money, error) {
+	if meta == nil {
+		meta = map[string]string{}
+	}
+	amount := strings.TrimSpace(meta["amount"])
+	if amount == "" {
+		return nil, merrors.InvalidArgument("conversion amount metadata is required")
+	}
+	currency := strings.TrimSpace(meta["currency"])
+	if currency == "" && fx != nil && fx.GetPair() != nil {
+		currency = strings.TrimSpace(fx.GetPair().GetBase())
+	}
+	if currency == "" {
+		return nil, merrors.InvalidArgument("conversion currency metadata is required")
+	}
+	return &moneyv1.Money{
+		Currency: currency,
+		Amount:   amount,
+	}, nil
+}

api/payments/quotation/internal/service/orchestrator/internal_helpers.go

@@ -0,0 +1,132 @@
+package orchestrator
+
+import (
+	"context"
+	"strings"
+	"time"
+
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/api/routers/gsresponse"
+	"github.com/tech/sendico/pkg/mservice"
+	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"
+	fxv1 "github.com/tech/sendico/pkg/proto/common/fx/v1"
+	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+)
+
+func (s *Service) ensureRepository(ctx context.Context) error {
+	if s.storage == nil {
+		return errStorageUnavailable
+	}
+	return s.storage.Ping(ctx)
+}
+
+func (s *Service) withTimeout(ctx context.Context, d time.Duration) (context.Context, context.CancelFunc) {
+	if d <= 0 {
+		return context.WithCancel(ctx)
+	}
+	return context.WithTimeout(ctx, d)
+}
+
+func executeUnary[TReq any, TResp any](ctx context.Context, svc *Service, method string, handler func(context.Context, *TReq) gsresponse.Responder[TResp], req *TReq) (*TResp, error) {
+	start := svc.clock.Now()
+	resp, err := gsresponse.Unary(svc.logger, mservice.PaymentOrchestrator, handler)(ctx, req)
+	observeRPC(method, err, svc.clock.Now().Sub(start))
+	return resp, err
+}
+
+func triggerFromKind(kind orchestratorv1.PaymentKind, requiresFX bool) feesv1.Trigger {
+	switch kind {
+	case orchestratorv1.PaymentKind_PAYMENT_KIND_PAYOUT:
+		return feesv1.Trigger_TRIGGER_PAYOUT
+	case orchestratorv1.PaymentKind_PAYMENT_KIND_INTERNAL_TRANSFER:
+		return feesv1.Trigger_TRIGGER_CAPTURE
+	case orchestratorv1.PaymentKind_PAYMENT_KIND_FX_CONVERSION:
+		return feesv1.Trigger_TRIGGER_FX_CONVERSION
+	default:
+		if requiresFX {
+			return feesv1.Trigger_TRIGGER_FX_CONVERSION
+		}
+		return feesv1.Trigger_TRIGGER_UNSPECIFIED
+	}
+}
+
+func shouldEstimateNetworkFee(intent *orchestratorv1.PaymentIntent) bool {
+	if intent == nil {
+		return false
+	}
+	dest := intent.GetDestination()
+	if dest == nil {
+		return false
+	}
+	if dest.GetCard() != nil {
+		return false
+	}
+	if intent.GetKind() == orchestratorv1.PaymentKind_PAYMENT_KIND_PAYOUT {
+		return true
+	}
+	if dest.GetManagedWallet() != nil || dest.GetExternalChain() != nil {
+		return true
+	}
+	return false
+}
+
+func shouldRequestFX(intent *orchestratorv1.PaymentIntent) bool {
+	if intent == nil {
+		return false
+	}
+	if fxIntentForQuote(intent) != nil {
+		return true
+	}
+	return intent.GetRequiresFx()
+}
+
+func fxIntentForQuote(intent *orchestratorv1.PaymentIntent) *orchestratorv1.FXIntent {
+	if intent == nil {
+		return nil
+	}
+	if fx := intent.GetFx(); fx != nil && fx.GetPair() != nil {
+		return fx
+	}
+	amount := intent.GetAmount()
+	if amount == nil {
+		return nil
+	}
+	settlementCurrency := strings.TrimSpace(intent.GetSettlementCurrency())
+	if settlementCurrency == "" {
+		return nil
+	}
+	if strings.EqualFold(amount.GetCurrency(), settlementCurrency) {
+		return nil
+	}
+	return &orchestratorv1.FXIntent{
+		Pair: &fxv1.CurrencyPair{
+			Base:  strings.TrimSpace(amount.GetCurrency()),
+			Quote: settlementCurrency,
+		},
+		Side: fxv1.Side_SELL_BASE_BUY_QUOTE,
+	}
+}
+
+func mapMntxStatusToState(status mntxv1.PayoutStatus) model.PaymentState {
+	switch status {
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_CREATED:
+		return model.PaymentStateFundsReserved
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_WAITING:
+		return model.PaymentStateSubmitted
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_SUCCESS:
+		return model.PaymentStateSettled
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_FAILED:
+		return model.PaymentStateFailed
+
+	case mntxv1.PayoutStatus_PAYOUT_STATUS_CANCELLED:
+		return model.PaymentStateCancelled
+
+	default:
+		return model.PaymentStateUnspecified
+	}
+}

api/payments/quotation/internal/service/orchestrator/metrics.go

@@ -0,0 +1,65 @@
+package orchestrator
+
+import (
+	"errors"
+	"sync"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+	"github.com/tech/sendico/pkg/merrors"
+)
+
+var (
+	metricsOnce sync.Once
+
+	rpcLatency *prometheus.HistogramVec
+	rpcStatus  *prometheus.CounterVec
+)
+
+func initMetrics() {
+	metricsOnce.Do(func() {
+		rpcLatency = promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Namespace: "sendico",
+			Subsystem: "payment_orchestrator",
+			Name:      "rpc_latency_seconds",
+			Help:      "Latency distribution for payment orchestrator RPC handlers.",
+			Buckets:   prometheus.DefBuckets,
+		}, []string{"method"})
+
+		rpcStatus = promauto.NewCounterVec(prometheus.CounterOpts{
+			Namespace: "sendico",
+			Subsystem: "payment_orchestrator",
+			Name:      "rpc_requests_total",
+			Help:      "Total number of RPC invocations grouped by method and status.",
+		}, []string{"method", "status"})
+	})
+}
+
+func observeRPC(method string, err error, duration time.Duration) {
+	if rpcLatency != nil {
+		rpcLatency.WithLabelValues(method).Observe(duration.Seconds())
+	}
+	if rpcStatus != nil {
+		rpcStatus.WithLabelValues(method, statusLabel(err)).Inc()
+	}
+}
+
+func statusLabel(err error) string {
+	switch {
+	case err == nil:
+		return "ok"
+	case errors.Is(err, merrors.ErrInvalidArg):
+		return "invalid_argument"
+	case errors.Is(err, merrors.ErrNoData):
+		return "not_found"
+	case errors.Is(err, merrors.ErrDataConflict):
+		return "conflict"
+	case errors.Is(err, merrors.ErrAccessDenied):
+		return "denied"
+	case errors.Is(err, merrors.ErrInternal):
+		return "internal"
+	default:
+		return "error"
+	}
+}

api/payments/quotation/internal/service/orchestrator/model_money.go

@@ -0,0 +1,13 @@
+package orchestrator
+
+import paymenttypes "github.com/tech/sendico/pkg/payments/types"
+
+func cloneMoney(input *paymenttypes.Money) *paymenttypes.Money {
+	if input == nil {
+		return nil
+	}
+	return &paymenttypes.Money{
+		Currency: input.GetCurrency(),
+		Amount:   input.GetAmount(),
+	}
+}

api/payments/quotation/internal/service/orchestrator/options.go

@@ -0,0 +1,456 @@
+package orchestrator
+
+import (
+	"context"
+	"sort"
+	"strings"
+	"time"
+
+	"github.com/shopspring/decimal"
+	oracleclient "github.com/tech/sendico/fx/oracle/client"
+	chainclient "github.com/tech/sendico/gateway/chain/client"
+	mntxclient "github.com/tech/sendico/gateway/mntx/client"
+	ledgerclient "github.com/tech/sendico/ledger/client"
+	"github.com/tech/sendico/payments/storage/model"
+	clockpkg "github.com/tech/sendico/pkg/clock"
+	"github.com/tech/sendico/pkg/merrors"
+	mb "github.com/tech/sendico/pkg/messaging/broker"
+	"github.com/tech/sendico/pkg/mlogger"
+	"github.com/tech/sendico/pkg/payments/rail"
+	feesv1 "github.com/tech/sendico/pkg/proto/billing/fees/v1"
+	"go.uber.org/zap"
+)
+
+// Option configures service dependencies.
+type Option func(*Service)
+
+// GatewayInvokeResolver resolves gateway invoke URIs into chain gateway clients.
+type GatewayInvokeResolver interface {
+	Resolve(ctx context.Context, invokeURI string) (chainclient.Client, error)
+}
+
+// ChainGatewayResolver resolves chain gateway clients by network.
+type ChainGatewayResolver interface {
+	Resolve(ctx context.Context, network string) (chainclient.Client, error)
+}
+
+type feesDependency struct {
+	client  feesv1.FeeEngineClient
+	timeout time.Duration
+}
+
+func (f feesDependency) available() bool {
+	if f.client == nil {
+		return false
+	}
+	if checker, ok := f.client.(interface{ Available() bool }); ok {
+		return checker.Available()
+	}
+	return true
+}
+
+type ledgerDependency struct {
+	client   ledgerclient.Client
+	internal rail.InternalLedger
+}
+
+type gatewayDependency struct {
+	resolver ChainGatewayResolver
+}
+
+type railGatewayDependency struct {
+	byID             map[string]rail.RailGateway
+	byRail           map[model.Rail][]rail.RailGateway
+	registry         GatewayRegistry
+	chainResolver    GatewayInvokeResolver
+	providerResolver GatewayInvokeResolver
+	logger           mlogger.Logger
+}
+
+func (g railGatewayDependency) available() bool {
+	return len(g.byID) > 0 || len(g.byRail) > 0 || (g.registry != nil && (g.chainResolver != nil || g.providerResolver != nil))
+}
+
+func (g railGatewayDependency) resolve(ctx context.Context, step *model.PaymentStep) (rail.RailGateway, error) {
+	if step == nil {
+		return nil, merrors.InvalidArgument("rail gateway: step is required")
+	}
+	if id := strings.TrimSpace(step.GatewayID); id != "" {
+		if gw, ok := g.byID[id]; ok {
+			return gw, nil
+		}
+		return g.resolveDynamic(ctx, step)
+	}
+	if len(g.byRail) == 0 {
+		return g.resolveDynamic(ctx, step)
+	}
+	list := g.byRail[step.Rail]
+	if len(list) == 0 {
+		return g.resolveDynamic(ctx, step)
+	}
+	return list[0], nil
+}
+
+func (g railGatewayDependency) resolveDynamic(ctx context.Context, step *model.PaymentStep) (rail.RailGateway, error) {
+	if g.registry == nil {
+		return nil, merrors.InvalidArgument("rail gateway: registry is required")
+	}
+	if g.chainResolver == nil && g.providerResolver == nil {
+		return nil, merrors.InvalidArgument("rail gateway: gateway resolver is required")
+	}
+	items, err := g.registry.List(ctx)
+	if err != nil {
+		return nil, err
+	}
+	if len(items) == 0 {
+		return nil, merrors.InvalidArgument("rail gateway: no gateway instances available")
+	}
+
+	currency := ""
+	amount := decimal.Zero
+	if step.Amount != nil && strings.TrimSpace(step.Amount.GetAmount()) != "" {
+		value, err := decimalFromMoney(step.Amount)
+		if err != nil {
+			return nil, err
+		}
+		amount = value
+		currency = strings.ToUpper(strings.TrimSpace(step.Amount.GetCurrency()))
+	}
+
+	candidates := make([]*model.GatewayInstanceDescriptor, 0)
+	var lastErr error
+	for _, entry := range items {
+		if entry == nil || !entry.IsEnabled {
+			continue
+		}
+		if entry.Rail != step.Rail {
+			continue
+		}
+		if step.GatewayID != "" && entry.ID != step.GatewayID {
+			continue
+		}
+		if step.InstanceID != "" && !strings.EqualFold(strings.TrimSpace(entry.InstanceID), strings.TrimSpace(step.InstanceID)) {
+			continue
+		}
+		if step.Action != model.RailOperationUnspecified {
+			if err := isGatewayEligible(entry, step.Rail, "", currency, step.Action, sendDirectionForRail(step.Rail), amount); err != nil {
+				lastErr = err
+				continue
+			}
+		}
+		candidates = append(candidates, entry)
+	}
+	if len(candidates) == 0 {
+		if lastErr != nil {
+			return nil, merrors.InvalidArgument("rail gateway: missing gateway for rail: " + lastErr.Error())
+		}
+		return nil, merrors.InvalidArgument("rail gateway: missing gateway for rail")
+	}
+	sort.Slice(candidates, func(i, j int) bool {
+		return candidates[i].ID < candidates[j].ID
+	})
+	entry := candidates[0]
+	invokeURI := strings.TrimSpace(entry.InvokeURI)
+	if invokeURI == "" {
+		return nil, merrors.InvalidArgument("rail gateway: invoke uri is required")
+	}
+
+	cfg := chainclient.RailGatewayConfig{
+		Rail:    string(entry.Rail),
+		Network: entry.Network,
+		Capabilities: rail.RailCapabilities{
+			CanPayIn:               entry.Capabilities.CanPayIn,
+			CanPayOut:              entry.Capabilities.CanPayOut,
+			CanReadBalance:         entry.Capabilities.CanReadBalance,
+			CanSendFee:             entry.Capabilities.CanSendFee,
+			RequiresObserveConfirm: entry.Capabilities.RequiresObserveConfirm,
+			CanBlock:               entry.Capabilities.CanBlock,
+			CanRelease:             entry.Capabilities.CanRelease,
+		},
+	}
+
+	g.logger.Info("Rail gateway resolved",
+		zap.String("step_id", strings.TrimSpace(step.StepID)),
+		zap.String("action", string(step.Action)),
+		zap.String("gateway_id", entry.ID),
+		zap.String("instance_id", entry.InstanceID),
+		zap.String("rail", string(entry.Rail)),
+		zap.String("network", entry.Network),
+		zap.String("invoke_uri", invokeURI))
+
+	switch entry.Rail {
+	case model.RailProviderSettlement:
+		if g.providerResolver == nil {
+			return nil, merrors.InvalidArgument("rail gateway: provider settlement resolver required")
+		}
+		client, err := g.providerResolver.Resolve(ctx, invokeURI)
+		if err != nil {
+			return nil, err
+		}
+		return NewProviderSettlementGateway(client, cfg), nil
+	default:
+		if g.chainResolver == nil {
+			return nil, merrors.InvalidArgument("rail gateway: chain gateway resolver required")
+		}
+		client, err := g.chainResolver.Resolve(ctx, invokeURI)
+		if err != nil {
+			return nil, err
+		}
+		return chainclient.NewRailGateway(client, cfg), nil
+	}
+}
+
+type oracleDependency struct {
+	client oracleclient.Client
+}
+
+func (o oracleDependency) available() bool {
+	if o.client == nil {
+		return false
+	}
+	if checker, ok := o.client.(interface{ Available() bool }); ok {
+		return checker.Available()
+	}
+	return true
+}
+
+type mntxDependency struct {
+	client mntxclient.Client
+}
+
+func (m mntxDependency) available() bool {
+	if m.client == nil {
+		return false
+	}
+	if checker, ok := m.client.(interface{ Available() bool }); ok {
+		return checker.Available()
+	}
+	return true
+}
+
+type providerGatewayDependency struct {
+	resolver ChainGatewayResolver
+}
+
+type staticChainGatewayResolver struct {
+	client chainclient.Client
+}
+
+func (r staticChainGatewayResolver) Resolve(ctx context.Context, _ string) (chainclient.Client, error) {
+	if r.client == nil {
+		return nil, merrors.InvalidArgument("chain gateway client is required")
+	}
+	return r.client, nil
+}
+
+// CardGatewayRoute maps a gateway to its funding and fee destinations.
+type CardGatewayRoute struct {
+	FundingAddress string
+	FeeAddress     string
+	FeeWalletRef   string
+}
+
+// WithFeeEngine wires the fee engine client.
+func WithFeeEngine(client feesv1.FeeEngineClient, timeout time.Duration) Option {
+	return func(s *Service) {
+		s.deps.fees = feesDependency{
+			client:  client,
+			timeout: timeout,
+		}
+	}
+}
+
+func WithPaymentGatewayBroker(broker mb.Broker) Option {
+	return func(s *Service) {
+		if broker != nil {
+			s.gatewayBroker = broker
+		}
+	}
+}
+
+// WithLedgerClient wires the ledger client.
+func WithLedgerClient(client ledgerclient.Client) Option {
+	return func(s *Service) {
+		s.deps.ledger = ledgerDependency{
+			client:   client,
+			internal: client,
+		}
+	}
+}
+
+// WithChainGatewayClient wires the chain gateway client.
+func WithChainGatewayClient(client chainclient.Client) Option {
+	return func(s *Service) {
+		s.deps.gateway = gatewayDependency{resolver: staticChainGatewayResolver{client: client}}
+	}
+}
+
+// WithChainGatewayResolver wires a resolver for chain gateway clients.
+func WithChainGatewayResolver(resolver ChainGatewayResolver) Option {
+	return func(s *Service) {
+		if resolver != nil {
+			s.deps.gateway = gatewayDependency{resolver: resolver}
+		}
+	}
+}
+
+// WithProviderSettlementGatewayClient wires the provider settlement gateway client.
+func WithProviderSettlementGatewayClient(client chainclient.Client) Option {
+	return func(s *Service) {
+		s.deps.providerGateway = providerGatewayDependency{resolver: staticChainGatewayResolver{client: client}}
+	}
+}
+
+// WithProviderSettlementGatewayResolver wires a resolver for provider settlement gateway clients.
+func WithProviderSettlementGatewayResolver(resolver ChainGatewayResolver) Option {
+	return func(s *Service) {
+		if resolver != nil {
+			s.deps.providerGateway = providerGatewayDependency{resolver: resolver}
+		}
+	}
+}
+
+// WithGatewayInvokeResolver wires a resolver for gateway invoke URIs.
+func WithGatewayInvokeResolver(resolver GatewayInvokeResolver) Option {
+	return func(s *Service) {
+		if resolver == nil {
+			return
+		}
+		s.deps.gatewayInvokeResolver = resolver
+		s.deps.railGateways.chainResolver = resolver
+		s.deps.railGateways.providerResolver = resolver
+	}
+}
+
+// WithRailGateways wires rail gateway adapters by instance ID.
+func WithRailGateways(gateways map[string]rail.RailGateway) Option {
+	return func(s *Service) {
+		if len(gateways) == 0 {
+			return
+		}
+		s.deps.railGateways = buildRailGatewayDependency(gateways, s.deps.gatewayRegistry, s.deps.gatewayInvokeResolver, s.deps.gatewayInvokeResolver, s.logger)
+	}
+}
+
+// WithOracleClient wires the FX oracle client.
+func WithOracleClient(client oracleclient.Client) Option {
+	return func(s *Service) {
+		s.deps.oracle = oracleDependency{client: client}
+	}
+}
+
+// WithMntxGateway wires the Monetix gateway client.
+func WithMntxGateway(client mntxclient.Client) Option {
+	return func(s *Service) {
+		s.deps.mntx = mntxDependency{client: client}
+	}
+}
+
+// WithCardGatewayRoutes configures funding/fee wallet routing per gateway.
+func WithCardGatewayRoutes(routes map[string]CardGatewayRoute) Option {
+	return func(s *Service) {
+		if len(routes) == 0 {
+			return
+		}
+		s.deps.cardRoutes = make(map[string]CardGatewayRoute, len(routes))
+		for k, v := range routes {
+			s.deps.cardRoutes[strings.ToLower(strings.TrimSpace(k))] = v
+		}
+	}
+}
+
+// WithFeeLedgerAccounts maps gateway identifiers to ledger accounts used for fees.
+func WithFeeLedgerAccounts(routes map[string]string) Option {
+	return func(s *Service) {
+		if len(routes) == 0 {
+			return
+		}
+		s.deps.feeLedgerAccounts = make(map[string]string, len(routes))
+		for k, v := range routes {
+			key := strings.ToLower(strings.TrimSpace(k))
+			val := strings.TrimSpace(v)
+			if key == "" || val == "" {
+				continue
+			}
+			s.deps.feeLedgerAccounts[key] = val
+		}
+	}
+}
+
+// WithPlanBuilder wires a payment plan builder implementation.
+func WithPlanBuilder(builder PlanBuilder) Option {
+	return func(s *Service) {
+		if builder != nil {
+			s.deps.planBuilder = builder
+		}
+	}
+}
+
+// WithGatewayRegistry wires a registry of gateway instances for routing.
+func WithGatewayRegistry(registry GatewayRegistry) Option {
+	return func(s *Service) {
+		if registry != nil {
+			s.deps.gatewayRegistry = registry
+			s.deps.railGateways.registry = registry
+			s.deps.railGateways.chainResolver = s.deps.gatewayInvokeResolver
+			s.deps.railGateways.providerResolver = s.deps.gatewayInvokeResolver
+			s.deps.railGateways.logger = s.logger.Named("rail_gateways")
+			if s.deps.planBuilder == nil {
+				s.deps.planBuilder = newDefaultPlanBuilder(s.logger)
+			}
+		}
+	}
+}
+
+// WithClock overrides the default clock.
+func WithClock(clock clockpkg.Clock) Option {
+	return func(s *Service) {
+		if clock != nil {
+			s.clock = clock
+		}
+	}
+}
+
+func buildRailGatewayDependency(gateways map[string]rail.RailGateway, registry GatewayRegistry, chainResolver GatewayInvokeResolver, providerResolver GatewayInvokeResolver, logger mlogger.Logger) railGatewayDependency {
+	result := railGatewayDependency{
+		byID:             map[string]rail.RailGateway{},
+		byRail:           map[model.Rail][]rail.RailGateway{},
+		registry:         registry,
+		chainResolver:    chainResolver,
+		providerResolver: providerResolver,
+		logger:           logger,
+	}
+	if len(gateways) == 0 {
+		return result
+	}
+
+	type item struct {
+		id string
+		gw rail.RailGateway
+	}
+	itemsByRail := map[model.Rail][]item{}
+
+	for id, gw := range gateways {
+		cleanID := strings.TrimSpace(id)
+		if cleanID == "" || gw == nil {
+			continue
+		}
+		result.byID[cleanID] = gw
+		railID := parseRailValue(gw.Rail())
+		if railID == model.RailUnspecified {
+			continue
+		}
+		itemsByRail[railID] = append(itemsByRail[railID], item{id: cleanID, gw: gw})
+	}
+
+	for railID, items := range itemsByRail {
+		sort.Slice(items, func(i, j int) bool {
+			return items[i].id < items[j].id
+		})
+		for _, entry := range items {
+			result.byRail[railID] = append(result.byRail[railID], entry.gw)
+		}
+	}
+
+	return result
+}

api/payments/quotation/internal/service/orchestrator/payment_executor.go

@@ -0,0 +1,237 @@
+package orchestrator
+
+import (
+	"context"
+	"strings"
+
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/mlogger"
+	fxv1 "github.com/tech/sendico/pkg/proto/common/fx/v1"
+	chainv1 "github.com/tech/sendico/pkg/proto/gateway/chain/v1"
+	ledgerv1 "github.com/tech/sendico/pkg/proto/ledger/v1"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"go.uber.org/zap"
+)
+
+type paymentExecutor struct {
+	deps   *serviceDependencies
+	logger mlogger.Logger
+	svc    *Service
+}
+
+func newPaymentExecutor(deps *serviceDependencies, logger mlogger.Logger, svc *Service) *paymentExecutor {
+	return &paymentExecutor{deps: deps, logger: logger, svc: svc}
+}
+
+func (p *paymentExecutor) executePayment(ctx context.Context, store storage.PaymentsStore, payment *model.Payment, quote *orchestratorv1.PaymentQuote) error {
+	if store == nil {
+		return errStorageUnavailable
+	}
+	if p.svc == nil {
+		return p.failPayment(ctx, store, payment, model.PaymentFailureCodePolicy, "service_unavailable", errStorageUnavailable)
+	}
+	if p.svc.storage == nil {
+		return p.failPayment(ctx, store, payment, model.PaymentFailureCodePolicy, "routes_store_unavailable", errStorageUnavailable)
+	}
+	routeStore := p.svc.storage.Routes()
+	if routeStore == nil {
+		return p.failPayment(ctx, store, payment, model.PaymentFailureCodePolicy, "routes_store_unavailable", errStorageUnavailable)
+	}
+	planTemplates := p.svc.storage.PlanTemplates()
+	if planTemplates == nil {
+		return p.failPayment(ctx, store, payment, model.PaymentFailureCodePolicy, "plan_templates_store_unavailable", errStorageUnavailable)
+	}
+	builder := p.svc.deps.planBuilder
+	if builder == nil {
+		builder = newDefaultPlanBuilder(p.logger)
+	}
+	plan, err := builder.Build(ctx, payment, quote, routeStore, planTemplates, p.svc.deps.gatewayRegistry)
+	if err != nil {
+		p.logPlanBuilderFailure(payment, err)
+		return p.failPayment(ctx, store, payment, model.PaymentFailureCodePolicy, strings.TrimSpace(err.Error()), err)
+	}
+	if plan == nil || len(plan.Steps) == 0 {
+		return p.failPayment(ctx, store, payment, model.PaymentFailureCodePolicy, "payment_plan_empty", merrors.InvalidArgument("payment plan is required"))
+	}
+	payment.PaymentPlan = plan
+
+	return p.executePaymentPlan(ctx, store, payment, quote)
+}
+
+func (p *paymentExecutor) logPlanBuilderFailure(payment *model.Payment, err error) {
+	if p == nil || payment == nil {
+		return
+	}
+	intent := payment.Intent
+	sourceRail, sourceNetwork, sourceErr := railFromEndpoint(intent.Source, intent.Attributes, true)
+	destRail, destNetwork, destErr := railFromEndpoint(intent.Destination, intent.Attributes, false)
+
+	fields := []zap.Field{
+		zap.Error(err),
+		zap.String("payment_ref", payment.PaymentRef),
+		zap.String("org_ref", payment.OrganizationRef.Hex()),
+		zap.String("idempotency_key", payment.IdempotencyKey),
+		zap.String("source_rail", string(sourceRail)),
+		zap.String("destination_rail", string(destRail)),
+		zap.String("source_network", sourceNetwork),
+		zap.String("destination_network", destNetwork),
+		zap.String("source_endpoint_type", string(intent.Source.Type)),
+		zap.String("destination_endpoint_type", string(intent.Destination.Type)),
+	}
+
+	missing := make([]string, 0, 2)
+	if sourceErr != nil || sourceRail == model.RailUnspecified {
+		missing = append(missing, "source")
+		if sourceErr != nil {
+			fields = append(fields, zap.String("source_rail_error", sourceErr.Error()))
+		}
+	}
+	if destErr != nil || destRail == model.RailUnspecified {
+		missing = append(missing, "destination")
+		if destErr != nil {
+			fields = append(fields, zap.String("destination_rail_error", destErr.Error()))
+		}
+	}
+	if len(missing) > 0 {
+		fields = append(fields, zap.String("missing_rails", strings.Join(missing, ",")))
+		p.logger.Warn("Payment rail resolution failed", fields...)
+		return
+	}
+
+	routeNetwork, routeErr := resolveRouteNetwork(intent.Attributes, sourceNetwork, destNetwork)
+	if routeErr != nil {
+		fields = append(fields, zap.String("route_network_error", routeErr.Error()))
+	} else if routeNetwork != "" {
+		fields = append(fields, zap.String("route_network", routeNetwork))
+	}
+	p.logger.Warn("Payment route missing for rails", fields...)
+}
+
+func (p *paymentExecutor) applyFX(ctx context.Context, payment *model.Payment, quote *orchestratorv1.PaymentQuote, charges []*ledgerv1.PostingLine, description string, metadata map[string]string, exec *model.ExecutionRefs) error {
+	intent := payment.Intent
+	source := intent.Source.Ledger
+	destination := intent.Destination.Ledger
+	if source == nil || destination == nil {
+		return merrors.InvalidArgument("ledger: fx conversion requires ledger source and destination")
+	}
+	fq := quote.GetFxQuote()
+	if fq == nil {
+		return merrors.InvalidArgument("ledger: fx quote missing")
+	}
+	fxSide := fxv1.Side_SIDE_UNSPECIFIED
+	if intent.FX != nil {
+		fxSide = fxSideToProto(intent.FX.Side)
+	}
+	fromMoney, toMoney := resolveTradeAmounts(protoMoney(intent.Amount), fq, fxSide)
+	if fromMoney == nil {
+		fromMoney = protoMoney(intent.Amount)
+	}
+	if toMoney == nil {
+		toMoney = cloneProtoMoney(quote.GetExpectedSettlementAmount())
+	}
+	rate := ""
+	if fq.GetPrice() != nil {
+		rate = fq.GetPrice().GetValue()
+	}
+	req := &ledgerv1.FXRequest{
+		IdempotencyKey:       payment.IdempotencyKey,
+		OrganizationRef:      payment.OrganizationRef.Hex(),
+		FromLedgerAccountRef: strings.TrimSpace(source.LedgerAccountRef),
+		ToLedgerAccountRef:   strings.TrimSpace(destination.LedgerAccountRef),
+		FromMoney:            fromMoney,
+		ToMoney:              toMoney,
+		Rate:                 rate,
+		Description:          description,
+		Charges:              charges,
+		Metadata:             metadata,
+	}
+	resp, err := p.deps.ledger.client.ApplyFXWithCharges(ctx, req)
+	if err != nil {
+		return err
+	}
+	exec.FXEntryRef = strings.TrimSpace(resp.GetJournalEntryRef())
+	payment.Execution = exec
+	return nil
+}
+
+func (p *paymentExecutor) persistPayment(ctx context.Context, store storage.PaymentsStore, payment *model.Payment) error {
+	if store == nil {
+		return errStorageUnavailable
+	}
+	return store.Update(ctx, payment)
+}
+
+func (p *paymentExecutor) failPayment(ctx context.Context, store storage.PaymentsStore, payment *model.Payment, code model.PaymentFailureCode, reason string, err error) error {
+	payment.State = model.PaymentStateFailed
+	payment.FailureCode = code
+	payment.FailureReason = strings.TrimSpace(reason)
+	if store != nil {
+		if updateErr := store.Update(ctx, payment); updateErr != nil {
+			p.logger.Error("failed to persist payment failure", zap.Error(updateErr), zap.String("payment_ref", payment.PaymentRef))
+		}
+	}
+	if err != nil {
+		return err
+	}
+	return merrors.Internal(reason)
+}
+
+func paymentDescription(payment *model.Payment) string {
+	if payment == nil {
+		return ""
+	}
+	if val := strings.TrimSpace(payment.Intent.Attributes["description"]); val != "" {
+		return val
+	}
+	if payment.Metadata != nil {
+		if val := strings.TrimSpace(payment.Metadata["description"]); val != "" {
+			return val
+		}
+	}
+	return payment.PaymentRef
+}
+
+func applyTransferStatus(event *chainv1.TransferStatusChangedEvent, payment *model.Payment) {
+	if payment.Execution == nil {
+		payment.Execution = &model.ExecutionRefs{}
+	}
+	if event == nil || event.GetTransfer() == nil {
+		return
+	}
+	transfer := event.GetTransfer()
+	payment.Execution.ChainTransferRef = strings.TrimSpace(transfer.GetTransferRef())
+	reason := strings.TrimSpace(event.GetReason())
+	if reason == "" {
+		reason = strings.TrimSpace(transfer.GetFailureReason())
+	}
+	switch transfer.GetStatus() {
+
+	case chainv1.TransferStatus_TRANSFER_SUCCESS:
+		payment.State = model.PaymentStateSettled
+		payment.FailureCode = model.PaymentFailureCodeUnspecified
+		payment.FailureReason = ""
+
+	case chainv1.TransferStatus_TRANSFER_FAILED:
+		payment.State = model.PaymentStateFailed
+		payment.FailureCode = model.PaymentFailureCodeChain
+		payment.FailureReason = reason
+
+	case chainv1.TransferStatus_TRANSFER_CANCELLED:
+		payment.State = model.PaymentStateCancelled
+		payment.FailureCode = model.PaymentFailureCodePolicy
+		payment.FailureReason = reason
+
+	case chainv1.TransferStatus_TRANSFER_WAITING:
+		payment.State = model.PaymentStateSubmitted
+
+	case chainv1.TransferStatus_TRANSFER_CREATED,
+		chainv1.TransferStatus_TRANSFER_PROCESSING:
+		// do nothing, retain previous state
+
+	default:
+		// retain previous state
+	}
+
+}

api/payments/quotation/internal/service/orchestrator/payment_plan_analyzer.go

@@ -0,0 +1,123 @@
+package orchestrator
+
+import (
+	"errors"
+
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/mlogger"
+	"go.uber.org/zap"
+)
+
+type Liveness string
+
+const (
+	StepFinal    Liveness = "final"
+	StepRunnable Liveness = "runnable"
+	StepBlocked  Liveness = "blocked"
+	StepDead     Liveness = "dead"
+)
+
+func buildPaymentStepIndex(plan *model.PaymentPlan) map[string]*model.PaymentStep {
+	idx := make(map[string]*model.PaymentStep, len(plan.Steps))
+	for _, s := range plan.Steps {
+		idx[s.StepID] = s
+	}
+	return idx
+}
+
+func buildExecutionStepIndex(plan *model.ExecutionPlan) map[string]*model.ExecutionStep {
+	index := make(map[string]*model.ExecutionStep, len(plan.Steps))
+	for _, s := range plan.Steps {
+		if s == nil {
+			continue
+		}
+		index[s.Code] = s
+	}
+	return index
+}
+
+func stepLiveness(
+	logger mlogger.Logger,
+	step *model.ExecutionStep,
+	pStepIdx map[string]*model.PaymentStep,
+	eStepIdx map[string]*model.ExecutionStep,
+) Liveness {
+
+	if step.IsTerminal() {
+		return StepFinal
+	}
+
+	pStep, ok := pStepIdx[step.Code]
+	if !ok {
+		logger.Error("step missing in payment plan",
+			zap.String("step_id", step.Code),
+		)
+		return StepDead
+	}
+
+	for _, depID := range pStep.DependsOn {
+		dep := eStepIdx[depID]
+		if dep == nil {
+			logger.Warn("dependency missing in execution plan",
+				zap.String("step_id", step.Code),
+				zap.String("dep_id", depID),
+			)
+			continue
+		}
+
+		switch dep.State {
+		case model.OperationStateFailed:
+			return StepDead
+		}
+	}
+
+	allSuccess := true
+	for _, depID := range pStep.DependsOn {
+		dep := eStepIdx[depID]
+		if dep == nil || dep.State != model.OperationStateSuccess {
+			allSuccess = false
+			break
+		}
+	}
+
+	if allSuccess {
+		return StepRunnable
+	}
+
+	return StepBlocked
+}
+
+func analyzeExecutionPlan(
+	logger mlogger.Logger,
+	payment *model.Payment,
+) (bool, bool, error) {
+
+	if payment == nil || payment.ExecutionPlan == nil {
+		return true, false, nil
+	}
+
+	eIdx := buildExecutionStepIndex(payment.ExecutionPlan)
+	pIdx := buildPaymentStepIndex(payment.PaymentPlan)
+
+	hasRunnable := false
+	hasFailed := false
+	var rootErr error
+
+	for _, s := range payment.ExecutionPlan.Steps {
+		live := stepLiveness(logger, s, pIdx, eIdx)
+
+		if live == StepRunnable {
+			hasRunnable = true
+		}
+
+		if s.State == model.OperationStateFailed {
+			hasFailed = true
+			if rootErr == nil && s.Error != "" {
+				rootErr = errors.New(s.Error)
+			}
+		}
+	}
+
+	done := !hasRunnable
+	return done, hasFailed, rootErr
+}

api/payments/quotation/internal/service/orchestrator/payment_plan_card.go

@@ -0,0 +1,196 @@
+package orchestrator
+
+import (
+	"context"
+	"strings"
+
+	"github.com/shopspring/decimal"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/model/account_role"
+	moneyv1 "github.com/tech/sendico/pkg/proto/common/money/v1"
+	mntxv1 "github.com/tech/sendico/pkg/proto/gateway/mntx/v1"
+)
+
+func (p *paymentExecutor) submitCardPayoutPlan(ctx context.Context, payment *model.Payment, operationRef string, amount *moneyv1.Money, fromRole, toRole *account_role.AccountRole) (string, error) {
+	if payment == nil {
+		return "", merrors.InvalidArgument("payment is required")
+	}
+	if !p.deps.mntx.available() {
+		return "", merrors.Internal("card_gateway_unavailable")
+	}
+	intent := payment.Intent
+	card := intent.Destination.Card
+	if card == nil {
+		return "", merrors.InvalidArgument("card payout: card endpoint is required")
+	}
+	if amount == nil || strings.TrimSpace(amount.GetAmount()) == "" || strings.TrimSpace(amount.GetCurrency()) == "" {
+		return "", merrors.InvalidArgument("card payout: amount is required")
+	}
+
+	amtDec, err := decimalFromMoney(amount)
+	if err != nil {
+		return "", err
+	}
+	minor := amtDec.Mul(decimal.NewFromInt(100)).IntPart()
+
+	payoutID := payment.PaymentRef
+	currency := strings.TrimSpace(amount.GetCurrency())
+	holder := strings.TrimSpace(card.Cardholder)
+	meta := cloneMetadata(payment.Metadata)
+	if strings.TrimSpace(string(mergeAccountRole(fromRole))) != "" {
+		if meta == nil {
+			meta = map[string]string{}
+		}
+		meta[account_role.MetadataKeyFromRole] = strings.TrimSpace(string(mergeAccountRole(fromRole)))
+	}
+	if strings.TrimSpace(string(mergeAccountRole(toRole))) != "" {
+		if meta == nil {
+			meta = map[string]string{}
+		}
+		meta[account_role.MetadataKeyToRole] = strings.TrimSpace(string(mergeAccountRole(toRole)))
+	}
+	customer := intent.Customer
+	customerID := ""
+	customerFirstName := ""
+	customerMiddleName := ""
+	customerLastName := ""
+	customerIP := ""
+	customerZip := ""
+	customerCountry := ""
+	customerState := ""
+	customerCity := ""
+	customerAddress := ""
+	if customer != nil {
+		customerID = strings.TrimSpace(customer.ID)
+		customerFirstName = strings.TrimSpace(customer.FirstName)
+		customerMiddleName = strings.TrimSpace(customer.MiddleName)
+		customerLastName = strings.TrimSpace(customer.LastName)
+		customerIP = strings.TrimSpace(customer.IP)
+		customerZip = strings.TrimSpace(customer.Zip)
+		customerCountry = strings.TrimSpace(customer.Country)
+		customerState = strings.TrimSpace(customer.State)
+		customerCity = strings.TrimSpace(customer.City)
+		customerAddress = strings.TrimSpace(customer.Address)
+	}
+	if customerFirstName == "" {
+		customerFirstName = strings.TrimSpace(card.Cardholder)
+	}
+	if customerLastName == "" {
+		customerLastName = strings.TrimSpace(card.CardholderSurname)
+	}
+	if customerID == "" {
+		return "", merrors.InvalidArgument("card payout: customer id is required")
+	}
+	if customerFirstName == "" {
+		return "", merrors.InvalidArgument("card payout: customer first name is required")
+	}
+	if customerLastName == "" {
+		return "", merrors.InvalidArgument("card payout: customer last name is required")
+	}
+	if customerIP == "" {
+		return "", merrors.InvalidArgument("card payout: customer ip is required")
+	}
+
+	var state *mntxv1.CardPayoutState
+	if token := strings.TrimSpace(card.Token); token != "" {
+		req := &mntxv1.CardTokenPayoutRequest{
+			PayoutId:           payoutID,
+			CustomerId:         customerID,
+			CustomerFirstName:  customerFirstName,
+			CustomerMiddleName: customerMiddleName,
+			CustomerLastName:   customerLastName,
+			CustomerIp:         customerIP,
+			CustomerZip:        customerZip,
+			CustomerCountry:    customerCountry,
+			CustomerState:      customerState,
+			CustomerCity:       customerCity,
+			CustomerAddress:    customerAddress,
+			AmountMinor:        minor,
+			Currency:           currency,
+			CardToken:          token,
+			CardHolder:         holder,
+			MaskedPan:          strings.TrimSpace(card.MaskedPan),
+			Metadata:           meta,
+			OperationRef:       operationRef,
+			IntentRef:          payment.Intent.Ref,
+			IdempotencyKey:     payment.IdempotencyKey,
+		}
+		resp, err := p.deps.mntx.client.CreateCardTokenPayout(ctx, req)
+		if err != nil {
+			return "", err
+		}
+		state = resp.GetPayout()
+	} else if pan := strings.TrimSpace(card.Pan); pan != "" {
+		req := &mntxv1.CardPayoutRequest{
+			PayoutId:           payoutID,
+			CustomerId:         customerID,
+			CustomerFirstName:  customerFirstName,
+			CustomerMiddleName: customerMiddleName,
+			CustomerLastName:   customerLastName,
+			CustomerIp:         customerIP,
+			CustomerZip:        customerZip,
+			CustomerCountry:    customerCountry,
+			CustomerState:      customerState,
+			CustomerCity:       customerCity,
+			CustomerAddress:    customerAddress,
+			AmountMinor:        minor,
+			Currency:           currency,
+			CardPan:            pan,
+			CardExpYear:        card.ExpYear,
+			CardExpMonth:       card.ExpMonth,
+			CardHolder:         holder,
+			Metadata:           meta,
+			OperationRef:       operationRef,
+			IntentRef:          payment.Intent.Ref,
+			IdempotencyKey:     payment.IdempotencyKey,
+		}
+		resp, err := p.deps.mntx.client.CreateCardPayout(ctx, req)
+		if err != nil {
+			return "", err
+		}
+		state = resp.GetPayout()
+	} else {
+		return "", merrors.InvalidArgument("card payout: either token or pan must be provided")
+	}
+
+	if state == nil {
+		return "", merrors.Internal("card payout: missing payout state")
+	}
+	recordCardPayoutState(payment, state)
+	exec := ensureExecutionRefs(payment)
+	if exec.CardPayoutRef == "" {
+		exec.CardPayoutRef = strings.TrimSpace(state.GetPayoutId())
+	}
+	return exec.CardPayoutRef, nil
+}
+
+func mergeAccountRole(role *account_role.AccountRole) account_role.AccountRole {
+	if role == nil {
+		return ""
+	}
+	return account_role.AccountRole(strings.TrimSpace(string(*role)))
+}
+
+func (p *paymentExecutor) resolveCardRoute(intent model.PaymentIntent) (CardGatewayRoute, error) {
+	if p.svc != nil {
+		return p.svc.cardRoute(p.gatewayKeyFromIntent(intent))
+	}
+	key := p.gatewayKeyFromIntent(intent)
+	route, ok := p.deps.cardRoutes[key]
+	if !ok {
+		return CardGatewayRoute{}, merrors.InvalidArgument("card routing missing for gateway " + key)
+	}
+	if strings.TrimSpace(route.FundingAddress) == "" {
+		return CardGatewayRoute{}, merrors.InvalidArgument("card funding address is required for gateway " + key)
+	}
+	return route, nil
+}
+
+func (p *paymentExecutor) gatewayKeyFromIntent(intent model.PaymentIntent) string {
+	key := strings.TrimSpace(intent.Attributes["gateway"])
+	if key == "" && intent.Destination.Card != nil {
+		key = defaultCardGateway
+	}
+	return strings.ToLower(key)
+}

api/payments/quotation/internal/service/orchestrator/payment_plan_chain.go

@@ -0,0 +1,116 @@
+package orchestrator
+
+import (
+	"strings"
+
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/model/account_role"
+	"github.com/tech/sendico/pkg/payments/rail"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+)
+
+func (p *paymentExecutor) buildCryptoTransferRequest(payment *model.Payment, amount *paymenttypes.Money, action model.RailOperation, idempotencyKey, operationRef string, quote *orchestratorv1.PaymentQuote, fromRole, toRole *account_role.AccountRole) (rail.TransferRequest, error) {
+	if payment == nil {
+		return rail.TransferRequest{}, merrors.InvalidArgument("chain: payment is required")
+	}
+	if amount == nil {
+		return rail.TransferRequest{}, merrors.InvalidArgument("chain: amount is required")
+	}
+	source := payment.Intent.Source.ManagedWallet
+	if source == nil || strings.TrimSpace(source.ManagedWalletRef) == "" {
+		return rail.TransferRequest{}, merrors.InvalidArgument("chain: source managed wallet is required")
+	}
+	destRef, memo, err := p.resolveCryptoDestination(payment, action)
+	if err != nil {
+		return rail.TransferRequest{}, err
+	}
+	paymentRef := strings.TrimSpace(payment.PaymentRef)
+	if paymentRef == "" {
+		return rail.TransferRequest{}, merrors.InvalidArgument("chain: payment reference is required")
+	}
+	req := rail.TransferRequest{
+		IntentRef:       strings.TrimSpace(payment.Intent.Ref),
+		OperationRef:    strings.TrimSpace(operationRef),
+		OrganizationRef: payment.OrganizationRef.Hex(),
+		PaymentRef:      strings.TrimSpace(payment.PaymentRef),
+		FromAccountID:   strings.TrimSpace(source.ManagedWalletRef),
+		ToAccountID:     strings.TrimSpace(destRef),
+		Currency:        strings.TrimSpace(amount.GetCurrency()),
+		Network:         strings.TrimSpace(cryptoNetworkForPayment(payment)),
+		Amount:          strings.TrimSpace(amount.GetAmount()),
+		IdempotencyKey:  strings.TrimSpace(idempotencyKey),
+		Metadata:        cloneMetadata(payment.Metadata),
+		DestinationMemo: memo,
+	}
+	if fromRole != nil {
+		req.FromRole = *fromRole
+	}
+	if toRole != nil {
+		req.ToRole = *toRole
+	}
+	if req.Currency == "" || req.Amount == "" {
+		return rail.TransferRequest{}, merrors.InvalidArgument("chain: amount is required")
+	}
+	if req.IdempotencyKey == "" {
+		return rail.TransferRequest{}, merrors.InvalidArgument("chain: idempotency_key is required")
+	}
+	return req, nil
+}
+
+func (p *paymentExecutor) resolveCryptoDestination(payment *model.Payment, action model.RailOperation) (string, string, error) {
+	if payment == nil {
+		return "", "", merrors.InvalidArgument("chain: payment is required")
+	}
+	intent := payment.Intent
+	switch intent.Destination.Type {
+	case model.EndpointTypeManagedWallet:
+		if action == model.RailOperationSend {
+			if intent.Destination.ManagedWallet == nil || strings.TrimSpace(intent.Destination.ManagedWallet.ManagedWalletRef) == "" {
+				return "", "", merrors.InvalidArgument("chain: destination managed wallet is required")
+			}
+			return strings.TrimSpace(intent.Destination.ManagedWallet.ManagedWalletRef), "", nil
+		}
+	case model.EndpointTypeExternalChain:
+		if action == model.RailOperationSend {
+			if intent.Destination.ExternalChain == nil || strings.TrimSpace(intent.Destination.ExternalChain.Address) == "" {
+				return "", "", merrors.InvalidArgument("chain: external address is required")
+			}
+			return strings.TrimSpace(intent.Destination.ExternalChain.Address), strings.TrimSpace(intent.Destination.ExternalChain.Memo), nil
+		}
+	}
+	route, err := p.resolveCardRoute(intent)
+	if err != nil {
+		return "", "", err
+	}
+	switch action {
+	case model.RailOperationSend:
+		address := strings.TrimSpace(route.FundingAddress)
+		if address == "" {
+			return "", "", merrors.InvalidArgument("chain: funding address is required")
+		}
+		return address, "", nil
+	case model.RailOperationFee:
+		if walletRef := strings.TrimSpace(route.FeeWalletRef); walletRef != "" {
+			return walletRef, "", nil
+		}
+		if address := strings.TrimSpace(route.FeeAddress); address != "" {
+			return address, "", nil
+		}
+		return "", "", merrors.InvalidArgument("chain: fee destination is required")
+	default:
+		return "", "", merrors.InvalidArgument("chain: unsupported action")
+	}
+}
+
+func cryptoNetworkForPayment(payment *model.Payment) string {
+	if payment == nil {
+		return ""
+	}
+	network := networkFromEndpoint(payment.Intent.Source)
+	if network != "" {
+		return network
+	}
+	return networkFromEndpoint(payment.Intent.Destination)
+}

api/payments/quotation/internal/service/orchestrator/payment_plan_executor.go

@@ -0,0 +1,208 @@
+package orchestrator
+
+import (
+	"context"
+
+	"github.com/tech/sendico/payments/storage"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/merrors"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+	"go.uber.org/zap"
+)
+
+func buildStepIndex(plan *model.PaymentPlan) map[string]int {
+	m := make(map[string]int, len(plan.Steps))
+	for i, s := range plan.Steps {
+		if s == nil {
+			continue
+		}
+		m[s.StepID] = i
+	}
+	return m
+}
+
+func isPlanComplete(payment *model.Payment) bool {
+	if (payment.State == model.PaymentStateCancelled) ||
+		(payment.State == model.PaymentStateSettled) ||
+		(payment.State == model.PaymentStateFailed) {
+		return true
+	}
+	return false
+}
+
+func isStepFinal(step *model.ExecutionStep) bool {
+	if (step.State == model.OperationStateFailed) || (step.State == model.OperationStateSuccess) || (step.State == model.OperationStateCancelled) {
+		return true
+	}
+	return false
+}
+
+func (p *paymentExecutor) pickIndependentSteps(
+	ctx context.Context,
+	l *zap.Logger,
+	store storage.PaymentsStore,
+	waiting []*model.ExecutionStep,
+	payment *model.Payment,
+	quote *orchestratorv1.PaymentQuote,
+) error {
+
+	logger := l.With(zap.Int("waiting_steps", len(waiting)))
+	logger.Debug("Selecting independent steps for execution")
+
+	execSteps := executionStepsByCode(payment.ExecutionPlan)
+	planSteps := planStepsByID(payment.PaymentPlan)
+	execQuote := executionQuote(payment, quote)
+	charges := ledgerChargesFromFeeLines(execQuote.GetFeeLines())
+	stepIdx := buildStepIndex(payment.PaymentPlan)
+
+	for _, execStep := range waiting {
+		if execStep == nil {
+			continue
+		}
+
+		lg := logger.With(
+			zap.String("step_code", execStep.Code),
+			zap.String("step_state", string(execStep.State)),
+		)
+
+		planStep := planSteps[execStep.Code]
+		if planStep == nil {
+			lg.Warn("Plan step not found")
+			continue
+		}
+
+		ready, waitingDep, blocked, err :=
+			stepDependenciesReady(planStep, execSteps, planSteps, true)
+
+		if err != nil {
+			lg.Warn("Dependency evaluation failed", zap.Error(err))
+			continue
+		}
+
+		if blocked {
+			lg.Debug("Step permanently blocked by dependency failure")
+			setExecutionStepStatus(execStep, model.OperationStateCancelled)
+			continue
+		}
+
+		if waitingDep {
+			lg.Debug("Step waiting for dependencies")
+			continue
+		}
+
+		if !ready {
+			continue
+		}
+
+		lg.Debug("Executing independent step")
+		idx := stepIdx[execStep.Code]
+
+		async, err := p.executePlanStep(
+			ctx,
+			payment,
+			planStep,
+			execStep,
+			quote,
+			charges,
+			idx,
+		)
+		if err != nil {
+			lg.Warn("Step execution failed", zap.Error(err), zap.Bool("async", async))
+			return err
+		}
+	}
+
+	return nil
+}
+
+func (p *paymentExecutor) pickWaitingSteps(
+	ctx context.Context,
+	l *zap.Logger,
+	store storage.PaymentsStore,
+	payment *model.Payment,
+	quote *orchestratorv1.PaymentQuote,
+) error {
+	if payment == nil || payment.ExecutionPlan == nil {
+		l.Debug("No execution plan")
+		return nil
+	}
+
+	logger := l.With(zap.Int("total_steps", len(payment.ExecutionPlan.Steps)))
+	logger.Debug("Collecting waiting steps")
+
+	waitingSteps := make([]*model.ExecutionStep, 0, len(payment.ExecutionPlan.Steps))
+	for _, step := range payment.ExecutionPlan.Steps {
+		if step == nil {
+			continue
+		}
+		if step.State != model.OperationStatePlanned {
+			continue
+		}
+		waitingSteps = append(waitingSteps, step)
+	}
+
+	if len(waitingSteps) == 0 {
+		logger.Debug("No waiting steps to process")
+		return nil
+	}
+
+	return p.pickIndependentSteps(ctx, logger, store, waitingSteps, payment, quote)
+}
+
+func (p *paymentExecutor) executePaymentPlan(
+	ctx context.Context,
+	store storage.PaymentsStore,
+	payment *model.Payment,
+	quote *orchestratorv1.PaymentQuote,
+) error {
+
+	if payment == nil {
+		return merrors.InvalidArgument("plan must be provided")
+	}
+
+	logger := p.logger.With(zap.String("payment_ref", payment.PaymentRef))
+	logger.Debug("Starting plan execution")
+
+	if isPlanComplete(payment) {
+		logger.Debug("Plan already completed")
+		return nil
+	}
+
+	if payment.ExecutionPlan == nil {
+		logger.Debug("Initializing execution plan from payment plan")
+		payment.ExecutionPlan = ensureExecutionPlanForPlan(payment, payment.PaymentPlan)
+		if err := store.Update(ctx, payment); err != nil {
+			return err
+		}
+	}
+
+	// Execute steps
+	if err := p.pickWaitingSteps(ctx, logger, store, payment, quote); err != nil {
+		logger.Warn("Step execution returned infrastructure error", zap.Error(err))
+	}
+
+	if err := store.Update(ctx, payment); err != nil {
+		return err
+	}
+
+	done, failed, rootErr := analyzeExecutionPlan(logger, payment)
+	if !done {
+		return nil
+	}
+
+	if failed {
+		payment.State = model.PaymentStateFailed
+	} else {
+		payment.State = model.PaymentStateSettled
+	}
+
+	if err := store.Update(ctx, payment); err != nil {
+		logger.Warn("Failed to update final payment state", zap.Error(err))
+		return err
+	}
+
+	if failed && rootErr != nil {
+		return rootErr
+	}
+	return nil
+}

api/payments/quotation/internal/service/orchestrator/payment_plan_helpers.go

@@ -0,0 +1,215 @@
+package orchestrator
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/google/uuid"
+	"github.com/tech/sendico/payments/storage/model"
+	"github.com/tech/sendico/pkg/model/account_role"
+	orchestratorv1 "github.com/tech/sendico/pkg/proto/payments/orchestrator/v1"
+)
+
+func ensureExecutionRefs(payment *model.Payment) *model.ExecutionRefs {
+	if payment.Execution == nil {
+		payment.Execution = &model.ExecutionRefs{}
+	}
+	return payment.Execution
+}
+
+func executionQuote(payment *model.Payment, quote *orchestratorv1.PaymentQuote) *orchestratorv1.PaymentQuote {
+	if quote != nil {
+		return quote
+	}
+	if payment != nil && payment.LastQuote != nil {
+		return modelQuoteToProto(payment.LastQuote)
+	}
+	return &orchestratorv1.PaymentQuote{}
+}
+
+func ensureExecutionPlanForPlan(
+	payment *model.Payment,
+	plan *model.PaymentPlan,
+) *model.ExecutionPlan {
+
+	if payment.ExecutionPlan != nil {
+		return payment.ExecutionPlan
+	}
+
+	exec := &model.ExecutionPlan{
+		Steps: make([]*model.ExecutionStep, 0, len(plan.Steps)),
+	}
+
+	for _, step := range plan.Steps {
+		if step == nil {
+			continue
+		}
+
+		exec.Steps = append(exec.Steps, &model.ExecutionStep{
+			Code:         step.StepID,
+			State:        model.OperationStatePlanned,
+			OperationRef: uuid.New().String(),
+		})
+	}
+
+	return exec
+}
+
+func executionPlanComplete(plan *model.ExecutionPlan) bool {
+	if plan == nil || len(plan.Steps) == 0 {
+		return false
+	}
+	for _, step := range plan.Steps {
+		if step == nil {
+			continue
+		}
+		if step.State == model.OperationStateSkipped {
+			continue
+		}
+		if step.State != model.OperationStateSuccess {
+			return false
+		}
+	}
+	return true
+}
+
+func blockStepConfirmed(plan *model.PaymentPlan, execPlan *model.ExecutionPlan) bool {
+	if plan == nil || execPlan == nil || len(plan.Steps) == 0 {
+		return false
+	}
+	execSteps := executionStepsByCode(execPlan)
+	for idx, step := range plan.Steps {
+		if step == nil || step.Action != model.RailOperationBlock {
+			continue
+		}
+		execStep := execSteps[planStepID(step, idx)]
+		if execStep == nil {
+			continue
+		}
+		if execStep.State == model.OperationStateSuccess {
+			return true
+		}
+	}
+	return false
+}
+
+func roleHintsForStep(plan *model.PaymentPlan, idx int) (*account_role.AccountRole, *account_role.AccountRole) {
+	if plan == nil || idx <= 0 {
+		return nil, nil
+	}
+	for i := idx - 1; i >= 0; i-- {
+		step := plan.Steps[i]
+		if step == nil {
+			continue
+		}
+		if step.Rail != model.RailLedger || step.Action != model.RailOperationMove {
+			continue
+		}
+		if step.ToRole != nil && strings.TrimSpace(string(*step.ToRole)) != "" {
+			role := *step.ToRole
+			return &role, nil
+		}
+	}
+	return nil, nil
+}
+
+func linkRailObservation(payment *model.Payment, rail model.Rail, referenceID, dependsOn string) {
+	if payment == nil || payment.PaymentPlan == nil {
+		return
+	}
+	ref := strings.TrimSpace(referenceID)
+	if ref == "" {
+		return
+	}
+	plan := payment.PaymentPlan
+	execPlan := ensureExecutionPlanForPlan(payment, plan)
+	if execPlan == nil {
+		return
+	}
+	dep := strings.TrimSpace(dependsOn)
+	for idx, planStep := range plan.Steps {
+		if planStep == nil {
+			continue
+		}
+		if planStep.Rail != rail || planStep.Action != model.RailOperationObserveConfirm {
+			continue
+		}
+		if dep != "" {
+			matched := false
+			for _, entry := range planStep.DependsOn {
+				if strings.EqualFold(strings.TrimSpace(entry), dep) {
+					matched = true
+					break
+				}
+			}
+			if !matched {
+				continue
+			}
+		}
+		if idx >= len(execPlan.Steps) {
+			continue
+		}
+		execStep := execPlan.Steps[idx]
+		if execStep == nil {
+			execStep = &model.ExecutionStep{Code: planStepID(planStep, idx), Description: describePlanStep(planStep)}
+			execPlan.Steps[idx] = execStep
+		}
+		if execStep.TransferRef == "" {
+			execStep.TransferRef = ref
+		}
+	}
+}
+
+func planStepID(step *model.PaymentStep, idx int) string {
+	if step != nil {
+		if val := strings.TrimSpace(step.StepID); val != "" {
+			return val
+		}
+	}
+	return fmt.Sprintf("plan_step_%d", idx)
+}
+
+func describePlanStep(step *model.PaymentStep) string {
+	if step == nil {
+		return ""
+	}
+	return strings.TrimSpace(fmt.Sprintf("%s %s", step.Rail, step.Action))
+}
+
+func planStepIdempotencyKey(payment *model.Payment, idx int, step *model.PaymentStep) string {
+	base := ""
+	if payment != nil {
+		base = strings.TrimSpace(payment.IdempotencyKey)
+		if base == "" {
+			base = strings.TrimSpace(payment.PaymentRef)
+		}
+	}
+	if base == "" {
+		base = "payment"
+	}
+	if step == nil {
+		return fmt.Sprintf("%s:plan:%d", base, idx)
+	}
+	stepID := strings.TrimSpace(step.StepID)
+	if stepID == "" {
+		stepID = fmt.Sprintf("%d", idx)
+	}
+	return fmt.Sprintf("%s:plan:%s:%s:%s", base, stepID, strings.ToLower(string(step.Rail)), strings.ToLower(string(step.Action)))
+}
+
+func failureCodeForStep(step *model.PaymentStep) model.PaymentFailureCode {
+	if step == nil {
+		return model.PaymentFailureCodePolicy
+	}
+	switch step.Rail {
+	case model.RailLedger:
+		if step.Action == model.RailOperationFXConvert {
+			return model.PaymentFailureCodeFX
+		}
+		return model.PaymentFailureCodeLedger
+	case model.RailCrypto:
+		return model.PaymentFailureCodeChain
+	default:
+		return model.PaymentFailureCodePolicy
+	}
+}