move api/server to api/edge/bff

api/edge/bff/interface/api/srequest/acceptinvitation.go

@@ -0,0 +1,7 @@
+package srequest
+
+import "github.com/tech/sendico/pkg/model"
+
+type AcceptInvitation struct {
+	Account *model.AccountData `json:"account,omitempty"`
+}

api/edge/bff/interface/api/srequest/changepolicies.go

@@ -0,0 +1,12 @@
+package srequest
+
+import (
+	"github.com/tech/sendico/pkg/model"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type ChangePolicies struct {
+	RoleRef bson.ObjectID       `json:"roleRef"`
+	Add     *[]model.RolePolicy `json:"add,omitempty"`
+	Remove  *[]model.RolePolicy `json:"remove,omitempty"`
+}

api/edge/bff/interface/api/srequest/changerole.go

@@ -0,0 +1,8 @@
+package srequest
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type ChangeRole struct {
+	AccountRef            bson.ObjectID `json:"accountRef"`
+	NewRoleDescriptionRef bson.ObjectID `json:"newRoleDescriptionRef"`
+}

api/edge/bff/interface/api/srequest/customer.go

@@ -0,0 +1,15 @@
+package srequest
+
+// Customer captures payer/recipient identity details for downstream processing.
+type Customer struct {
+	ID         string `json:"id,omitempty"`
+	FirstName  string `json:"first_name,omitempty"`
+	MiddleName string `json:"middle_name,omitempty"`
+	LastName   string `json:"last_name,omitempty"`
+	IP         string `json:"ip,omitempty"`
+	Zip        string `json:"zip,omitempty"`
+	Country    string `json:"country,omitempty"`
+	State      string `json:"state,omitempty"`
+	City       string `json:"city,omitempty"`
+	Address    string `json:"address,omitempty"`
+}

api/edge/bff/interface/api/srequest/endpoint_payloads.go

@@ -0,0 +1,76 @@
+package srequest
+
+// Asset represents a chain/token pair for blockchain endpoints.
+type Asset struct {
+	Chain           ChainNetwork `json:"chain"`
+	TokenSymbol     string       `json:"token_symbol"`
+	ContractAddress string       `json:"contract_address,omitempty"`
+}
+
+// LedgerEndpoint represents a ledger account payload.
+type LedgerEndpoint struct {
+	LedgerAccountRef       string `json:"ledger_account_ref"`
+	ContraLedgerAccountRef string `json:"contra_ledger_account_ref,omitempty"`
+}
+
+// ManagedWalletEndpoint represents a managed wallet payload.
+type ManagedWalletEndpoint struct {
+	ManagedWalletRef string `json:"managed_wallet_ref"`
+	Asset            *Asset `json:"asset,omitempty"`
+}
+
+// ExternalChainEndpoint represents an external chain address payload.
+type ExternalChainEndpoint struct {
+	Asset   *Asset `json:"asset,omitempty"`
+	Address string `json:"address"`
+	Memo    string `json:"memo,omitempty"`
+}
+
+// CardEndpoint represents a card payout payload (PAN or network token).
+type CardEndpoint struct {
+	Pan       string `json:"pan"`
+	FirstName string `json:"firstName"`
+	LastName  string `json:"lastName"`
+	ExpMonth  uint32 `json:"exp_month,omitempty"`
+	ExpYear   uint32 `json:"exp_year,omitempty"`
+	Country   string `json:"country,omitempty"`
+}
+
+// CardTokenEndpoint represents a vaulted card token payout payload.
+type CardTokenEndpoint struct {
+	Token     string `json:"token"`
+	MaskedPan string `json:"masked_pan"`
+}
+
+// WalletEndpoint represents a Sendico wallet payout payload.
+type WalletEndpoint struct {
+	WalletID string `json:"walletId"`
+}
+
+// BankAccountEndpoint represents a domestic bank account payout payload.
+type BankAccountEndpoint struct {
+	RecipientName        string `json:"recipientName"`
+	Inn                  string `json:"inn"`
+	Kpp                  string `json:"kpp"`
+	BankName             string `json:"bankName"`
+	Bik                  string `json:"bik"`
+	AccountNumber        string `json:"accountNumber"`
+	CorrespondentAccount string `json:"correspondentAccount"`
+}
+
+// IBANEndpoint represents an international bank account payout payload.
+type IBANEndpoint struct {
+	IBAN          string `json:"iban"`
+	AccountHolder string `json:"accountHolder"`
+	BIC           string `json:"bic,omitempty"`
+	BankName      string `json:"bankName,omitempty"`
+}
+
+// LegacyPaymentEndpoint mirrors the previous bag-of-pointers DTO for backward compatibility.
+type LegacyPaymentEndpoint struct {
+	Ledger        *LedgerEndpoint        `json:"ledger,omitempty"`
+	ManagedWallet *ManagedWalletEndpoint `json:"managed_wallet,omitempty"`
+	ExternalChain *ExternalChainEndpoint `json:"external_chain,omitempty"`
+	Card          *CardEndpoint          `json:"card,omitempty"`
+	Metadata      map[string]string      `json:"metadata,omitempty"`
+}

api/edge/bff/interface/api/srequest/endpoint_union.go

@@ -0,0 +1,266 @@
+package srequest
+
+import (
+	"encoding/json"
+
+	"github.com/tech/sendico/pkg/merrors"
+)
+
+type EndpointType string
+
+const (
+	EndpointTypeLedger        EndpointType = "ledger"
+	EndpointTypeManagedWallet EndpointType = "managedWallet"
+	EndpointTypeExternalChain EndpointType = "cryptoAddress"
+	EndpointTypeCard          EndpointType = "card"
+	EndpointTypeCardToken     EndpointType = "cardToken"
+	EndpointTypeWallet        EndpointType = "wallet"
+	EndpointTypeBankAccount   EndpointType = "bankAccount"
+	EndpointTypeIBAN          EndpointType = "iban"
+)
+
+// Endpoint is a discriminated union for payment endpoints.
+type Endpoint struct {
+	Type     EndpointType      `json:"type"`
+	Data     json.RawMessage   `json:"data"`
+	Metadata map[string]string `json:"metadata,omitempty"`
+}
+
+func newEndpoint(kind EndpointType, payload interface{}, metadata map[string]string) (Endpoint, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return Endpoint{}, merrors.Internal("marshal endpoint payload failed")
+	}
+	return Endpoint{
+		Type:     kind,
+		Data:     data,
+		Metadata: cloneStringMap(metadata),
+	}, nil
+}
+
+func (e Endpoint) decodePayload(expected EndpointType, dst interface{}) error {
+	actual := normalizeEndpointType(e.Type)
+	if actual == "" {
+		return merrors.InvalidArgument("endpoint type is required")
+	}
+	if actual != expected {
+		return merrors.InvalidArgument("expected endpoint type " + string(expected) + ", got " + string(e.Type))
+	}
+	if len(e.Data) == 0 {
+		return merrors.InvalidArgument("endpoint data is required for type " + string(expected))
+	}
+	if err := json.Unmarshal(e.Data, dst); err != nil {
+		return merrors.InvalidArgument("decode " + string(expected) + " endpoint: " + err.Error())
+	}
+	return nil
+}
+
+func (e *Endpoint) UnmarshalJSON(data []byte) error {
+	var envelope struct {
+		Type     EndpointType      `json:"type"`
+		Data     json.RawMessage   `json:"data"`
+		Metadata map[string]string `json:"metadata"`
+	}
+	if err := json.Unmarshal(data, &envelope); err == nil {
+		if envelope.Type != "" || len(envelope.Data) > 0 {
+			if envelope.Type == "" {
+				return merrors.InvalidArgument("endpoint type is required")
+			}
+			*e = Endpoint{
+				Type:     normalizeEndpointType(envelope.Type),
+				Data:     envelope.Data,
+				Metadata: cloneStringMap(envelope.Metadata),
+			}
+			return nil
+		}
+	}
+
+	var legacy LegacyPaymentEndpoint
+	if err := json.Unmarshal(data, &legacy); err != nil {
+		return err
+	}
+	endpoint, err := LegacyPaymentEndpointToEndpointDTO(&legacy)
+	if err != nil {
+		return err
+	}
+	if endpoint == nil {
+		return merrors.InvalidArgument("endpoint payload is empty")
+	}
+	*e = *endpoint
+	return nil
+}
+
+func NewLedgerEndpointDTO(payload LedgerEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeLedger, payload, metadata)
+}
+
+func NewManagedWalletEndpointDTO(payload ManagedWalletEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeManagedWallet, payload, metadata)
+}
+
+func NewExternalChainEndpointDTO(payload ExternalChainEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeExternalChain, payload, metadata)
+}
+
+func NewCardEndpointDTO(payload CardEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeCard, payload, metadata)
+}
+
+func NewCardTokenEndpointDTO(payload CardTokenEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeCardToken, payload, metadata)
+}
+
+func NewWalletEndpointDTO(payload WalletEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeWallet, payload, metadata)
+}
+
+func NewBankAccountEndpointDTO(payload BankAccountEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeBankAccount, payload, metadata)
+}
+
+func NewIBANEndpointDTO(payload IBANEndpoint, metadata map[string]string) (Endpoint, error) {
+	return newEndpoint(EndpointTypeIBAN, payload, metadata)
+}
+
+func (e Endpoint) DecodeLedger() (LedgerEndpoint, error) {
+	var payload LedgerEndpoint
+	return payload, e.decodePayload(EndpointTypeLedger, &payload)
+}
+
+func (e Endpoint) DecodeManagedWallet() (ManagedWalletEndpoint, error) {
+	var payload ManagedWalletEndpoint
+	return payload, e.decodePayload(EndpointTypeManagedWallet, &payload)
+}
+
+func (e Endpoint) DecodeExternalChain() (ExternalChainEndpoint, error) {
+	var payload ExternalChainEndpoint
+	return payload, e.decodePayload(EndpointTypeExternalChain, &payload)
+}
+
+func (e Endpoint) DecodeCard() (CardEndpoint, error) {
+	var payload CardEndpoint
+	return payload, e.decodePayload(EndpointTypeCard, &payload)
+}
+
+func (e Endpoint) DecodeCardToken() (CardTokenEndpoint, error) {
+	var payload CardTokenEndpoint
+	return payload, e.decodePayload(EndpointTypeCardToken, &payload)
+}
+
+func (e Endpoint) DecodeWallet() (WalletEndpoint, error) {
+	var payload WalletEndpoint
+	return payload, e.decodePayload(EndpointTypeWallet, &payload)
+}
+
+func (e Endpoint) DecodeBankAccount() (BankAccountEndpoint, error) {
+	var payload BankAccountEndpoint
+	return payload, e.decodePayload(EndpointTypeBankAccount, &payload)
+}
+
+func (e Endpoint) DecodeIBAN() (IBANEndpoint, error) {
+	var payload IBANEndpoint
+	return payload, e.decodePayload(EndpointTypeIBAN, &payload)
+}
+
+func LegacyPaymentEndpointToEndpointDTO(old *LegacyPaymentEndpoint) (*Endpoint, error) {
+	if old == nil {
+		return nil, nil
+	}
+
+	count := 0
+	var endpoint Endpoint
+	var err error
+
+	if old.Ledger != nil {
+		count++
+		endpoint, err = NewLedgerEndpointDTO(*old.Ledger, old.Metadata)
+	}
+	if old.ManagedWallet != nil {
+		count++
+		endpoint, err = NewManagedWalletEndpointDTO(*old.ManagedWallet, old.Metadata)
+	}
+	if old.ExternalChain != nil {
+		count++
+		endpoint, err = NewExternalChainEndpointDTO(*old.ExternalChain, old.Metadata)
+	}
+	if old.Card != nil {
+		count++
+		endpoint, err = NewCardEndpointDTO(*old.Card, old.Metadata)
+	}
+
+	if err != nil {
+		return nil, err
+	}
+	if count == 0 {
+		return nil, merrors.InvalidArgument("exactly one endpoint must be set")
+	}
+	if count > 1 {
+		return nil, merrors.InvalidArgument("only one endpoint can be set")
+	}
+	return &endpoint, nil
+}
+
+func EndpointDTOToLegacyPaymentEndpoint(new *Endpoint) (*LegacyPaymentEndpoint, error) {
+	if new == nil {
+		return nil, nil
+	}
+
+	legacy := &LegacyPaymentEndpoint{
+		Metadata: cloneStringMap(new.Metadata),
+	}
+
+	switch normalizeEndpointType(new.Type) {
+	case EndpointTypeLedger:
+		payload, err := new.DecodeLedger()
+		if err != nil {
+			return nil, err
+		}
+		legacy.Ledger = &payload
+	case EndpointTypeManagedWallet:
+		payload, err := new.DecodeManagedWallet()
+		if err != nil {
+			return nil, err
+		}
+		legacy.ManagedWallet = &payload
+	case EndpointTypeExternalChain:
+		payload, err := new.DecodeExternalChain()
+		if err != nil {
+			return nil, err
+		}
+		legacy.ExternalChain = &payload
+	case EndpointTypeCard:
+		payload, err := new.DecodeCard()
+		if err != nil {
+			return nil, err
+		}
+		legacy.Card = &payload
+	default:
+		return nil, merrors.InvalidArgument("unsupported endpoint type: " + string(new.Type))
+	}
+	return legacy, nil
+}
+
+var endpointTypeAliases = map[EndpointType]EndpointType{
+	"managed_wallet": EndpointTypeManagedWallet,
+	"external_chain": EndpointTypeExternalChain,
+	"card_token":     EndpointTypeCardToken,
+	"bank_account":   EndpointTypeBankAccount,
+}
+
+func normalizeEndpointType(t EndpointType) EndpointType {
+	if canonical, ok := endpointTypeAliases[t]; ok {
+		return canonical
+	}
+	return t
+}
+
+func cloneStringMap(src map[string]string) map[string]string {
+	if len(src) == 0 {
+		return nil
+	}
+	dst := make(map[string]string, len(src))
+	for k, v := range src {
+		dst[k] = v
+	}
+	return dst
+}

