epay

package module
v0.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 13 Imported by: 0

Documentation

Overview

Package epay implements the payment.PaymentProvider interface for Epay (易支付) aggregated payment gateways, including the ZPay (zpayz.cn) enhanced variant.

Epay is a self-hosted payment aggregation protocol commonly used to proxy Alipay (支付宝), WeChat Pay (微信支付), and QQ Pay behind a single MD5-signed endpoint. This adapter supports two checkout modes:

  • Redirect mode: builds a signed form that redirects the payer's browser to the gateway's /submit.php cashier page.
  • API mode: POSTs to /mapi.php and receives a JSON response containing a payment URL, QR code link, or QR code image.

Beyond checkout, the adapter also implements payment.Refunder and payment.BalanceQuerier for gateways that expose the /api.php management endpoints (order query, balance query, refund).

The adapter is stateless after construction and safe for concurrent use.

Index

Constants

This section is empty.

Variables

View Source
var ErrMissingConfig = errors.New("epay: missing configuration")

ErrMissingConfig is returned when required configuration is absent.

Functions

This section is empty.

Types

type Adapter

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

Adapter implements payment.PaymentProvider for Epay.

func New

func New(cfg Config, opts ...Option) *Adapter

New constructs an Epay adapter.

func (*Adapter) BuildWebhookResponse

func (a *Adapter) BuildWebhookResponse(ctx context.Context, success bool, msg string) (*payment.WebhookResponse, error)

BuildWebhookResponse returns the Epay ack body. Epay expects the literal string "success" on successful processing and "fail" on failure.

func (*Adapter) Configured

func (a *Adapter) Configured() bool

Configured reports whether the adapter has the minimum credentials.

func (*Adapter) CreateCheckout

func (a *Adapter) CreateCheckout(ctx context.Context, req *payment.CheckoutRequest) (*payment.CheckoutResult, error)

CreateCheckout builds the Epay payment request. In ModeRedirect it returns a signed form URL + params for browser redirect. In ModeAPI it POSTs to /mapi.php and returns the JSON-derived payment URL or QR code.

func (*Adapter) Provider

func (a *Adapter) Provider() payment.Provider

Provider returns the gateway identifier.

func (*Adapter) QueryBalance added in v0.2.0

func (a *Adapter) QueryBalance(ctx context.Context) (*payment.BalanceResult, error)

QueryBalance queries the gateway's /api.php?act=balance endpoint.

func (*Adapter) QueryOrder

func (a *Adapter) QueryOrder(ctx context.Context, req *payment.OrderQuery) (*payment.OrderQueryResult, error)

QueryOrder queries the gateway's /api.php?act=order endpoint for the current status of an order. Either TradeNo or ProviderOrderID may be used; TradeNo (out_trade_no) is preferred.

func (*Adapter) Refund added in v0.2.0

Refund submits a refund request to /api.php?act=refund. Either TradeNo or ProviderOrderID must be set. Money is the refund amount; most channels require it to match the original charge.

func (*Adapter) VerifyWebhook

func (a *Adapter) VerifyWebhook(ctx context.Context, req *payment.WebhookVerifyRequest) (*payment.WebhookEvent, error)

VerifyWebhook verifies the Epay MD5 callback signature and parses the form parameters into a normalized WebhookEvent.

type CheckoutMode added in v0.2.0

type CheckoutMode string

CheckoutMode selects the checkout flow.

const (
	// ModeRedirect builds a signed form and redirects the payer to
	// /submit.php. This is the default and works with all Epay gateways.
	ModeRedirect CheckoutMode = "redirect"

	// ModeAPI POSTs to /mapi.php and returns a JSON response with a
	// payment URL or QR code. Requires a gateway that supports the API
	// payment endpoint (e.g. ZPay).
	ModeAPI CheckoutMode = "api"
)

type Config

type Config struct {
	// PartnerID is the merchant id issued by the Epay gateway (pid).
	PartnerID string

	// Key is the merchant signing key shared with the gateway.
	Key string

	// BaseURL is the gateway root URL (e.g. https://zpayz.cn).
	BaseURL string

	// CheckoutMode selects redirect vs API checkout flow. Defaults to
	// ModeRedirect when empty.
	CheckoutMode CheckoutMode

	// HTTPTimeout is the timeout for outbound API calls. Defaults to 15s.
	HTTPTimeout time.Duration
}

Config holds the Epay gateway credentials.

type Option

type Option func(*Config)

Option mutates Config.

func WithCheckoutMode added in v0.2.0

func WithCheckoutMode(m CheckoutMode) Option

WithCheckoutMode sets the checkout flow mode.

func WithHTTPTimeout

func WithHTTPTimeout(d time.Duration) Option

WithHTTPTimeout sets the outbound HTTP timeout.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL