monetix gateway

api/gateway/mntx/internal/service/monetix/client.go

@@ -0,0 +1,66 @@
+package monetix
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"net/http"
+
+	"github.com/tech/sendico/pkg/merrors"
+	"github.com/tech/sendico/pkg/mlogger"
+	"go.uber.org/zap"
+)
+
+type Client struct {
+	cfg    Config
+	client *http.Client
+	logger mlogger.Logger
+}
+
+func NewClient(cfg Config, httpClient *http.Client, logger mlogger.Logger) *Client {
+	client := httpClient
+	if client == nil {
+		client = &http.Client{Timeout: cfg.timeout()}
+	}
+	cl := logger
+	if cl == nil {
+		cl = zap.NewNop()
+	}
+	return &Client{
+		cfg:    cfg,
+		client: client,
+		logger: cl.Named("monetix_client"),
+	}
+}
+
+func (c *Client) CreateCardPayout(ctx context.Context, req CardPayoutRequest) (*CardPayoutSendResult, error) {
+	return c.sendCardPayout(ctx, req)
+}
+
+func (c *Client) CreateCardTokenPayout(ctx context.Context, req CardTokenPayoutRequest) (*CardPayoutSendResult, error) {
+	return c.sendCardTokenPayout(ctx, req)
+}
+
+func (c *Client) CreateCardTokenization(ctx context.Context, req CardTokenizeRequest) (*TokenizationResult, error) {
+	return c.sendTokenization(ctx, req)
+}
+
+func signPayload(payload any, secret string) (string, error) {
+	data, err := json.Marshal(payload)
+	if err != nil {
+		return "", err
+	}
+
+	h := hmac.New(sha256.New, []byte(secret))
+	if _, err := h.Write(data); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+// SignPayload exposes signature calculation for callback verification.
+func SignPayload(payload any, secret string) (string, error) {
+	return signPayload(payload, secret)
+}

api/gateway/mntx/internal/service/monetix/config.go

@@ -0,0 +1,78 @@
+package monetix
+
+import (
+	"strings"
+	"time"
+)
+
+const (
+	DefaultRequestTimeout   = 15 * time.Second
+	DefaultStatusSuccess    = "success"
+	DefaultStatusProcessing = "processing"
+
+	OutcomeSuccess    = "success"
+	OutcomeProcessing = "processing"
+	OutcomeDecline    = "decline"
+)
+
+// Config holds resolved settings for communicating with Monetix.
+type Config struct {
+	BaseURL                string
+	ProjectID              int64
+	SecretKey              string
+	AllowedCurrencies      []string
+	RequireCustomerAddress bool
+	RequestTimeout         time.Duration
+	StatusSuccess          string
+	StatusProcessing       string
+}
+
+func DefaultConfig() Config {
+	return Config{
+		RequestTimeout:   DefaultRequestTimeout,
+		StatusSuccess:    DefaultStatusSuccess,
+		StatusProcessing: DefaultStatusProcessing,
+	}
+}
+
+func (c Config) timeout() time.Duration {
+	if c.RequestTimeout <= 0 {
+		return DefaultRequestTimeout
+	}
+	return c.RequestTimeout
+}
+
+// Timeout exposes the configured HTTP timeout for external callers.
+func (c Config) Timeout() time.Duration {
+	return c.timeout()
+}
+
+func (c Config) CurrencyAllowed(code string) bool {
+	code = strings.ToUpper(strings.TrimSpace(code))
+	if code == "" {
+		return false
+	}
+	if len(c.AllowedCurrencies) == 0 {
+		return true
+	}
+	for _, allowed := range c.AllowedCurrencies {
+		if strings.EqualFold(strings.TrimSpace(allowed), code) {
+			return true
+		}
+	}
+	return false
+}
+
+func (c Config) SuccessStatus() string {
+	if strings.TrimSpace(c.StatusSuccess) == "" {
+		return DefaultStatusSuccess
+	}
+	return strings.ToLower(strings.TrimSpace(c.StatusSuccess))
+}
+
+func (c Config) ProcessingStatus() string {
+	if strings.TrimSpace(c.StatusProcessing) == "" {
+		return DefaultStatusProcessing
+	}
+	return strings.ToLower(strings.TrimSpace(c.StatusProcessing))
+}

api/gateway/mntx/internal/service/monetix/mask.go

@@ -0,0 +1,21 @@
+package monetix
+
+import "strings"
+
+// MaskPAN redacts a primary account number by keeping the first 6 and last 4 digits.
+func MaskPAN(pan string) string {
+	p := strings.TrimSpace(pan)
+	if len(p) <= 4 {
+		return strings.Repeat("*", len(p))
+	}
+
+	if len(p) <= 10 {
+		return p[:2] + strings.Repeat("*", len(p)-4) + p[len(p)-2:]
+	}
+
+	maskLen := len(p) - 10
+	if maskLen < 0 {
+		maskLen = 0
+	}
+	return p[:6] + strings.Repeat("*", maskLen) + p[len(p)-4:]
+}

api/gateway/mntx/internal/service/monetix/metrics.go

@@ -0,0 +1,71 @@
+package monetix
+
+import (
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/prometheus/client_golang/prometheus"
+	"github.com/prometheus/client_golang/prometheus/promauto"
+)
+
+var (
+	metricsOnce sync.Once
+
+	cardPayoutRequests  *prometheus.CounterVec
+	cardPayoutCallbacks *prometheus.CounterVec
+	cardPayoutLatency   *prometheus.HistogramVec
+)
+
+func initMetrics() {
+	metricsOnce.Do(func() {
+		cardPayoutRequests = promauto.NewCounterVec(prometheus.CounterOpts{
+			Namespace: "sendico",
+			Subsystem: "mntx_gateway",
+			Name:      "card_payout_requests_total",
+			Help:      "Monetix card payout submissions grouped by outcome.",
+		}, []string{"outcome"})
+
+		cardPayoutCallbacks = promauto.NewCounterVec(prometheus.CounterOpts{
+			Namespace: "sendico",
+			Subsystem: "mntx_gateway",
+			Name:      "card_payout_callbacks_total",
+			Help:      "Monetix card payout callbacks grouped by provider status.",
+		}, []string{"status"})
+
+		cardPayoutLatency = promauto.NewHistogramVec(prometheus.HistogramOpts{
+			Namespace: "sendico",
+			Subsystem: "mntx_gateway",
+			Name:      "card_payout_request_latency_seconds",
+			Help:      "Latency distribution for outbound Monetix card payout requests.",
+			Buckets:   prometheus.DefBuckets,
+		}, []string{"outcome"})
+	})
+}
+
+func observeRequest(outcome string, duration time.Duration) {
+	initMetrics()
+	outcome = strings.ToLower(strings.TrimSpace(outcome))
+	if outcome == "" {
+		outcome = "unknown"
+	}
+	if cardPayoutLatency != nil {
+		cardPayoutLatency.WithLabelValues(outcome).Observe(duration.Seconds())
+	}
+	if cardPayoutRequests != nil {
+		cardPayoutRequests.WithLabelValues(outcome).Inc()
+	}
+}
+
+// ObserveCallback records callback status for Monetix card payouts.
+func ObserveCallback(status string) {
+	initMetrics()
+	status = strings.TrimSpace(status)
+	if status == "" {
+		status = "unknown"
+	}
+	status = strings.ToLower(status)
+	if cardPayoutCallbacks != nil {
+		cardPayoutCallbacks.WithLabelValues(status).Inc()
+	}
+}

api/gateway/mntx/internal/service/monetix/payloads.go

@@ -0,0 +1,96 @@
+package monetix
+
+type General struct {
+	ProjectID int64  `json:"project_id"`
+	PaymentID string `json:"payment_id"`
+	Signature string `json:"signature,omitempty"`
+}
+
+type Customer struct {
+	ID        string `json:"id"`
+	FirstName string `json:"first_name"`
+	Middle    string `json:"middle_name,omitempty"`
+	LastName  string `json:"last_name"`
+	IP        string `json:"ip_address"`
+
+	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"`
+}
+
+type Payment struct {
+	Amount   int64  `json:"amount"`
+	Currency string `json:"currency"`
+}
+
+type Card struct {
+	PAN        string `json:"pan"`
+	Year       int    `json:"year,omitempty"`
+	Month      int    `json:"month,omitempty"`
+	CardHolder string `json:"card_holder"`
+}
+
+type CardTokenize struct {
+	PAN        string `json:"pan"`
+	Year       int    `json:"year,omitempty"`
+	Month      int    `json:"month,omitempty"`
+	CardHolder string `json:"card_holder"`
+	CVV        string `json:"cvv,omitempty"`
+}
+
+type Token struct {
+	CardToken  string `json:"card_token"`
+	CardHolder string `json:"card_holder,omitempty"`
+	MaskedPAN  string `json:"masked_pan,omitempty"`
+}
+
+type CardPayoutRequest struct {
+	General  General  `json:"general"`
+	Customer Customer `json:"customer"`
+	Payment  Payment  `json:"payment"`
+	Card     Card     `json:"card"`
+}
+
+type CardTokenPayoutRequest struct {
+	General  General  `json:"general"`
+	Customer Customer `json:"customer"`
+	Payment  Payment  `json:"payment"`
+	Token    Token    `json:"token"`
+}
+
+type CardTokenizeRequest struct {
+	General  General      `json:"general"`
+	Customer Customer     `json:"customer"`
+	Card     CardTokenize `json:"card"`
+}
+
+type CardPayoutSendResult struct {
+	Accepted          bool
+	ProviderRequestID string
+	StatusCode        int
+	ErrorCode         string
+	ErrorMessage      string
+}
+
+type TokenizationResult struct {
+	CardPayoutSendResult
+	Token       string
+	MaskedPAN   string
+	ExpiryMonth string
+	ExpiryYear  string
+	CardBrand   string
+}
+
+type APIResponse struct {
+	RequestID string `json:"request_id"`
+	Message   string `json:"message"`
+	Code      string `json:"code"`
+	Operation struct {
+		RequestID string `json:"request_id"`
+		Status    string `json:"status"`
+		Code      string `json:"code"`
+		Message   string `json:"message"`
+	} `json:"operation"`
+}

api/gateway/mntx/internal/service/monetix/sender.go

@@ -0,0 +1,289 @@
+package monetix
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"io"
+	"net/http"
+	"strings"
+	"time"
+
+	"github.com/tech/sendico/pkg/merrors"
+	"go.uber.org/zap"
+)
+
+const (
+	outcomeAccepted     = "accepted"
+	outcomeHTTPError    = "http_error"
+	outcomeNetworkError = "network_error"
+)
+
+// sendCardPayout dispatches a PAN-based payout.
+func (c *Client) sendCardPayout(ctx context.Context, req CardPayoutRequest) (*CardPayoutSendResult, error) {
+	maskedPAN := MaskPAN(req.Card.PAN)
+	return c.send(ctx, &req, "/v2/payment/card/payout",
+		func() {
+			c.logger.Info("dispatching Monetix card payout",
+				zap.String("payout_id", req.General.PaymentID),
+				zap.Int64("amount_minor", req.Payment.Amount),
+				zap.String("currency", req.Payment.Currency),
+				zap.String("pan", maskedPAN),
+			)
+		},
+		func(r *CardPayoutSendResult) {
+			c.logger.Info("Monetix payout response",
+				zap.String("payout_id", req.General.PaymentID),
+				zap.Bool("accepted", r.Accepted),
+				zap.Int("status_code", r.StatusCode),
+				zap.String("provider_request_id", r.ProviderRequestID),
+				zap.String("error_code", r.ErrorCode),
+				zap.String("error_message", r.ErrorMessage),
+			)
+		})
+}
+
+// sendCardTokenPayout dispatches a token-based payout.
+func (c *Client) sendCardTokenPayout(ctx context.Context, req CardTokenPayoutRequest) (*CardPayoutSendResult, error) {
+	return c.send(ctx, &req, "/v2/payment/card/payout/token",
+		func() {
+			c.logger.Info("dispatching Monetix card token payout",
+				zap.String("payout_id", req.General.PaymentID),
+				zap.Int64("amount_minor", req.Payment.Amount),
+				zap.String("currency", req.Payment.Currency),
+				zap.String("masked_pan", req.Token.MaskedPAN),
+			)
+		},
+		func(r *CardPayoutSendResult) {
+			c.logger.Info("Monetix token payout response",
+				zap.String("payout_id", req.General.PaymentID),
+				zap.Bool("accepted", r.Accepted),
+				zap.Int("status_code", r.StatusCode),
+				zap.String("provider_request_id", r.ProviderRequestID),
+				zap.String("error_code", r.ErrorCode),
+				zap.String("error_message", r.ErrorMessage),
+			)
+		})
+}
+
+// sendTokenization sends a tokenization request.
+func (c *Client) sendTokenization(ctx context.Context, req CardTokenizeRequest) (*TokenizationResult, error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if c == nil {
+		return nil, merrors.Internal("monetix client not initialised")
+	}
+	if strings.TrimSpace(c.cfg.SecretKey) == "" {
+		return nil, merrors.Internal("monetix secret key not configured")
+	}
+	if strings.TrimSpace(c.cfg.BaseURL) == "" {
+		return nil, merrors.Internal("monetix base url not configured")
+	}
+
+	req.General.Signature = ""
+	signature, err := signPayload(req, c.cfg.SecretKey)
+	if err != nil {
+		return nil, merrors.Internal("failed to sign request: " + err.Error())
+	}
+	req.General.Signature = signature
+
+	payload, err := json.Marshal(req)
+	if err != nil {
+		return nil, merrors.Internal("failed to marshal request payload: " + err.Error())
+	}
+
+	url := strings.TrimRight(c.cfg.BaseURL, "/") + "/v1/tokenize"
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
+	if err != nil {
+		return nil, merrors.Internal("failed to build request: " + err.Error())
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Accept", "application/json")
+
+	c.logger.Info("dispatching Monetix card tokenization",
+		zap.String("request_id", req.General.PaymentID),
+		zap.String("masked_pan", MaskPAN(req.Card.PAN)),
+	)
+
+	start := time.Now()
+	resp, err := c.client.Do(httpReq)
+	duration := time.Since(start)
+	if err != nil {
+		observeRequest(outcomeNetworkError, duration)
+		return nil, merrors.Internal("monetix tokenization request failed: " + err.Error())
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	outcome := outcomeAccepted
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		outcome = outcomeHTTPError
+	}
+	observeRequest(outcome, duration)
+
+	result := &TokenizationResult{
+		CardPayoutSendResult: CardPayoutSendResult{
+			Accepted:   resp.StatusCode >= 200 && resp.StatusCode < 300,
+			StatusCode: resp.StatusCode,
+		},
+	}
+
+	var apiResp APIResponse
+	if len(body) > 0 {
+		if err := json.Unmarshal(body, &apiResp); err != nil {
+			c.logger.Warn("failed to decode Monetix tokenization response", zap.String("request_id", req.General.PaymentID), zap.Int("status_code", resp.StatusCode), zap.Error(err))
+		} else {
+			var tokenData struct {
+				Token       string `json:"token"`
+				MaskedPAN   string `json:"masked_pan"`
+				ExpiryMonth string `json:"expiry_month"`
+				ExpiryYear  string `json:"expiry_year"`
+				CardBrand   string `json:"card_brand"`
+			}
+			_ = json.Unmarshal(body, &tokenData)
+			result.Token = tokenData.Token
+			result.MaskedPAN = tokenData.MaskedPAN
+			result.ExpiryMonth = tokenData.ExpiryMonth
+			result.ExpiryYear = tokenData.ExpiryYear
+			result.CardBrand = tokenData.CardBrand
+		}
+	}
+
+	if apiResp.Operation.RequestID != "" {
+		result.ProviderRequestID = apiResp.Operation.RequestID
+	} else if apiResp.RequestID != "" {
+		result.ProviderRequestID = apiResp.RequestID
+	}
+
+	if !result.Accepted {
+		result.ErrorCode = apiResp.Code
+		if result.ErrorCode == "" {
+			result.ErrorCode = http.StatusText(resp.StatusCode)
+		}
+		result.ErrorMessage = apiResp.Message
+		if result.ErrorMessage == "" {
+			result.ErrorMessage = apiResp.Operation.Message
+		}
+	}
+
+	c.logger.Info("Monetix tokenization response",
+		zap.String("request_id", req.General.PaymentID),
+		zap.Bool("accepted", result.Accepted),
+		zap.Int("status_code", resp.StatusCode),
+		zap.String("provider_request_id", result.ProviderRequestID),
+		zap.String("error_code", result.ErrorCode),
+		zap.String("error_message", result.ErrorMessage),
+	)
+
+	return result, nil
+}
+
+func (c *Client) send(ctx context.Context, req any, path string, dispatchLog func(), responseLog func(*CardPayoutSendResult)) (*CardPayoutSendResult, error) {
+	if ctx == nil {
+		ctx = context.Background()
+	}
+	if c == nil {
+		return nil, merrors.Internal("monetix client not initialised")
+	}
+	if strings.TrimSpace(c.cfg.SecretKey) == "" {
+		return nil, merrors.Internal("monetix secret key not configured")
+	}
+	if strings.TrimSpace(c.cfg.BaseURL) == "" {
+		return nil, merrors.Internal("monetix base url not configured")
+	}
+
+	setSignature, err := clearSignature(req)
+	if err != nil {
+		return nil, err
+	}
+	signature, err := signPayload(req, c.cfg.SecretKey)
+	if err != nil {
+		return nil, merrors.Internal("failed to sign request: " + err.Error())
+	}
+	setSignature(signature)
+
+	payload, err := json.Marshal(req)
+	if err != nil {
+		return nil, merrors.Internal("failed to marshal request payload: " + err.Error())
+	}
+
+	url := strings.TrimRight(c.cfg.BaseURL, "/") + path
+	httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(payload))
+	if err != nil {
+		return nil, merrors.Internal("failed to build request: " + err.Error())
+	}
+	httpReq.Header.Set("Content-Type", "application/json")
+	httpReq.Header.Set("Accept", "application/json")
+
+	if dispatchLog != nil {
+		dispatchLog()
+	}
+
+	start := time.Now()
+	resp, err := c.client.Do(httpReq)
+	duration := time.Since(start)
+	if err != nil {
+		observeRequest(outcomeNetworkError, duration)
+		return nil, merrors.Internal("monetix request failed: " + err.Error())
+	}
+	defer resp.Body.Close()
+
+	body, _ := io.ReadAll(resp.Body)
+	outcome := outcomeAccepted
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		outcome = outcomeHTTPError
+	}
+	observeRequest(outcome, duration)
+
+	result := &CardPayoutSendResult{
+		Accepted:   resp.StatusCode >= 200 && resp.StatusCode < 300,
+		StatusCode: resp.StatusCode,
+	}
+
+	var apiResp APIResponse
+	if len(body) > 0 {
+		if err := json.Unmarshal(body, &apiResp); err != nil {
+			c.logger.Warn("failed to decode Monetix response", zap.Int("status_code", resp.StatusCode), zap.Error(err))
+		}
+	}
+
+	if apiResp.Operation.RequestID != "" {
+		result.ProviderRequestID = apiResp.Operation.RequestID
+	} else if apiResp.RequestID != "" {
+		result.ProviderRequestID = apiResp.RequestID
+	}
+
+	if !result.Accepted {
+		result.ErrorCode = apiResp.Code
+		if result.ErrorCode == "" {
+			result.ErrorCode = http.StatusText(resp.StatusCode)
+		}
+		result.ErrorMessage = apiResp.Message
+		if result.ErrorMessage == "" {
+			result.ErrorMessage = apiResp.Operation.Message
+		}
+	}
+
+	if responseLog != nil {
+		responseLog(result)
+	}
+
+	return result, nil
+}
+
+func clearSignature(req any) (func(string), error) {
+	switch r := req.(type) {
+	case *CardPayoutRequest:
+		r.General.Signature = ""
+		return func(sig string) { r.General.Signature = sig }, nil
+	case *CardTokenPayoutRequest:
+		r.General.Signature = ""
+		return func(sig string) { r.General.Signature = sig }, nil
+	case *CardTokenizeRequest:
+		r.General.Signature = ""
+		return func(sig string) { r.General.Signature = sig }, nil
+	default:
+		return nil, merrors.Internal("unsupported monetix payload type for signing")
+	}
+}