gitcaddy-server/modules/monetize/provider.go

// Copyright 2026 MarketAlly. All rights reserved.
// SPDX-License-Identifier: MIT

package monetize

import "context"

// ProviderType identifies a payment provider.
type ProviderType string

const (
	ProviderStripe ProviderType = "stripe"
	ProviderPayPal ProviderType = "paypal"
)

// SubscriptionResult holds the IDs returned after creating a subscription.
type SubscriptionResult struct {
	ProviderSubscriptionID string // Stripe subscription ID or PayPal subscription ID
	ClientSecret           string // Stripe PaymentIntent client_secret for frontend confirmation
}

// OneTimePaymentResult holds the IDs returned after creating a one-time payment.
type OneTimePaymentResult struct {
	ProviderPaymentID string // Stripe PaymentIntent ID or PayPal order ID
	ClientSecret      string // Stripe PaymentIntent client_secret for frontend confirmation
	ApprovalURL       string // PayPal approval URL (empty for Stripe)
}

// PaymentProvider defines the interface for payment integrations.
type PaymentProvider interface {
	// CreateSubscription creates a recurring subscription for the given customer/price.
	// customerEmail is used to find or create the customer on the provider side.
	// stripePriceID or paypalPlanID from the product is used.
	CreateSubscription(ctx context.Context, customerEmail, providerPriceID string, metadata map[string]string) (*SubscriptionResult, error)

	// CreateOneTimePayment creates a one-time payment (for lifetime access).
	CreateOneTimePayment(ctx context.Context, customerEmail string, amountCents int64, currency string, metadata map[string]string) (*OneTimePaymentResult, error)

	// CancelSubscription cancels an active subscription by its provider ID.
	CancelSubscription(ctx context.Context, providerSubscriptionID string) error

	// VerifyWebhookSignature verifies the webhook payload signature.
	// Returns the raw event payload if valid.
	VerifyWebhookSignature(payload []byte, signature string) ([]byte, error)

	// Type returns the provider type.
	Type() ProviderType
}