api/edge/bff/interface/api/srequest/file.go

@@ -0,0 +1,7 @@
+package srequest
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type FileUpload struct {
+	ObjRef bson.ObjectID `json:"objRef"`
+}

api/edge/bff/interface/api/srequest/invitation.go

@@ -0,0 +1,7 @@
+package srequest
+
+import (
+	"github.com/tech/sendico/pkg/model"
+)
+
+type CreateInvitation = model.Invitation

api/edge/bff/interface/api/srequest/ledger.go

@@ -0,0 +1,54 @@
+package srequest
+
+import (
+	"strings"
+
+	"github.com/tech/sendico/pkg/ledgerconv"
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/model"
+	"github.com/tech/sendico/pkg/model/account_role"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type LedgerAccountType string
+
+const (
+	LedgerAccountTypeUnspecified LedgerAccountType = "unspecified"
+	LedgerAccountTypeAsset       LedgerAccountType = "asset"
+	LedgerAccountTypeLiability   LedgerAccountType = "liability"
+	LedgerAccountTypeRevenue     LedgerAccountType = "revenue"
+	LedgerAccountTypeExpense     LedgerAccountType = "expense"
+)
+
+type LedgerAccountStatus string
+
+const (
+	LedgerAccountStatusUnspecified LedgerAccountStatus = "unspecified"
+	LedgerAccountStatusActive      LedgerAccountStatus = "active"
+	LedgerAccountStatusFrozen      LedgerAccountStatus = "frozen"
+)
+
+type CreateLedgerAccount struct {
+	AccountType   LedgerAccountType        `json:"accountType"`
+	Currency      string                   `json:"currency"`
+	AllowNegative bool                     `json:"allowNegative,omitempty"`
+	Role          account_role.AccountRole `json:"role"`
+	Describable   model.Describable        `json:"describable"`
+	OwnerRef      *bson.ObjectID           `json:"ownerRef,omitempty"`
+	Metadata      map[string]string        `json:"metadata,omitempty"`
+}
+
+func (r *CreateLedgerAccount) Validate() error {
+	if strings.TrimSpace(r.Currency) == "" {
+		return merrors.InvalidArgument("currency is required", "currency")
+	}
+	if strings.TrimSpace(string(r.AccountType)) == "" || strings.EqualFold(string(r.AccountType), string(LedgerAccountTypeUnspecified)) {
+		return merrors.InvalidArgument("accountType is required", "accountType")
+	}
+	if role := strings.TrimSpace(string(r.Role)); role != "" {
+		if _, ok := ledgerconv.ParseAccountRole(role); !ok || ledgerconv.IsAccountRoleUnspecified(role) {
+			return merrors.InvalidArgument("role is invalid", "role")
+		}
+	}
+	return nil
+}

api/edge/bff/interface/api/srequest/login.go

@@ -0,0 +1,8 @@
+package srequest
+
+import "github.com/tech/sendico/pkg/model"
+
+type Login struct {
+	model.SessionIdentifier `json:",inline"`
+	model.LoginData         `json:"login"`
+}

api/edge/bff/interface/api/srequest/password.go

@@ -0,0 +1,15 @@
+package srequest
+
+type ChangePassword struct {
+	Old      string `json:"old"`
+	New      string `json:"new"`
+	DeviceID string `json:"deviceId"`
+}
+
+type ResetPassword struct {
+	Password string `json:"password"`
+}
+
+type ForgotPassword struct {
+	Login string `json:"login"`
+}

api/edge/bff/interface/api/srequest/payment.go

@@ -0,0 +1,126 @@
+package srequest
+
+import (
+	"strings"
+
+	"github.com/tech/sendico/pkg/merrors"
+)
+
+type PaymentBase struct {
+	IdempotencyKey string            `json:"idempotencyKey"`
+	Metadata       map[string]string `json:"metadata,omitempty"`
+}
+
+func (b *PaymentBase) Validate() error {
+	if b.IdempotencyKey == "" {
+		return merrors.InvalidArgument("idempotencyKey is required", "idempotencyKey")
+	}
+	return nil
+}
+
+type QuotePayment struct {
+	PaymentBase `json:",inline"`
+	Intent      PaymentIntent `json:"intent"`
+	PreviewOnly bool          `json:"previewOnly"`
+}
+
+func (r *QuotePayment) Validate() error {
+	if err := validateQuoteIdempotency(r.PreviewOnly, r.IdempotencyKey); err != nil {
+		return err
+	}
+
+	// intent is mandatory, so validate always
+	if err := r.Intent.Validate(); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+type QuotePayments struct {
+	PaymentBase `json:",inline"`
+	Intents     []PaymentIntent `json:"intents"`
+	PreviewOnly bool            `json:"previewOnly"`
+}
+
+func (r *QuotePayments) Validate() error {
+	if err := validateQuoteIdempotency(r.PreviewOnly, r.IdempotencyKey); err != nil {
+		return err
+	}
+	if len(r.Intents) == 0 {
+		return merrors.InvalidArgument("intents are required", "intents")
+	}
+	for i := range r.Intents {
+		if err := r.Intents[i].Validate(); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+func validateQuoteIdempotency(previewOnly bool, idempotencyKey string) error {
+	key := strings.TrimSpace(idempotencyKey)
+	if previewOnly {
+		if key != "" {
+			return merrors.InvalidArgument("previewOnly requests must not include idempotencyKey", "idempotencyKey")
+		}
+		return nil
+	}
+	if key == "" {
+		return merrors.InvalidArgument("idempotencyKey is required", "idempotencyKey")
+	}
+	return nil
+}
+
+type InitiatePayment struct {
+	PaymentBase `json:",inline"`
+	Intent      *PaymentIntent `json:"intent,omitempty"`
+	QuoteRef    string         `json:"quoteRef,omitempty"`
+}
+
+func (r InitiatePayment) Validate() error {
+	// base checks
+	if err := r.PaymentBase.Validate(); err != nil {
+		return err
+	}
+
+	hasIntent := r.Intent != nil
+	hasQuote := r.QuoteRef != ""
+
+	// must be exactly one
+	switch {
+	case !hasIntent && !hasQuote:
+		return merrors.NoData("either intent or quoteRef must be provided")
+	case hasIntent && hasQuote:
+		return merrors.DataConflict("intent and quoteRef are mutually exclusive")
+	}
+
+	// if intent provided → validate it
+	if hasIntent {
+		if err := r.Intent.Validate(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}
+
+type InitiatePayments struct {
+	PaymentBase `json:",inline"`
+	QuoteRef    string `json:"quoteRef,omitempty"`
+}
+
+func (r *InitiatePayments) Validate() error {
+	if r == nil {
+		return merrors.InvalidArgument("request is required")
+	}
+	if err := r.PaymentBase.Validate(); err != nil {
+		return err
+	}
+	r.QuoteRef = strings.TrimSpace(r.QuoteRef)
+
+	if r.QuoteRef == "" {
+		return merrors.InvalidArgument("quoteRef is required", "quoteRef")
+	}
+	return nil
+}

api/edge/bff/interface/api/srequest/payment_enums.go

@@ -0,0 +1,60 @@
+package srequest
+
+// PaymentKind mirrors the orchestrator payment kinds without importing generated proto types.
+// Strings keep JSON readable; conversion helpers map these to proto enums.
+type PaymentKind string
+
+const (
+	PaymentKindUnspecified      PaymentKind = "unspecified"
+	PaymentKindPayout           PaymentKind = "payout"
+	PaymentKindInternalTransfer PaymentKind = "internal_transfer"
+	PaymentKindFxConversion     PaymentKind = "fx_conversion"
+)
+
+// SettlementMode matches orchestrator settlement behavior.
+type SettlementMode string
+
+const (
+	SettlementModeUnspecified SettlementMode = "unspecified"
+	SettlementModeFixSource   SettlementMode = "fix_source"
+	SettlementModeFixReceived SettlementMode = "fix_received"
+)
+
+// FeeTreatment controls where fee impact is applied by quotation.
+type FeeTreatment string
+
+const (
+	FeeTreatmentUnspecified           FeeTreatment = "unspecified"
+	FeeTreatmentAddToSource           FeeTreatment = "add_to_source"
+	FeeTreatmentDeductFromDestination FeeTreatment = "deduct_from_destination"
+)
+
+// FXSide mirrors the common FX side enum.
+type FXSide string
+
+const (
+	FXSideUnspecified      FXSide = "unspecified"
+	FXSideBuyBaseSellQuote FXSide = "buy_base_sell_quote"
+	FXSideSellBaseBuyQuote FXSide = "sell_base_buy_quote"
+)
+
+// ChainNetwork mirrors the chain network enum used by managed wallets.
+type ChainNetwork string
+
+const (
+	ChainNetworkUnspecified     ChainNetwork = "unspecified"
+	ChainNetworkEthereumMainnet ChainNetwork = "ethereum_mainnet"
+	ChainNetworkArbitrumOne     ChainNetwork = "arbitrum_one"
+	ChainNetworkTronMainnet     ChainNetwork = "tron_mainnet"
+	ChainNetworkTronNile        ChainNetwork = "tron_nile"
+)
+
+// InsufficientNetPolicy mirrors the fee engine policy override.
+type InsufficientNetPolicy string
+
+const (
+	InsufficientNetPolicyUnspecified  InsufficientNetPolicy = "unspecified"
+	InsufficientNetPolicyBlockPosting InsufficientNetPolicy = "block_posting"
+	InsufficientNetPolicySweepOrgCash InsufficientNetPolicy = "sweep_org_cash"
+	InsufficientNetPolicyInvoiceLater InsufficientNetPolicy = "invoice_later"
+)

api/edge/bff/interface/api/srequest/payment_intent.go

@@ -0,0 +1,56 @@
+package srequest
+
+import (
+	"github.com/tech/sendico/pkg/merrors"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+)
+
+type PaymentIntent struct {
+	Kind           PaymentKind         `json:"kind,omitempty"`
+	Source         *Endpoint           `json:"source,omitempty"`
+	Destination    *Endpoint           `json:"destination,omitempty"`
+	Amount         *paymenttypes.Money `json:"amount,omitempty"`
+	FX             *FXIntent           `json:"fx,omitempty"`
+	SettlementMode SettlementMode      `json:"settlement_mode,omitempty"`
+	FeeTreatment   FeeTreatment        `json:"fee_treatment,omitempty"`
+	Attributes     map[string]string   `json:"attributes,omitempty"`
+	Customer       *Customer           `json:"customer,omitempty"`
+}
+
+type AssetResolverStub struct{}
+
+func (a *AssetResolverStub) IsSupported(_ string) bool {
+	return true
+}
+
+func (p *PaymentIntent) Validate() error {
+	// Kind must be set (non-zero)
+	var zeroKind PaymentKind
+	if p.Kind == zeroKind {
+		return merrors.InvalidArgument("kind is required", "intent.kind")
+	}
+
+	if p.Source == nil {
+		return merrors.InvalidArgument("source is required", "intent.source")
+	}
+
+	if p.Destination == nil {
+		return merrors.InvalidArgument("destination is required", "intent.destination")
+	}
+
+	if p.Amount == nil {
+		return merrors.InvalidArgument("amount is required", "intent.amount")
+	}
+	//TODO: collect supported currencies and validate against them
+	if err := ValidateMoney(p.Amount, &AssetResolverStub{}); err != nil {
+		return err
+	}
+
+	if p.FX != nil {
+		if err := p.FX.Validate(); err != nil {
+			return err
+		}
+	}
+
+	return nil
+}

api/edge/bff/interface/api/srequest/payment_intent_validate_test.go

@@ -0,0 +1,84 @@
+package srequest
+
+import (
+	"testing"
+
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+)
+
+func TestPaymentIntentValidate_AcceptsBaseIntentWithoutFX(t *testing.T) {
+	intent := mustValidBaseIntent(t)
+
+	if err := intent.Validate(); err != nil {
+		t.Fatalf("unexpected validation error: %v", err)
+	}
+}
+
+func TestPaymentIntentValidate_RejectsFXWithoutPair(t *testing.T) {
+	intent := mustValidBaseIntent(t)
+	intent.FX = &FXIntent{
+		Side: FXSideSellBaseBuyQuote,
+	}
+
+	if err := intent.Validate(); err == nil {
+		t.Fatalf("expected validation error for missing fx pair")
+	}
+}
+
+func TestPaymentIntentValidate_RejectsInvalidFXSide(t *testing.T) {
+	intent := mustValidBaseIntent(t)
+	intent.FX = &FXIntent{
+		Pair: &CurrencyPair{
+			Base:  "USDT",
+			Quote: "RUB",
+		},
+		Side: FXSide("wrong"),
+	}
+
+	if err := intent.Validate(); err == nil {
+		t.Fatalf("expected validation error for invalid fx side")
+	}
+}
+
+func TestPaymentIntentValidate_AcceptsValidFX(t *testing.T) {
+	intent := mustValidBaseIntent(t)
+	intent.FX = &FXIntent{
+		Pair: &CurrencyPair{
+			Base:  "USDT",
+			Quote: "RUB",
+		},
+		Side: FXSideSellBaseBuyQuote,
+	}
+
+	if err := intent.Validate(); err != nil {
+		t.Fatalf("unexpected validation error: %v", err)
+	}
+}
+
+func mustValidBaseIntent(t *testing.T) *PaymentIntent {
+	t.Helper()
+
+	source, err := NewManagedWalletEndpointDTO(ManagedWalletEndpoint{ManagedWalletRef: "mw-src"}, nil)
+	if err != nil {
+		t.Fatalf("build source endpoint: %v", err)
+	}
+	destination, err := NewCardEndpointDTO(CardEndpoint{
+		Pan:       "2200700142860161",
+		FirstName: "Jane",
+		LastName:  "Doe",
+		ExpMonth:  2,
+		ExpYear:   2030,
+	}, nil)
+	if err != nil {
+		t.Fatalf("build destination endpoint: %v", err)
+	}
+
+	return &PaymentIntent{
+		Kind:           PaymentKindPayout,
+		Source:         &source,
+		Destination:    &destination,
+		Amount:         &paymenttypes.Money{Amount: "10", Currency: "USDT"},
+		SettlementMode: SettlementModeFixSource,
+		FeeTreatment:   FeeTreatmentAddToSource,
+	}
+}

api/edge/bff/interface/api/srequest/payment_types_test.go

@@ -0,0 +1,427 @@
+package srequest
+
+import (
+	"encoding/json"
+	"reflect"
+	"strings"
+	"testing"
+
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+)
+
+func TestEndpointDTOBuildersAndDecoders(t *testing.T) {
+	meta := map[string]string{"note": "meta"}
+
+	t.Run("ledger", func(t *testing.T) {
+		payload := LedgerEndpoint{LedgerAccountRef: "acc-1", ContraLedgerAccountRef: "contra-1"}
+		endpoint, err := NewLedgerEndpointDTO(payload, meta)
+		if err != nil {
+			t.Fatalf("build ledger endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeLedger {
+			t.Fatalf("expected type %s got %s", EndpointTypeLedger, endpoint.Type)
+		}
+		if string(endpoint.Data) != `{"ledger_account_ref":"acc-1","contra_ledger_account_ref":"contra-1"}` {
+			t.Fatalf("unexpected data: %s", endpoint.Data)
+		}
+		decoded, err := endpoint.DecodeLedger()
+		if err != nil {
+			t.Fatalf("decode ledger: %v", err)
+		}
+		if decoded != payload {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+		meta["note"] = "changed"
+		if endpoint.Metadata["note"] != "meta" {
+			t.Fatalf("metadata should be copied, got %s", endpoint.Metadata["note"])
+		}
+	})
+
+	t.Run("managed wallet", func(t *testing.T) {
+		payload := ManagedWalletEndpoint{
+			ManagedWalletRef: "mw-1",
+			Asset: &Asset{
+				Chain:           ChainNetworkArbitrumOne,
+				TokenSymbol:     "USDC",
+				ContractAddress: "0xabc",
+			},
+		}
+		endpoint, err := NewManagedWalletEndpointDTO(payload, nil)
+		if err != nil {
+			t.Fatalf("build managed wallet endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeManagedWallet {
+			t.Fatalf("expected type %s got %s", EndpointTypeManagedWallet, endpoint.Type)
+		}
+		decoded, err := endpoint.DecodeManagedWallet()
+		if err != nil {
+			t.Fatalf("decode managed wallet: %v", err)
+		}
+		if !reflect.DeepEqual(decoded, payload) {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+	})
+
+	t.Run("external chain", func(t *testing.T) {
+		payload := ExternalChainEndpoint{
+			Asset: &Asset{
+				Chain:       ChainNetworkEthereumMainnet,
+				TokenSymbol: "ETH",
+			},
+			Address: "0x123",
+			Memo:    "memo",
+		}
+		endpoint, err := NewExternalChainEndpointDTO(payload, nil)
+		if err != nil {
+			t.Fatalf("build external chain endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeExternalChain {
+			t.Fatalf("expected type %s got %s", EndpointTypeExternalChain, endpoint.Type)
+		}
+		decoded, err := endpoint.DecodeExternalChain()
+		if err != nil {
+			t.Fatalf("decode external chain: %v", err)
+		}
+		if !reflect.DeepEqual(decoded, payload) {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+	})
+
+	t.Run("card", func(t *testing.T) {
+		payload := CardEndpoint{
+			Pan:       "pan",
+			FirstName: "Jane",
+			LastName:  "Doe",
+			ExpMonth:  12,
+			ExpYear:   2030,
+			Country:   "US",
+		}
+		endpoint, err := NewCardEndpointDTO(payload, map[string]string{"k": "v"})
+		if err != nil {
+			t.Fatalf("build card endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeCard {
+			t.Fatalf("expected type %s got %s", EndpointTypeCard, endpoint.Type)
+		}
+		decoded, err := endpoint.DecodeCard()
+		if err != nil {
+			t.Fatalf("decode card: %v", err)
+		}
+		if !reflect.DeepEqual(decoded, payload) {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+		if endpoint.Metadata["k"] != "v" {
+			t.Fatalf("expected metadata copy, got %s", endpoint.Metadata["k"])
+		}
+	})
+
+	t.Run("card token", func(t *testing.T) {
+		payload := CardTokenEndpoint{Token: "token", MaskedPan: "****1234"}
+		endpoint, err := NewCardTokenEndpointDTO(payload, nil)
+		if err != nil {
+			t.Fatalf("build card token endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeCardToken {
+			t.Fatalf("expected type %s got %s", EndpointTypeCardToken, endpoint.Type)
+		}
+		decoded, err := endpoint.DecodeCardToken()
+		if err != nil {
+			t.Fatalf("decode card token: %v", err)
+		}
+		if !reflect.DeepEqual(decoded, payload) {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+	})
+
+	t.Run("wallet", func(t *testing.T) {
+		payload := WalletEndpoint{WalletID: "wallet-1"}
+		endpoint, err := NewWalletEndpointDTO(payload, nil)
+		if err != nil {
+			t.Fatalf("build wallet endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeWallet {
+			t.Fatalf("expected type %s got %s", EndpointTypeWallet, endpoint.Type)
+		}
+		decoded, err := endpoint.DecodeWallet()
+		if err != nil {
+			t.Fatalf("decode wallet: %v", err)
+		}
+		if decoded != payload {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+	})
+
+	t.Run("bank account", func(t *testing.T) {
+		payload := BankAccountEndpoint{
+			RecipientName:        "ACME",
+			Inn:                  "inn",
+			Kpp:                  "kpp",
+			BankName:             "bank",
+			Bik:                  "bik",
+			AccountNumber:        "123",
+			CorrespondentAccount: "456",
+		}
+		endpoint, err := NewBankAccountEndpointDTO(payload, map[string]string{"note": "n"})
+		if err != nil {
+			t.Fatalf("build bank account endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeBankAccount {
+			t.Fatalf("expected type %s got %s", EndpointTypeBankAccount, endpoint.Type)
+		}
+		decoded, err := endpoint.DecodeBankAccount()
+		if err != nil {
+			t.Fatalf("decode bank account: %v", err)
+		}
+		if !reflect.DeepEqual(decoded, payload) {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+		if endpoint.Metadata["note"] != "n" {
+			t.Fatalf("expected metadata copy, got %s", endpoint.Metadata["note"])
+		}
+	})
+
+	t.Run("iban", func(t *testing.T) {
+		payload := IBANEndpoint{
+			IBAN:          "DE123",
+			AccountHolder: "John Doe",
+			BIC:           "BICCODE",
+			BankName:      "BankName",
+		}
+		endpoint, err := NewIBANEndpointDTO(payload, nil)
+		if err != nil {
+			t.Fatalf("build iban endpoint: %v", err)
+		}
+		if endpoint.Type != EndpointTypeIBAN {
+			t.Fatalf("expected type %s got %s", EndpointTypeIBAN, endpoint.Type)
+		}
+		decoded, err := endpoint.DecodeIBAN()
+		if err != nil {
+			t.Fatalf("decode iban: %v", err)
+		}
+		if !reflect.DeepEqual(decoded, payload) {
+			t.Fatalf("decoded payload mismatch: %#v vs %#v", decoded, payload)
+		}
+	})
+
+	t.Run("type mismatch", func(t *testing.T) {
+		endpoint, err := NewLedgerEndpointDTO(LedgerEndpoint{LedgerAccountRef: "acc"}, nil)
+		if err != nil {
+			t.Fatalf("build ledger endpoint: %v", err)
+		}
+		if _, err := endpoint.DecodeCard(); err == nil || !strings.Contains(err.Error(), "expected endpoint type") {
+			t.Fatalf("expected type mismatch error, got %v", err)
+		}
+	})
+
+	t.Run("invalid json data", func(t *testing.T) {
+		endpoint := Endpoint{Type: EndpointTypeLedger, Data: json.RawMessage("not-json")}
+		if _, err := endpoint.DecodeLedger(); err == nil {
+			t.Fatalf("expected decode error")
+		}
+	})
+
+	t.Run("legacy type alias normalizes", func(t *testing.T) {
+		raw := []byte(`{"type":"managed_wallet","data":{"managed_wallet_ref":"mw-legacy"}}`)
+		var endpoint Endpoint
+		if err := json.Unmarshal(raw, &endpoint); err != nil {
+			t.Fatalf("unmarshal with legacy type: %v", err)
+		}
+		if endpoint.Type != EndpointTypeManagedWallet {
+			t.Fatalf("expected normalized type %s got %s", EndpointTypeManagedWallet, endpoint.Type)
+		}
+		payload, err := endpoint.DecodeManagedWallet()
+		if err != nil {
+			t.Fatalf("decode managed wallet with alias: %v", err)
+		}
+		if payload.ManagedWalletRef != "mw-legacy" {
+			t.Fatalf("decoded payload mismatch from alias: %#v", payload)
+		}
+	})
+}
+
+func TestPaymentIntentJSONRoundTrip(t *testing.T) {
+	sourcePayload := LedgerEndpoint{LedgerAccountRef: "source"}
+	source, err := NewLedgerEndpointDTO(sourcePayload, map[string]string{"src": "meta"})
+	if err != nil {
+		t.Fatalf("build source endpoint: %v", err)
+	}
+	destPayload := ExternalChainEndpoint{Address: "0xabc", Asset: &Asset{Chain: ChainNetworkEthereumMainnet, TokenSymbol: "USDC"}}
+	dest, err := NewExternalChainEndpointDTO(destPayload, nil)
+	if err != nil {
+		t.Fatalf("build destination endpoint: %v", err)
+	}
+
+	intent := &PaymentIntent{
+		Kind:        PaymentKindPayout,
+		Source:      &source,
+		Destination: &dest,
+		Amount:      &paymenttypes.Money{Amount: "10", Currency: "USD"},
+		FX: &FXIntent{
+			Pair:              &CurrencyPair{Base: "USD", Quote: "EUR"},
+			Side:              FXSideBuyBaseSellQuote,
+			Firm:              true,
+			TTLms:             5000,
+			PreferredProvider: "provider",
+			MaxAgeMs:          10,
+		},
+		SettlementMode: SettlementModeFixReceived,
+		Attributes:     map[string]string{"k": "v"},
+	}
+
+	data, err := json.Marshal(intent)
+	if err != nil {
+		t.Fatalf("marshal intent: %v", err)
+	}
+	var decoded PaymentIntent
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("unmarshal intent: %v", err)
+	}
+
+	if decoded.Kind != intent.Kind || decoded.SettlementMode != intent.SettlementMode {
+		t.Fatalf("scalar fields changed after round trip")
+	}
+	if decoded.Amount == nil || *decoded.Amount != *intent.Amount {
+		t.Fatalf("amount mismatch after round trip")
+	}
+	if decoded.FX == nil || decoded.FX.PreferredProvider != intent.FX.PreferredProvider {
+		t.Fatalf("fx mismatch after round trip")
+	}
+	if decoded.Source == nil || decoded.Destination == nil {
+		t.Fatalf("source/destination missing after round trip")
+	}
+	sourceDecoded, err := decoded.Source.DecodeLedger()
+	if err != nil {
+		t.Fatalf("decode source after round trip: %v", err)
+	}
+	if sourceDecoded != sourcePayload {
+		t.Fatalf("source payload mismatch after round trip: %#v vs %#v", sourceDecoded, sourcePayload)
+	}
+	destDecoded, err := decoded.Destination.DecodeExternalChain()
+	if err != nil {
+		t.Fatalf("decode destination after round trip: %v", err)
+	}
+	if !reflect.DeepEqual(destDecoded, destPayload) {
+		t.Fatalf("destination payload mismatch after round trip: %#v vs %#v", destDecoded, destPayload)
+	}
+	if decoded.Attributes["k"] != "v" {
+		t.Fatalf("attributes mismatch after round trip")
+	}
+}
+
+func TestPaymentIntentMinimalRoundTrip(t *testing.T) {
+	sourcePayload := ManagedWalletEndpoint{ManagedWalletRef: "mw"}
+	source, err := NewManagedWalletEndpointDTO(sourcePayload, nil)
+	if err != nil {
+		t.Fatalf("build source endpoint: %v", err)
+	}
+	destPayload := LedgerEndpoint{LedgerAccountRef: "dest-ledger"}
+	dest, err := NewLedgerEndpointDTO(destPayload, nil)
+	if err != nil {
+		t.Fatalf("build destination endpoint: %v", err)
+	}
+
+	intent := &PaymentIntent{
+		Kind:        PaymentKindInternalTransfer,
+		Source:      &source,
+		Destination: &dest,
+		Amount:      &paymenttypes.Money{Amount: "1", Currency: "USD"},
+	}
+
+	data, err := json.Marshal(intent)
+	if err != nil {
+		t.Fatalf("marshal intent: %v", err)
+	}
+	var decoded PaymentIntent
+	if err := json.Unmarshal(data, &decoded); err != nil {
+		t.Fatalf("unmarshal intent: %v", err)
+	}
+
+	if decoded.Kind != intent.Kind || decoded.FX != nil {
+		t.Fatalf("unexpected fx data in minimal intent: %#v", decoded)
+	}
+	if decoded.Amount == nil || *decoded.Amount != *intent.Amount {
+		t.Fatalf("amount mismatch after round trip")
+	}
+	if decoded.Source == nil || decoded.Destination == nil {
+		t.Fatalf("endpoints missing after round trip")
+	}
+	sourceDecoded, err := decoded.Source.DecodeManagedWallet()
+	if err != nil {
+		t.Fatalf("decode source: %v", err)
+	}
+	if !reflect.DeepEqual(sourceDecoded, sourcePayload) {
+		t.Fatalf("source payload mismatch: %#v vs %#v", sourceDecoded, sourcePayload)
+	}
+	destDecoded, err := decoded.Destination.DecodeLedger()
+	if err != nil {
+		t.Fatalf("decode destination: %v", err)
+	}
+	if destDecoded != destPayload {
+		t.Fatalf("destination payload mismatch: %#v vs %#v", destDecoded, destPayload)
+	}
+}
+
+func TestLegacyEndpointRoundTrip(t *testing.T) {
+	legacy := &LegacyPaymentEndpoint{
+		ExternalChain: &ExternalChainEndpoint{
+			Asset:   &Asset{Chain: ChainNetworkEthereumMainnet, TokenSymbol: "DAI", ContractAddress: "0xdef"},
+			Address: "0x123",
+			Memo:    "memo",
+		},
+		Metadata: map[string]string{"note": "legacy"},
+	}
+
+	endpoint, err := LegacyPaymentEndpointToEndpointDTO(legacy)
+	if err != nil {
+		t.Fatalf("convert legacy to dto: %v", err)
+	}
+	if endpoint == nil || endpoint.Type != EndpointTypeExternalChain {
+		t.Fatalf("unexpected endpoint result: %#v", endpoint)
+	}
+	legacy.Metadata["note"] = "changed"
+	if endpoint.Metadata["note"] != "legacy" {
+		t.Fatalf("metadata should be copied from legacy")
+	}
+
+	roundTrip, err := EndpointDTOToLegacyPaymentEndpoint(endpoint)
+	if err != nil {
+		t.Fatalf("convert dto back to legacy: %v", err)
+	}
+	if roundTrip == nil || roundTrip.ExternalChain == nil {
+		t.Fatalf("round trip legacy missing payload: %#v", roundTrip)
+	}
+	if !reflect.DeepEqual(roundTrip.ExternalChain, legacy.ExternalChain) {
+		t.Fatalf("round trip payload mismatch: %#v vs %#v", roundTrip.ExternalChain, legacy.ExternalChain)
+	}
+	if roundTrip.Metadata["note"] != "legacy" {
+		t.Fatalf("metadata mismatch after round trip: %v", roundTrip.Metadata)
+	}
+}
+
+func TestLegacyEndpointConversionRejectsMultiple(t *testing.T) {
+	_, err := LegacyPaymentEndpointToEndpointDTO(&LegacyPaymentEndpoint{
+		Ledger: &LedgerEndpoint{LedgerAccountRef: "a"},
+		Card:   &CardEndpoint{Pan: "t"},
+	})
+	if err == nil {
+		t.Fatalf("expected error when multiple legacy endpoints are set")
+	}
+}
+
+func TestEndpointUnmarshalLegacyShape(t *testing.T) {
+	raw := []byte(`{"ledger":{"ledger_account_ref":"abc"}}`)
+	var endpoint Endpoint
+	if err := json.Unmarshal(raw, &endpoint); err != nil {
+		t.Fatalf("unmarshal legacy shape: %v", err)
+	}
+	if endpoint.Type != EndpointTypeLedger {
+		t.Fatalf("expected type %s got %s", EndpointTypeLedger, endpoint.Type)
+	}
+	payload, err := endpoint.DecodeLedger()
+	if err != nil {
+		t.Fatalf("decode ledger from legacy shape: %v", err)
+	}
+	if payload.LedgerAccountRef != "abc" {
+		t.Fatalf("unexpected payload from legacy shape: %#v", payload)
+	}
+}

api/edge/bff/interface/api/srequest/payment_validate_test.go

@@ -0,0 +1,53 @@
+package srequest
+
+import "testing"
+
+func TestValidateQuoteIdempotency(t *testing.T) {
+	t.Run("non-preview requires idempotency key", func(t *testing.T) {
+		if err := validateQuoteIdempotency(false, ""); err == nil {
+			t.Fatalf("expected error for empty idempotency key")
+		}
+	})
+
+	t.Run("preview rejects idempotency key", func(t *testing.T) {
+		if err := validateQuoteIdempotency(true, "idem-1"); err == nil {
+			t.Fatalf("expected error when preview request has idempotency key")
+		}
+	})
+
+	t.Run("preview accepts empty idempotency key", func(t *testing.T) {
+		if err := validateQuoteIdempotency(true, ""); err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+	})
+
+	t.Run("non-preview accepts idempotency key", func(t *testing.T) {
+		if err := validateQuoteIdempotency(false, "idem-1"); err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+	})
+}
+
+func TestInitiatePaymentsValidate(t *testing.T) {
+	t.Run("accepts quoteRef", func(t *testing.T) {
+		req := &InitiatePayments{
+			PaymentBase: PaymentBase{IdempotencyKey: "idem-1"},
+			QuoteRef:    " quote-1 ",
+		}
+		if err := req.Validate(); err != nil {
+			t.Fatalf("expected no error, got %v", err)
+		}
+		if got, want := req.QuoteRef, "quote-1"; got != want {
+			t.Fatalf("quoteRef mismatch: got=%q want=%q", got, want)
+		}
+	})
+
+	t.Run("rejects missing quoteRef", func(t *testing.T) {
+		req := &InitiatePayments{
+			PaymentBase: PaymentBase{IdempotencyKey: "idem-1"},
+		}
+		if err := req.Validate(); err == nil {
+			t.Fatal("expected error")
+		}
+	})
+}

api/edge/bff/interface/api/srequest/payment_value_objects.go

@@ -0,0 +1,133 @@
+package srequest
+
+import (
+	"regexp"
+	"strings"
+
+	"github.com/shopspring/decimal"
+	"github.com/tech/sendico/pkg/merrors"
+	paymenttypes "github.com/tech/sendico/pkg/payments/types"
+)
+
+// AssetResolver defines environment-specific supported assets.
+// Implementations should check:
+// - fiat assets (ISO-4217)
+// - crypto assets supported by gateways / FX providers
+type AssetResolver interface {
+	IsSupported(ticker string) bool
+}
+
+// Precompile regex for efficiency.
+var currencySyntax = regexp.MustCompile(`^[A-Z0-9]{2,10}$`)
+
+// ValidateCurrency validates currency syntax and checks dictionary via assetResolver.
+func ValidateCurrency(cur string, assetResolver AssetResolver) error {
+	// Basic presence
+	if strings.TrimSpace(cur) == "" {
+		return merrors.InvalidArgument("currency is required", "intent.currency")
+	}
+
+	// Normalize
+	cur = strings.ToUpper(strings.TrimSpace(cur))
+
+	// Syntax check
+	if !currencySyntax.MatchString(cur) {
+		return merrors.InvalidArgument(
+			"invalid currency format (must be A–Z0–9, length 2–10)",
+			"intent.currency",
+		)
+	}
+
+	// Dictionary validation
+	if assetResolver == nil {
+		return merrors.InvalidArgument("asset resolver is not configured", "intent.currency")
+	}
+
+	if !assetResolver.IsSupported(cur) {
+		return merrors.InvalidArgument("unsupported currency/asset", "intent.currency")
+	}
+
+	return nil
+}
+
+func ValidateMoney(m *paymenttypes.Money, assetResolver AssetResolver) error {
+	if m == nil {
+		return merrors.InvalidArgument("money is required", "intent.amount")
+	}
+
+	// 1) Basic presence
+	if strings.TrimSpace(m.Amount) == "" {
+		return merrors.InvalidArgument("amount is required", "intent.amount")
+	}
+
+	// 2) Validate decimal amount
+	amount, err := decimal.NewFromString(m.Amount)
+	if err != nil {
+		return merrors.InvalidArgument("invalid decimal amount", "intent.amount")
+	}
+	if amount.IsNegative() {
+		return merrors.InvalidArgument("amount must be >= 0", "intent.amount")
+	}
+
+	// 3) Validate currency via helper
+	if err := ValidateCurrency(m.Currency, assetResolver); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+type CurrencyPair struct {
+	Base  string `json:"base"`
+	Quote string `json:"quote"`
+}
+
+func (p *CurrencyPair) Validate() error {
+	if p == nil {
+		return merrors.InvalidArgument("currency pair is required", "currncy_pair")
+	}
+	if err := ValidateCurrency(p.Base, &AssetResolverStub{}); err != nil {
+		return merrors.InvalidArgument("invalid base currency in pair: "+err.Error(), "currency_pair.base")
+	}
+	if err := ValidateCurrency(p.Quote, &AssetResolverStub{}); err != nil {
+		return merrors.InvalidArgument("invalid quote currency in pair: "+err.Error(), "currency_pair.quote")
+	}
+	return nil
+}
+
+type FXIntent struct {
+	Pair              *CurrencyPair `json:"pair,omitempty"`
+	Side              FXSide        `json:"side,omitempty"`
+	Firm              bool          `json:"firm,omitempty"`
+	TTLms             int64         `json:"ttl_ms,omitempty"`
+	PreferredProvider string        `json:"preferred_provider,omitempty"`
+	MaxAgeMs          int32         `json:"max_age_ms,omitempty"`
+}
+
+func (fx *FXIntent) Validate() error {
+	if fx.Pair == nil {
+		return merrors.InvalidArgument("fx pair is required", "intent.fx.pair")
+	}
+	if err := fx.Pair.Validate(); err != nil {
+		return err
+	}
+
+	switch strings.TrimSpace(string(fx.Side)) {
+	case string(FXSideBuyBaseSellQuote), string(FXSideSellBaseBuyQuote):
+	default:
+		return merrors.InvalidArgument("fx side is invalid", "intent.fx.side")
+	}
+
+	if fx.TTLms < 0 {
+		return merrors.InvalidArgument("fx ttl_ms cannot be negative", "intent.fx.ttl_ms")
+	}
+	if fx.TTLms == 0 && fx.Firm {
+		return merrors.InvalidArgument("firm quote requires positive ttl_ms", "intent.fx.ttl_ms")
+	}
+
+	if fx.MaxAgeMs < 0 {
+		return merrors.InvalidArgument("fx max_age_ms cannot be negative", "intent.fx.max_age_ms")
+	}
+
+	return nil
+}

api/edge/bff/interface/api/srequest/refresh.go

@@ -0,0 +1,5 @@
+package srequest
+
+import "github.com/tech/sendico/pkg/model"
+
+type AccessTokenRefresh = model.ClientRefreshToken

api/edge/bff/interface/api/srequest/reorder.go

@@ -0,0 +1,19 @@
+package srequest
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type Reorder struct {
+	ParentRef bson.ObjectID `json:"parentRef"`
+	From      int           `json:"from"`
+	To        int           `json:"to"`
+}
+
+type ReorderX struct {
+	ObjectRef bson.ObjectID `json:"objectRef"`
+	To        int           `json:"to"`
+}
+
+type ReorderXDefault struct {
+	ReorderX  `json:",inline"`
+	ParentRef bson.ObjectID `json:"parentRef"`
+}

api/edge/bff/interface/api/srequest/rotate.go

@@ -0,0 +1,5 @@
+package srequest
+
+import "github.com/tech/sendico/pkg/model"
+
+type TokenRefreshRotate = model.ClientRefreshToken

api/edge/bff/interface/api/srequest/sgchange.go

@@ -0,0 +1,13 @@
+package srequest
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+type GroupItemChange struct {
+	GroupRef bson.ObjectID `json:"groupRef"`
+	ItemRef  bson.ObjectID `json:"itemRef"`
+}
+
+type RemoveItemFromGroup struct {
+	GroupItemChange `json:",inline"`
+	TargetItemRef   bson.ObjectID `json:"targetItemRef"`
+}

api/edge/bff/interface/api/srequest/signup.go

@@ -0,0 +1,31 @@
+package srequest
+
+import (
+	"bytes"
+	"encoding/json"
+
+	"github.com/tech/sendico/pkg/model"
+)
+
+type Signup struct {
+	Account              model.AccountData `json:"account"`
+	Organization         model.Describable `json:"organization"`
+	OrganizationTimeZone string            `json:"organizationTimeZone"`
+	OwnerRole            model.Describable `json:"ownerRole"`
+	CryptoWallet         model.Describable `json:"cryptoWallet"`
+	LedgerWallet         model.Describable `json:"ledgerWallet"`
+}
+
+// UnmarshalJSON enforces strict parsing to catch malformed or unexpected fields.
+func (s *Signup) UnmarshalJSON(data []byte) error {
+	type alias Signup
+	var payload alias
+
+	dec := json.NewDecoder(bytes.NewReader(data))
+	dec.DisallowUnknownFields()
+	if err := dec.Decode(&payload); err != nil {
+		return err
+	}
+	*s = Signup(payload)
+	return nil
+}

api/edge/bff/interface/api/srequest/signup_test.go

@@ -0,0 +1,150 @@
+package srequest_test
+
+import (
+	"encoding/json"
+	"fmt"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/tech/sendico/pkg/model"
+	"github.com/tech/sendico/server/interface/api/srequest"
+)
+
+func TestSignupRequest_JSONSerialization(t *testing.T) {
+	signup := srequest.Signup{
+		Account: model.AccountData{
+			LoginData: model.LoginData{
+				UserDataBase: model.UserDataBase{
+					Login: "test@example.com",
+				},
+				Password: "TestPassword123!",
+			},
+			Describable: model.Describable{
+				Name: "Test User",
+			},
+		},
+		Organization: model.Describable{
+			Name: "Test Organization",
+		},
+		OrganizationTimeZone: "UTC",
+		OwnerRole: model.Describable{
+			Name: "Owner",
+		},
+	}
+
+	// Test JSON marshaling
+	jsonData, err := json.Marshal(signup)
+	require.NoError(t, err)
+	assert.NotEmpty(t, jsonData)
+
+	// Test JSON unmarshaling
+	var unmarshaled srequest.Signup
+	err = json.Unmarshal(jsonData, &unmarshaled)
+	require.NoError(t, err)
+
+	// Verify all fields are properly serialized/deserialized
+	assert.Equal(t, signup.Account.Name, unmarshaled.Account.Name)
+	assert.Equal(t, signup.Account.Login, unmarshaled.Account.Login)
+	assert.Equal(t, signup.Account.Password, unmarshaled.Account.Password)
+	assert.Equal(t, signup.Organization.Name, unmarshaled.Organization.Name)
+	assert.Equal(t, signup.OrganizationTimeZone, unmarshaled.OrganizationTimeZone)
+	assert.Equal(t, signup.OwnerRole.Name, unmarshaled.OwnerRole.Name)
+}
+
+func TestSignupRequest_MinimalValidRequest(t *testing.T) {
+	signup := srequest.Signup{
+		Account: model.AccountData{
+			LoginData: model.LoginData{
+				UserDataBase: model.UserDataBase{
+					Login: "test@example.com",
+				},
+				Password: "TestPassword123!",
+			},
+			Describable: model.Describable{
+				Name: "Test User",
+			},
+		},
+		Organization: model.Describable{
+			Name: "Test Organization",
+		},
+		OrganizationTimeZone: "UTC",
+		OwnerRole: model.Describable{
+			Name: "Owner",
+		},
+	}
+
+	// Test JSON marshaling
+	jsonData, err := json.Marshal(signup)
+	require.NoError(t, err)
+	assert.NotEmpty(t, jsonData)
+
+	// Test JSON unmarshaling
+	var unmarshaled srequest.Signup
+	err = json.Unmarshal(jsonData, &unmarshaled)
+	require.NoError(t, err)
+
+	// Verify minimal request is valid
+	assert.Equal(t, signup.Account.Name, unmarshaled.Account.Name)
+	assert.Equal(t, signup.Account.Login, unmarshaled.Account.Login)
+	assert.Equal(t, signup.Organization.Name, unmarshaled.Organization.Name)
+}
+
+func TestSignupRequest_InvalidJSON(t *testing.T) {
+	invalidJSONs := []string{
+		`{"account": invalid}`,
+		`{"organization": 123}`,
+		`{"organizationTimeZone": true}`,
+		`{"defaultPriorityGroup": "not_an_object"}`,
+		`{"anonymousUser": []}`,
+		`{"anonymousRole": 456}`,
+		`{invalid json}`,
+	}
+
+	for i, invalidJSON := range invalidJSONs {
+		t.Run(fmt.Sprintf("Invalid JSON %d", i), func(t *testing.T) {
+			var signup srequest.Signup
+			err := json.Unmarshal([]byte(invalidJSON), &signup)
+			require.Error(t, err)
+		})
+	}
+}
+
+func TestSignupRequest_UnicodeCharacters(t *testing.T) {
+	signup := srequest.Signup{
+		Account: model.AccountData{
+			LoginData: model.LoginData{
+				UserDataBase: model.UserDataBase{
+					Login: "测试@example.com",
+				},
+				Password: "TestPassword123!",
+			},
+			Describable: model.Describable{
+				Name: "Test 用户 Üser",
+			},
+		},
+		Organization: model.Describable{
+			Name: "测试 Organization",
+		},
+		OrganizationTimeZone: "UTC",
+		OwnerRole: model.Describable{
+			Name: "所有者",
+		},
+	}
+
+	// Test JSON marshaling
+	jsonData, err := json.Marshal(signup)
+	require.NoError(t, err)
+	assert.NotEmpty(t, jsonData)
+
+	// Test JSON unmarshaling
+	var unmarshaled srequest.Signup
+	err = json.Unmarshal(jsonData, &unmarshaled)
+	require.NoError(t, err)
+
+	// Verify unicode characters are properly handled
+	assert.Equal(t, "测试@example.com", unmarshaled.Account.Login)
+	assert.Equal(t, "Test 用户 Üser", unmarshaled.Account.Name)
+	assert.Equal(t, "测试 Organization", unmarshaled.Organization.Name)
+	assert.Equal(t, "所有者", unmarshaled.OwnerRole.Name)
+}

api/edge/bff/interface/api/srequest/taggable.go

@@ -0,0 +1,20 @@
+package srequest
+
+import "go.mongodb.org/mongo-driver/v2/bson"
+
+// TaggableSingle is used for single tag operations (add/remove tag)
+type TaggableSingle struct {
+	ObjectRef bson.ObjectID `json:"objectRef"`
+	TagRef    bson.ObjectID `json:"tagRef"`
+}
+
+// TaggableMultiple is used for multiple tag operations (add tags, set tags)
+type TaggableMultiple struct {
+	ObjectRef bson.ObjectID   `json:"objectRef"`
+	TagRefs   []bson.ObjectID `json:"tagRefs"`
+}
+
+// TaggableObject is used for object-only operations (remove all tags, get tags)
+type TaggableObject struct {
+	ObjectRef bson.ObjectID `json:"objectRef"`
+}

api/edge/bff/interface/api/srequest/validateable.go

@@ -0,0 +1,5 @@
+package srequest
+
+type Validatable interface {
+	Validate() error
+}

api/edge/bff/interface/api/srequest/wallet.go

@@ -0,0 +1,12 @@
+package srequest
+
+import (
+	"github.com/tech/sendico/pkg/model"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+type CreateWallet struct {
+	Description model.Describable   `json:"description"`
+	Asset       model.ChainAssetKey `json:"asset"`
+	OwnerRef    *bson.ObjectID      `json:"ownerRef,omitempty"`
+}