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 ¶
- Variables
- type Adapter
- func (a *Adapter) BuildWebhookResponse(ctx context.Context, success bool, msg string) (*payment.WebhookResponse, error)
- func (a *Adapter) Configured() bool
- func (a *Adapter) CreateCheckout(ctx context.Context, req *payment.CheckoutRequest) (*payment.CheckoutResult, error)
- func (a *Adapter) Provider() payment.Provider
- func (a *Adapter) QueryBalance(ctx context.Context) (*payment.BalanceResult, error)
- func (a *Adapter) QueryOrder(ctx context.Context, req *payment.OrderQuery) (*payment.OrderQueryResult, error)
- func (a *Adapter) Refund(ctx context.Context, req *payment.RefundRequest) (*payment.RefundResult, error)
- func (a *Adapter) VerifyWebhook(ctx context.Context, req *payment.WebhookVerifyRequest) (*payment.WebhookEvent, error)
- type CheckoutMode
- type Config
- type Option
Constants ¶
This section is empty.
Variables ¶
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 (*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 ¶
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) QueryBalance ¶ added in v0.2.0
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
func (a *Adapter) Refund(ctx context.Context, req *payment.RefundRequest) (*payment.RefundResult, error)
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 ¶
WithHTTPTimeout sets the outbound HTTP timeout.