payment

Documentation

Overview

Package payment defines a provider abstraction over payment gateways so the order service is not hardcoded to alipay. A gateway (alipay, wechat, stripe, ...) implements Provider and is registered in Registry by its platform name. The package deliberately imports only model (never service) to avoid an import cycle; configuration is supplied via an injected function.

Index

• Constants
• Variables
• func PlatformEnabledKey(platform string) string
• type ChannelInfo
• type ConfigSource
• type ConfigStatusProvider
• type PayDirective
• type Provider
• type Registry
  • func NewRegistry(getConfig ConfigSource) *Registry
  • func (r *Registry) DefaultPlatform() string
  • func (r *Registry) Get(platform string) (Provider, error)
  • func (r *Registry) IsAvailable(platform string) (bool, error)
  • func (r *Registry) IsConfigured(platform string) bool
  • func (r *Registry) IsEnabled(platform string) bool
  • func (r *Registry) List() []ChannelInfo
  • func (r *Registry) Register(platform string, f factory)

Constants

const (
	ModeRedirect = "redirect"
	ModeQR       = "qr"
	ModeIAP      = "iap"
)

ChannelMode enumerates the values returned by Provider.Mode.

Variables

var PlatformLabel = map[string]string{
	model.OrderPlatformAlipay: "Alipay",
	model.OrderPlatformWechat: "WeChat Pay",
	model.OrderPlatformStripe: "Stripe",
	model.OrderPlatformPaypal: "PayPal",
	model.OrderPlatformApple:  "Apple (App Store)",
}

PlatformLabel maps a platform identifier to a human-readable label used by the frontend and the available-methods endpoint.

Functions

func PlatformEnabledKey

func PlatformEnabledKey(platform string) string

PlatformEnabledKey returns the SystemConfig key that holds the admin's explicit on/off toggle for the given platform.

Types

type ChannelInfo

type ChannelInfo struct {
	Platform   string `json:"platform"`
	Label      string `json:"label"`
	Mode       string `json:"mode"`
	Enabled    bool   `json:"enabled"`
	Configured bool   `json:"configured"`
}

ChannelInfo describes a registered payment platform for the "list available methods" endpoint. Enabled reflects the admin's explicit on/off toggle (payment.<platform>.enabled; absent = enabled for backward compatibility); Configured reflects whether the provider's credentials are present.

type ConfigSource

type ConfigSource func() (map[string]string, error)

ConfigSource supplies the raw SystemConfig key/value map. Injected as a function (sysCfg.GetAll) so this package never imports service, which would create a cycle (service depends on payment).

type ConfigStatusProvider

type ConfigStatusProvider interface {
	// IsConfigured reports whether the provider has the credentials it needs
	// to actually collect a payment.
	IsConfigured() bool
}

ConfigStatusProvider is optionally implemented by providers that can report whether they are fully configured (i.e. the required credentials are present in SystemConfig). The Registry uses it to build the list of available payment methods surfaced to the frontend; providers that do not implement it are always reported as configured.

type PayDirective

type PayDirective struct {
	// Kind is "redirect" (open URL in a browser, e.g. stripe checkout) or
	// "qr" (render URL as a QR code the user scans, e.g. alipay
	// trade.precreate qr_code / wechat NATIVE code_url).
	Kind string
	// URL is the browser redirect URL when Kind="redirect", or the QR code
	// content (e.g. an alipay qr_code or wechat code_url) when Kind="qr".
	URL string
	// WalletUsedCents is the amount of the order the user's wallet balance
	// covered (0 when the wallet was not used). WalletRemainingCents is the
	// wallet balance left after that debit. Both are populated even when a
	// gateway step still follows, so the client can show "paid X from wallet".
	WalletUsedCents      int64 `json:"wallet_used_cents"`
	WalletRemainingCents int64 `json:"wallet_remaining_cents"`
}

PayDirective tells the frontend how to present the payment to the user.

type Provider

type Provider interface {
	// Platform returns the canonical platform identifier stored on
	// Order.Platform (e.g. model.OrderPlatformAlipay).
	Platform() string

	// Mode reports how the frontend should present the PayDirective returned by
	// PayURL. Known values: "redirect" (open URL in a browser, e.g. stripe /
	// paypal checkout), "qr" (render URL as a QR code to scan, e.g. alipay /
	// wechat NATIVE), and "iap" (an in-app purchase the user completes inside a
	// native app, e.g. Apple App Store — there is no URL to open).
	Mode() string

	// PayURL returns a PayDirective describing how the user pays for order.
	PayURL(order *model.Order, subject string) (*PayDirective, error)

	// VerifyNotify verifies an async gateway notification from the raw request
	// (compatible with alipay form posts, wechat/stripe JSON callbacks and
	// signature headers). It returns the out_trade_no used to look up the
	// order, the gateway's transaction id, and whether the notification
	// represents a successful (paid) payment. Transient non-paid states return
	// paid=false with a nil error so the gateway can be told the notification
	// was received without granting entitlement.
	VerifyNotify(ctx context.Context, r *http.Request) (outTradeNo, tradeNo string, paid bool, err error)
}

Provider abstracts a single payment gateway. Adding a new platform means implementing Provider and registering it in Registry.Get.

type Registry

type Registry struct {
	// contains filtered or unexported fields
}

Registry resolves a Provider by platform name. Providers register themselves (see the alipay package's Register) so this package has no compile-time dependency on any concrete gateway. Providers are built lazily and cached for the life of the process; each provider caches its own gateway client and rebuilds it when its credentials change.

func NewRegistry

func NewRegistry(getConfig ConfigSource) *Registry

NewRegistry builds a Registry. getConfig is typically sysCfg.GetAll.

func (*Registry) DefaultPlatform

func (r *Registry) DefaultPlatform() string

DefaultPlatform returns the first platform (in platformPriority order) that is both enabled and configured, falling back to alipay for backward compatibility. It is used when an order is created without an explicit platform selection.

func (*Registry) Get

func (r *Registry) Get(platform string) (Provider, error)

Get returns the Provider for platform, building and caching it on first use. An empty platform defaults to alipay. Unknown platforms return an error.

func (*Registry) IsAvailable

func (r *Registry) IsAvailable(platform string) (bool, error)

IsAvailable reports whether platform can be used to collect a payment: it must be registered, enabled by the admin, and have its credentials present.

func (*Registry) IsConfigured

func (r *Registry) IsConfigured(platform string) bool

IsConfigured reports whether the provider for platform has the credentials it needs. Unregistered platforms are reported as not configured.

func (*Registry) IsEnabled

func (r *Registry) IsEnabled(platform string) bool

IsEnabled reports whether the admin's explicit toggle for platform is on. The key absent means enabled (for backward compatibility with deployments that only configured credentials and never set the toggle).

func (*Registry) List

func (r *Registry) List() []ChannelInfo

List returns every registered payment platform with its label, mode, and availability (enabled && configured). The frontend uses this to render a payment-method picker.

func (*Registry) Register

func (r *Registry) Register(platform string, f factory)

Register associates a platform name with a Provider factory. Called by each gateway package's Register function.