payment

package
v0.1.21 Latest Latest
Warning

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

Go to latest
Published: Sep 28, 2026 License: MIT Imports: 8 Imported by: 0

Documentation

Index

Constants

View Source
const DefaultCurrency = "CNY"
View Source
const KeyPayment runtime.Key = "payment"

Variables

View Source
var (
	ErrNilContext             = errors.New("payment: nil context")
	ErrInvalidAmount          = errors.New("payment: invalid amount")
	ErrInvalidRequest         = errors.New("payment: invalid request")
	ErrInvalidAction          = errors.New("payment: invalid action")
	ErrInvalidCurrency        = errors.New("payment: invalid currency")
	ErrInvalidExchangeRate    = errors.New("payment: invalid exchange rate")
	ErrCurrencyMetaNotFound   = errors.New("payment: currency metadata not found")
	ErrSettleAmountMismatch   = errors.New("payment: settle amount mismatch")
	ErrUnsupportedProvider    = errors.New("payment: unsupported provider")
	ErrUnsupportedChannel     = errors.New("payment: unsupported channel")
	ErrUnsupportedCapability  = errors.New("payment: unsupported capability")
	ErrAdapterAlreadyExists   = errors.New("payment: adapter already exists")
	ErrAdapterNotFound        = errors.New("payment: adapter not found")
	ErrPaymentActionRequired  = errors.New("payment: action required")
	ErrNotifyVerificationFail = errors.New("payment: notify verification failed")
	ErrPaymentReference       = errors.New("payment: payment reference required")
	ErrInvalidStateTransition = errors.New("payment: invalid state transition")
)

Functions

func Bind

func Bind(app *runtime.App, service *Service) error

func CanTransitionPaymentStatus

func CanTransitionPaymentStatus(from, to PaymentStatus) bool

func Close

func Close()

func ClosePayment

func ClosePayment(ctx context.Context, req ClosePaymentRequest) error

func DefaultCurrencyMetadata

func DefaultCurrencyMetadata() map[string]CurrencyMeta

func IsPaymentClosed added in v0.1.10

func IsPaymentClosed(status PaymentStatus) bool

PaymentClosed reports a provider-confirmed unsuccessful terminal state.

func IsPaymentExpired added in v0.1.10

func IsPaymentExpired(local, provider *time.Time, now time.Time) bool

PaymentExpired does not imply that the provider has closed the payment.

func NormalizeCurrency

func NormalizeCurrency(code string) string

func PaymentDeadline added in v0.1.10

func PaymentDeadline(local, provider *time.Time) *time.Time

PaymentDeadline returns the earlier caller/provider deadline without changing either.

func RegisterProvider added in v0.1.10

func RegisterProvider(adapter ProviderAdapter) error

RegisterProvider registers against the initialized default service.

func ReloadChannels

func ReloadChannels(bindings []ChannelBinding) error

func SetDefault

func SetDefault(service *Service)

func WithProviderExchange added in v0.1.13

func WithProviderExchange(err error, exchange ProviderExchange) error

WithProviderExchange attaches credential-free raw request/response evidence to an error without changing errors.Is/errors.As behavior.

Types

type ActionType

type ActionType string
const (
	ActionNone        ActionType = "none"
	ActionRedirectURL ActionType = "redirect_url"
	ActionHTMLForm    ActionType = "html_form"
	ActionQRCode      ActionType = "qr_code"
	ActionSDKParams   ActionType = "sdk_params"
	ActionClientToken ActionType = "client_token"
)

type AddPayoutBatchItemsRequest added in v0.1.13

type AddPayoutBatchItemsRequest struct {
	Provider        Provider                 `json:"provider"`
	Channel         Channel                  `json:"channel"`
	MerchantKey     string                   `json:"merchant_key,omitempty"`
	ProviderBatchID string                   `json:"provider_batch_id"`
	Items           []PayoutBatchItemRequest `json:"items"`
}

type BeneficiaryProvider added in v0.1.13

type BeneficiaryProvider interface {
	CreateBeneficiary(context.Context, CreateBeneficiaryRequest) (*BeneficiaryResponse, error)
	QueryBeneficiary(context.Context, QueryBeneficiaryRequest) (*BeneficiaryResponse, error)
}

type BeneficiaryResponse added in v0.1.13

type BeneficiaryResponse struct {
	Provider      Provider         `json:"provider"`
	Channel       Channel          `json:"channel"`
	MerchantKey   string           `json:"merchant_key,omitempty"`
	BeneficiaryID string           `json:"beneficiary_id"`
	Exchange      ProviderExchange `json:"-"`
}

func CreateBeneficiary added in v0.1.13

func CreateBeneficiary(ctx context.Context, req CreateBeneficiaryRequest) (*BeneficiaryResponse, error)

func QueryBeneficiary added in v0.1.13

func QueryBeneficiary(ctx context.Context, req QueryBeneficiaryRequest) (*BeneficiaryResponse, error)

type BeneficiarySchemaKind added in v0.1.15

type BeneficiarySchemaKind string
const (
	BeneficiarySchemaAPI  BeneficiarySchemaKind = "api"
	BeneficiarySchemaForm BeneficiarySchemaKind = "form"
)

type BeneficiarySchemaProvider added in v0.1.15

type BeneficiarySchemaProvider interface {
	GenerateBeneficiarySchema(context.Context, GenerateBeneficiarySchemaRequest) (*BeneficiarySchemaResponse, error)
}

type BeneficiarySchemaResponse added in v0.1.15

type BeneficiarySchemaResponse struct {
	Provider    Provider              `json:"provider"`
	Channel     Channel               `json:"channel"`
	MerchantKey string                `json:"merchant_key,omitempty"`
	Kind        BeneficiarySchemaKind `json:"kind"`
	Condition   map[string]any        `json:"condition"`
	Fields      []map[string]any      `json:"fields"`
	Exchange    ProviderExchange      `json:"-"`
}

func GenerateBeneficiarySchema added in v0.1.15

func GenerateBeneficiarySchema(ctx context.Context, req GenerateBeneficiarySchemaRequest) (*BeneficiarySchemaResponse, error)

type Capabilities

type Capabilities struct {
	Provider              Provider     `json:"provider"`
	Channels              []Channel    `json:"channels,omitempty"`
	SupportedCurrencies   []string     `json:"supported_currencies,omitempty"`
	SupportedActions      []ActionType `json:"supported_actions,omitempty"`
	SupportsMultiMerchant bool         `json:"supports_multi_merchant,omitempty"`
	SupportsExpireAt      bool         `json:"supports_expire_at,omitempty"`
	SupportsClose         bool         `json:"supports_close,omitempty"`
	SupportsRefund        bool         `json:"supports_refund,omitempty"`
	SupportsQueryRefund   bool         `json:"supports_query_refund,omitempty"`
	SupportsPartialRefund bool         `json:"supports_partial_refund,omitempty"`
	SupportsQuery         bool         `json:"supports_query,omitempty"`
	SupportsNotify        bool         `json:"supports_notify,omitempty"`
	SupportsCapture       bool         `json:"supports_capture,omitempty"`
	SupportsConfirm       bool         `json:"supports_confirm,omitempty"`
	SupportsReconcile     bool         `json:"supports_reconcile,omitempty"`
	SupportsDispute       bool         `json:"supports_dispute,omitempty"`
	SupportsSubscription  bool         `json:"supports_subscription,omitempty"`
}

type Channel

type Channel string
const (
	ChannelWechatApp         Channel = "wechat_app"
	ChannelWechatMiniProgram Channel = "wechat_mini_program"
	ChannelWechatH5          Channel = "wechat_h5"
	ChannelWechatNative      Channel = "wechat_native"

	ChannelAlipayApp  Channel = "alipay_app"
	ChannelAlipayWap  Channel = "alipay_wap"
	ChannelAlipayPage Channel = "alipay_page"

	ChannelPayPalOrder    Channel = "paypal_order"
	ChannelStripeCheckout Channel = "stripe_checkout"
	ChannelStripeIntent   Channel = "stripe_payment_intent"
	ChannelAggregateForm  Channel = "aggregate_form"
)
const ChannelAirwallexHPP Channel = "airwallex_hpp"
const ChannelAirwallexTransfer Channel = "airwallex_transfer"

type ChannelBinding

type ChannelBinding struct {
	DisabledForNew bool     `mapstructure:"disabled_for_new" yaml:"disabled_for_new"`
	Key            string   `mapstructure:"key" yaml:"key"`
	Provider       Provider `mapstructure:"provider" yaml:"provider"`
	Channel        Channel  `mapstructure:"channel" yaml:"channel"`
	MerchantKey    string   `mapstructure:"merchant_key" yaml:"merchant_key"`
}

type ChannelSelection

type ChannelSelection struct {
	DisabledForNew bool
	Provider       Provider
	Channel        Channel
	MerchantKey    string
}

type ChannelSelectionRequest

type ChannelSelectionRequest struct {
	Provider    Provider
	Channel     Channel
	MerchantKey string
	Operation   PaymentOperation
}

type ChannelSelector

type ChannelSelector interface {
	SelectPaymentChannel(ctx context.Context, req ChannelSelectionRequest) (*ChannelSelection, error)
}

type ClosePaymentRequest

type ClosePaymentRequest struct {
	Provider        Provider       `json:"provider"`
	Channel         Channel        `json:"channel"`
	MerchantKey     string         `json:"merchant_key,omitempty"`
	PaymentID       string         `json:"payment_id,omitempty"`
	OrderID         string         `json:"order_id,omitempty"`
	OutTradeNo      string         `json:"out_trade_no,omitempty"`
	ProviderTradeID string         `json:"provider_trade_id,omitempty"`
	Extra           map[string]any `json:"extra,omitempty"`
}

type CreateBeneficiaryRequest added in v0.1.13

type CreateBeneficiaryRequest struct {
	Provider    Provider       `json:"provider"`
	Channel     Channel        `json:"channel"`
	MerchantKey string         `json:"merchant_key,omitempty"`
	Details     map[string]any `json:"details"`
}

type CreatePaymentRequest

type CreatePaymentRequest struct {
	// ProviderTradeID resumes a previously created intent without creating another.
	ProviderTradeID string         `json:"provider_trade_id,omitempty"`
	Provider        Provider       `json:"provider"`
	Channel         Channel        `json:"channel"`
	MerchantKey     string         `json:"merchant_key,omitempty"`
	PaymentID       string         `json:"payment_id,omitempty"`
	OrderID         string         `json:"order_id,omitempty"`
	OutTradeNo      string         `json:"out_trade_no,omitempty"`
	Subject         string         `json:"subject,omitempty"`
	Body            string         `json:"body,omitempty"`
	Pricing         PaymentPricing `json:"pricing"`
	NotifyURL       string         `json:"notify_url,omitempty"`
	ReturnURL       string         `json:"return_url,omitempty"`
	ExpireAt        *time.Time     `json:"expire_at,omitempty"`
	Extra           map[string]any `json:"extra,omitempty"`
}

type CreatePaymentResponse

type CreatePaymentResponse struct {
	ExpireAt           *time.Time          `json:"expire_at,omitempty"`
	PaidAt             *time.Time          `json:"paid_at,omitempty"`
	ProviderSettlement *ProviderSettlement `json:"provider_settlement,omitempty"`
	Provider           Provider            `json:"provider"`
	Channel            Channel             `json:"channel"`
	MerchantKey        string              `json:"merchant_key,omitempty"`
	PaymentID          string              `json:"payment_id,omitempty"`
	OrderID            string              `json:"order_id,omitempty"`
	OutTradeNo         string              `json:"out_trade_no,omitempty"`
	ProviderTradeID    string              `json:"provider_trade_id,omitempty"`
	Status             PaymentStatus       `json:"status"`
	Pricing            PaymentPricing      `json:"pricing"`
	Action             PaymentAction       `json:"action"`
	Raw                any                 `json:"raw,omitempty"`
	Extra              map[string]any      `json:"extra,omitempty"`
}

type CreatePayoutBatchRequest added in v0.1.13

type CreatePayoutBatchRequest struct {
	Provider    Provider `json:"provider"`
	Channel     Channel  `json:"channel"`
	MerchantKey string   `json:"merchant_key,omitempty"`
	RequestID   string   `json:"request_id"`
	Name        string   `json:"name,omitempty"`
	Remarks     string   `json:"remarks,omitempty"`
}

type CreatePayoutRequest added in v0.1.10

type CreatePayoutRequest struct {
	Provider      Provider       `json:"provider"`
	Channel       Channel        `json:"channel"`
	MerchantKey   string         `json:"merchant_key,omitempty"`
	PayoutID      string         `json:"payout_id"`
	RequestID     string         `json:"request_id"`
	BeneficiaryID string         `json:"beneficiary_id"`
	Amount        Money          `json:"amount"`
	Reference     string         `json:"reference,omitempty"`
	Reason        string         `json:"reason,omitempty"`
	Extra         map[string]any `json:"extra,omitempty"`
}

type CurrencyMeta

type CurrencyMeta struct {
	Code     string
	MinorExp int
}

func DefaultCurrencyMeta

func DefaultCurrencyMeta(code string) (CurrencyMeta, bool)

type DefaultPricingPolicy

type DefaultPricingPolicy struct {
	DefaultSettleCurrency string
	Currencies            map[string]CurrencyMeta
	AllowExplicitSettle   bool
}

func NewDefaultPricingPolicy

func NewDefaultPricingPolicy() DefaultPricingPolicy

func (DefaultPricingPolicy) NormalizePricing

func (p DefaultPricingPolicy) NormalizePricing(ctx context.Context, pricing PaymentPricing) (PaymentPricing, error)

type EventType

type EventType string
const (
	EventPaymentCreated    EventType = "payment.created"
	EventPaymentSucceeded  EventType = "payment.succeeded"
	EventPaymentFailed     EventType = "payment.failed"
	EventPaymentClosed     EventType = "payment.closed"
	EventPaymentExpired    EventType = "payment.expired"
	EventPaymentAuthorized EventType = "payment.authorized"
	EventPaymentCaptured   EventType = "payment.captured"
	EventPaymentRefunding  EventType = "payment.refunding"
	EventPaymentRefunded   EventType = "payment.refunded"
	EventPaymentPartRefund EventType = "payment.partial_refunded"
	EventRefundCreated     EventType = "refund.created"
	EventRefundProcessing  EventType = "refund.processing"
	EventRefundSucceeded   EventType = "refund.succeeded"
	EventRefundFailed      EventType = "refund.failed"
	EventDisputeCreated    EventType = "dispute.created"
	EventDisputeClosed     EventType = "dispute.closed"
	EventUnknown           EventType = "unknown"
)

type ExchangeRateSnapshot

type ExchangeRateSnapshot struct {
	FromCurrency string `json:"from_currency"`
	ToCurrency   string `json:"to_currency"`
	Rate         string `json:"rate"`
	Source       string `json:"source"`
	QuotedAt     int64  `json:"quoted_at"`
}

type GenerateBeneficiarySchemaRequest added in v0.1.15

type GenerateBeneficiarySchemaRequest struct {
	Provider            Provider              `json:"provider"`
	Channel             Channel               `json:"channel"`
	MerchantKey         string                `json:"merchant_key,omitempty"`
	Kind                BeneficiarySchemaKind `json:"kind"`
	BankCountryCode     string                `json:"bank_country_code,omitempty"`
	AccountCurrency     string                `json:"account_currency,omitempty"`
	TransferMethod      string                `json:"transfer_method,omitempty"`
	LocalClearingSystem string                `json:"local_clearing_system,omitempty"`
	EntityType          string                `json:"entity_type,omitempty"`
	CountryCode         string                `json:"country_code,omitempty"`
}

type ListPayoutBatchItemsRequest added in v0.1.13

type ListPayoutBatchItemsRequest = SubmitPayoutBatchRequest

type Money

type Money struct {
	Amount   int64  `json:"amount"`
	Currency string `json:"currency"`
}

type NotifyAck

type NotifyAck struct {
	StatusCode  int    `json:"status_code"`
	ContentType string `json:"content_type,omitempty"`
	Body        []byte `json:"body,omitempty"`
}

type NotifyRequest

type NotifyRequest struct {
	// MerchantKey is selected by the trusted callback route, never by an unverified payload.
	MerchantKey string              `json:"merchant_key,omitempty"`
	Provider    Provider            `json:"provider"`
	Channel     Channel             `json:"channel"`
	Method      string              `json:"method,omitempty"`
	Header      map[string][]string `json:"header,omitempty"`
	Query       map[string][]string `json:"query,omitempty"`
	Form        map[string][]string `json:"form,omitempty"`
	Body        []byte              `json:"body,omitempty"`
	Raw         any                 `json:"-"`
	ReceivedAt  time.Time           `json:"received_at"`
}

type NotifyResult

type NotifyResult struct {
	Verified bool          `json:"verified"`
	Event    *PaymentEvent `json:"event,omitempty"`
	Ack      NotifyAck     `json:"ack"`
}

func HandleNotify

func HandleNotify(ctx context.Context, req NotifyRequest) (*NotifyResult, error)

type PaymentAction

type PaymentAction struct {
	Type        ActionType        `json:"type"`
	Method      string            `json:"method,omitempty"`
	URL         string            `json:"url,omitempty"`
	Fields      map[string]string `json:"fields,omitempty"`
	HTML        string            `json:"html,omitempty"`
	EncodedHTML string            `json:"encoded_html,omitempty"`
	Token       string            `json:"token,omitempty"`
	Params      map[string]any    `json:"params,omitempty"`
}

type PaymentDetails added in v0.1.12

type PaymentDetails struct {
	Method        string `json:"method,omitempty"`
	AttemptID     string `json:"attempt_id,omitempty"`
	TransactionID string `json:"transaction_id,omitempty"`
	CardBrand     string `json:"card_brand,omitempty"`
	CardLast4     string `json:"card_last4,omitempty"`
}

PaymentDetails contains only provider-confirmed, non-secret payment facts. An intent ID is not an attempt ID or an underlying method transaction ID.

type PaymentEvent

type PaymentEvent struct {
	Details            *PaymentDetails     `json:"details,omitempty"`
	ExpireAt           *time.Time          `json:"expire_at,omitempty"`
	ProviderSettlement *ProviderSettlement `json:"provider_settlement,omitempty"`
	EventID            string              `json:"event_id"`
	Type               EventType           `json:"type"`
	Provider           Provider            `json:"provider"`
	Channel            Channel             `json:"channel"`
	MerchantKey        string              `json:"merchant_key,omitempty"`
	PaymentID          string              `json:"payment_id,omitempty"`
	OrderID            string              `json:"order_id,omitempty"`
	OutTradeNo         string              `json:"out_trade_no,omitempty"`
	ProviderTradeID    string              `json:"provider_trade_id,omitempty"`
	RefundID           string              `json:"refund_id,omitempty"`
	ProviderRefundID   string              `json:"provider_refund_id,omitempty"`
	Status             PaymentStatus       `json:"status,omitempty"`
	RefundStatus       RefundStatus        `json:"refund_status,omitempty"`
	Amount             Money               `json:"amount"`
	PaidAt             *time.Time          `json:"paid_at,omitempty"`
	Raw                []byte              `json:"raw,omitempty"`
	Extra              map[string]any      `json:"extra,omitempty"`
}

func EventFromQueryPaymentResponse

func EventFromQueryPaymentResponse(resp *QueryPaymentResponse) *PaymentEvent

func EventFromQueryRefundResponse

func EventFromQueryRefundResponse(resp *QueryRefundResponse) *PaymentEvent

func (*PaymentEvent) ValidateIdentity added in v0.1.10

func (event *PaymentEvent) ValidateIdentity(expected PaymentEvent) error

ValidateIdentity checks a verified or queried receipt against the original payment. expected.Extra may bind provider-specific account_id and environment values. This does not verify a webhook signature or validate the amount.

type PaymentOperation

type PaymentOperation string
const (
	PaymentOperationCreate      PaymentOperation = "create"
	PaymentOperationQuery       PaymentOperation = "query"
	PaymentOperationClose       PaymentOperation = "close"
	PaymentOperationRefund      PaymentOperation = "refund"
	PaymentOperationQueryRefund PaymentOperation = "query_refund"
)

type PaymentPricing

type PaymentPricing struct {
	OrderAmount    Money                 `json:"order_amount"`
	PayAmount      Money                 `json:"pay_amount"`
	SettleCurrency string                `json:"settle_currency,omitempty"`
	SettleAmount   Money                 `json:"settle_amount"`
	FeeAmount      *Money                `json:"fee_amount,omitempty"`
	ExchangeRate   *ExchangeRateSnapshot `json:"exchange_rate,omitempty"`
}

func CNY

func CNY(amount int64) PaymentPricing

func NormalizePricing

func NormalizePricing(ctx context.Context, pricing PaymentPricing) (PaymentPricing, error)

type PaymentStatus

type PaymentStatus string
const (
	PaymentPending        PaymentStatus = "pending"
	PaymentProcessing     PaymentStatus = "processing"
	PaymentRequiresAction PaymentStatus = "requires_action"
	PaymentAuthorized     PaymentStatus = "authorized"
	PaymentSucceeded      PaymentStatus = "succeeded"
	PaymentFailed         PaymentStatus = "failed"
	PaymentClosed         PaymentStatus = "closed"
	// PaymentExpired is an expiry confirmed by the provider, not a local timer.
	PaymentExpired         PaymentStatus = "expired"
	PaymentRefunding       PaymentStatus = "refunding"
	PaymentPartialRefunded PaymentStatus = "partial_refunded"
	PaymentRefunded        PaymentStatus = "refunded"
)

func StatusFromEvent

func StatusFromEvent(event PaymentEvent) PaymentStatus

type PayoutBatchItemRequest added in v0.1.13

type PayoutBatchItemRequest struct {
	RequestID      string `json:"request_id"`
	BeneficiaryID  string `json:"beneficiary_id"`
	Amount         Money  `json:"amount"`
	TransferMethod string `json:"transfer_method"`
	Reference      string `json:"reference"`
	Reason         string `json:"reason"`
}

type PayoutBatchItemResponse added in v0.1.13

type PayoutBatchItemResponse struct {
	ProviderItemID   string `json:"provider_item_id"`
	ProviderPayoutID string `json:"provider_payout_id,omitempty"`
	RequestID        string `json:"request_id"`
	ProviderStatus   string `json:"provider_status"`
	FailureCode      string `json:"failure_code,omitempty"`
	FailureMessage   string `json:"failure_message,omitempty"`
}

type PayoutBatchItemsResponse added in v0.1.13

type PayoutBatchItemsResponse struct {
	Provider        Provider                  `json:"provider"`
	Channel         Channel                   `json:"channel"`
	MerchantKey     string                    `json:"merchant_key,omitempty"`
	ProviderBatchID string                    `json:"provider_batch_id"`
	Items           []PayoutBatchItemResponse `json:"items"`
	Exchange        ProviderExchange          `json:"-"`
}

func ListPayoutBatchItems added in v0.1.13

type PayoutBatchResponse added in v0.1.13

type PayoutBatchResponse struct {
	Provider        Provider         `json:"provider"`
	Channel         Channel          `json:"channel"`
	MerchantKey     string           `json:"merchant_key,omitempty"`
	ProviderBatchID string           `json:"provider_batch_id"`
	ProviderStatus  string           `json:"provider_status"`
	TotalItemCount  int              `json:"total_item_count"`
	ValidItemCount  int              `json:"valid_item_count"`
	Exchange        ProviderExchange `json:"-"`
}

func AddPayoutBatchItems added in v0.1.13

func AddPayoutBatchItems(ctx context.Context, req AddPayoutBatchItemsRequest) (*PayoutBatchResponse, error)

func CreatePayoutBatch added in v0.1.13

func CreatePayoutBatch(ctx context.Context, req CreatePayoutBatchRequest) (*PayoutBatchResponse, error)

func QueryPayoutBatch added in v0.1.13

func QueryPayoutBatch(ctx context.Context, req QueryPayoutBatchRequest) (*PayoutBatchResponse, error)

func SubmitPayoutBatch added in v0.1.13

func SubmitPayoutBatch(ctx context.Context, req SubmitPayoutBatchRequest) (*PayoutBatchResponse, error)

type PayoutProvider added in v0.1.10

type PayoutProvider interface {
	CreatePayout(context.Context, CreatePayoutRequest) (*PayoutResponse, error)
	QueryPayout(context.Context, QueryPayoutRequest) (*PayoutResponse, error)
}

PayoutProvider is optional; ordinary payment adapters do not need to implement it.

type PayoutResponse added in v0.1.10

type PayoutResponse struct {
	Provider         Provider         `json:"provider"`
	Channel          Channel          `json:"channel"`
	MerchantKey      string           `json:"merchant_key,omitempty"`
	PayoutID         string           `json:"payout_id,omitempty"`
	ProviderPayoutID string           `json:"provider_payout_id"`
	Status           PayoutStatus     `json:"status"`
	Amount           Money            `json:"amount"`
	ProviderStatus   string           `json:"provider_status,omitempty"`
	Exchange         ProviderExchange `json:"-"`
}

func CreatePayout added in v0.1.10

func CreatePayout(ctx context.Context, req CreatePayoutRequest) (*PayoutResponse, error)

func QueryPayout added in v0.1.10

func QueryPayout(ctx context.Context, req QueryPayoutRequest) (*PayoutResponse, error)

type PayoutStatus added in v0.1.10

type PayoutStatus string
const (
	PayoutPending    PayoutStatus = "pending"
	PayoutProcessing PayoutStatus = "processing"
	PayoutSent       PayoutStatus = "sent"
	PayoutSucceeded  PayoutStatus = "succeeded"
	PayoutFailed     PayoutStatus = "failed"
	PayoutCancelled  PayoutStatus = "cancelled"
	PayoutReturned   PayoutStatus = "returned"
)

type PricingPolicy

type PricingPolicy interface {
	NormalizePricing(ctx context.Context, pricing PaymentPricing) (PaymentPricing, error)
}

type Provider

type Provider string
const (
	ProviderWechat    Provider = "wechat"
	ProviderAlipay    Provider = "alipay"
	ProviderPayPal    Provider = "paypal"
	ProviderStripe    Provider = "stripe"
	ProviderAggregate Provider = "aggregate"
)
const ProviderAirwallex Provider = "airwallex"

type ProviderAdapter

type ProviderAdapter interface {
	Name() Provider
	Capabilities() Capabilities
	CreatePayment(ctx context.Context, req CreatePaymentRequest) (*CreatePaymentResponse, error)
	QueryPayment(ctx context.Context, req QueryPaymentRequest) (*QueryPaymentResponse, error)
	ClosePayment(ctx context.Context, req ClosePaymentRequest) error
	Refund(ctx context.Context, req RefundRequest) (*RefundResponse, error)
	QueryRefund(ctx context.Context, req QueryRefundRequest) (*QueryRefundResponse, error)
	ParseNotify(ctx context.Context, req NotifyRequest) (*NotifyResult, error)
}

type ProviderExchange added in v0.1.13

type ProviderExchange struct {
	RequestBody  []byte              `json:"-"`
	ResponseBody []byte              `json:"-"`
	StatusCode   int                 `json:"-"`
	Headers      map[string][]string `json:"-"`
}

ProviderExchange is the credential-free HTTP evidence returned by a provider adapter. Request and response bytes are kept out of ordinary JSON projections and application logs.

func ProviderExchangeFromError added in v0.1.13

func ProviderExchangeFromError(err error) (ProviderExchange, bool)

ProviderExchangeFromError extracts provider evidence from a failed call.

type ProviderSettlement added in v0.1.10

type ProviderSettlement struct {
	Currency     string                `json:"currency,omitempty"`
	Amount       *Money                `json:"amount,omitempty"`
	NetAmount    *Money                `json:"net_amount,omitempty"`
	FeeAmount    *Money                `json:"fee_amount,omitempty"`
	ExchangeRate *ExchangeRateSnapshot `json:"exchange_rate,omitempty"`
	Reference    string                `json:"reference,omitempty"`
	UpdatedAt    *time.Time            `json:"updated_at,omitempty"`
}

ProviderSettlement contains only facts supplied by the provider. It is optional and must never be populated from caller-side Pricing calculations.

func MergeProviderSettlement added in v0.1.10

func MergeProviderSettlement(current, incoming *ProviderSettlement) *ProviderSettlement

MergeProviderSettlement preserves optional fields and rejects older/conflicting updates. Neither input is modified. It never calculates settlement amounts or exchange rates.

type QueryBeneficiaryRequest added in v0.1.13

type QueryBeneficiaryRequest struct {
	Provider      Provider `json:"provider"`
	Channel       Channel  `json:"channel"`
	MerchantKey   string   `json:"merchant_key,omitempty"`
	BeneficiaryID string   `json:"beneficiary_id"`
}

type QueryPaymentRequest

type QueryPaymentRequest struct {
	Provider        Provider       `json:"provider"`
	Channel         Channel        `json:"channel"`
	MerchantKey     string         `json:"merchant_key,omitempty"`
	PaymentID       string         `json:"payment_id,omitempty"`
	OrderID         string         `json:"order_id,omitempty"`
	OutTradeNo      string         `json:"out_trade_no,omitempty"`
	ProviderTradeID string         `json:"provider_trade_id,omitempty"`
	Extra           map[string]any `json:"extra,omitempty"`
}

type QueryPaymentResponse

type QueryPaymentResponse struct {
	// RawBody preserves provider HTTP bytes for private accounting evidence.
	// Never serialize it to browser responses or application logs.
	RawBody            []byte              `json:"-"`
	Details            *PaymentDetails     `json:"details,omitempty"`
	ExpireAt           *time.Time          `json:"expire_at,omitempty"`
	ProviderSettlement *ProviderSettlement `json:"provider_settlement,omitempty"`
	Provider           Provider            `json:"provider"`
	Channel            Channel             `json:"channel"`
	MerchantKey        string              `json:"merchant_key,omitempty"`
	PaymentID          string              `json:"payment_id,omitempty"`
	OrderID            string              `json:"order_id,omitempty"`
	OutTradeNo         string              `json:"out_trade_no,omitempty"`
	ProviderTradeID    string              `json:"provider_trade_id,omitempty"`
	Status             PaymentStatus       `json:"status"`
	Pricing            PaymentPricing      `json:"pricing"`
	PaidAt             *time.Time          `json:"paid_at,omitempty"`
	Raw                any                 `json:"raw,omitempty"`
	Extra              map[string]any      `json:"extra,omitempty"`
}

type QueryPayoutBatchRequest added in v0.1.13

type QueryPayoutBatchRequest struct {
	Provider        Provider `json:"provider"`
	Channel         Channel  `json:"channel"`
	MerchantKey     string   `json:"merchant_key,omitempty"`
	ProviderBatchID string   `json:"provider_batch_id,omitempty"`
	RequestID       string   `json:"request_id,omitempty"`
}

type QueryPayoutRequest added in v0.1.10

type QueryPayoutRequest struct {
	Provider         Provider `json:"provider"`
	Channel          Channel  `json:"channel"`
	MerchantKey      string   `json:"merchant_key,omitempty"`
	PayoutID         string   `json:"payout_id,omitempty"`
	ProviderPayoutID string   `json:"provider_payout_id"`
}

type QueryRefundRequest

type QueryRefundRequest struct {
	Provider         Provider       `json:"provider"`
	Channel          Channel        `json:"channel"`
	MerchantKey      string         `json:"merchant_key,omitempty"`
	PaymentID        string         `json:"payment_id,omitempty"`
	OutTradeNo       string         `json:"out_trade_no,omitempty"`
	ProviderTradeID  string         `json:"provider_trade_id,omitempty"`
	RefundID         string         `json:"refund_id,omitempty"`
	OutRefundNo      string         `json:"out_refund_no,omitempty"`
	ProviderRefundID string         `json:"provider_refund_id,omitempty"`
	Extra            map[string]any `json:"extra,omitempty"`
}

type QueryRefundResponse

type QueryRefundResponse struct {
	Provider         Provider         `json:"provider"`
	Channel          Channel          `json:"channel"`
	MerchantKey      string           `json:"merchant_key,omitempty"`
	PaymentID        string           `json:"payment_id,omitempty"`
	OutTradeNo       string           `json:"out_trade_no,omitempty"`
	ProviderTradeID  string           `json:"provider_trade_id,omitempty"`
	RefundID         string           `json:"refund_id,omitempty"`
	OutRefundNo      string           `json:"out_refund_no,omitempty"`
	ProviderRefundID string           `json:"provider_refund_id,omitempty"`
	Status           RefundStatus     `json:"status"`
	Amount           RefundAmount     `json:"amount"`
	Exchange         ProviderExchange `json:"-"`
	Raw              any              `json:"raw,omitempty"`
	Extra            map[string]any   `json:"extra,omitempty"`
}

type RefundAmount

type RefundAmount struct {
	Refund Money `json:"refund"`
	Settle Money `json:"settle"`
}

type RefundRequest

type RefundRequest struct {
	Provider        Provider       `json:"provider"`
	Channel         Channel        `json:"channel"`
	MerchantKey     string         `json:"merchant_key,omitempty"`
	PaymentID       string         `json:"payment_id,omitempty"`
	OrderID         string         `json:"order_id,omitempty"`
	OutTradeNo      string         `json:"out_trade_no,omitempty"`
	ProviderTradeID string         `json:"provider_trade_id,omitempty"`
	RefundID        string         `json:"refund_id,omitempty"`
	OutRefundNo     string         `json:"out_refund_no,omitempty"`
	Amount          RefundAmount   `json:"amount"`
	Reason          string         `json:"reason,omitempty"`
	Extra           map[string]any `json:"extra,omitempty"`
}

type RefundResponse

type RefundResponse struct {
	Provider         Provider         `json:"provider"`
	Channel          Channel          `json:"channel"`
	MerchantKey      string           `json:"merchant_key,omitempty"`
	PaymentID        string           `json:"payment_id,omitempty"`
	OrderID          string           `json:"order_id,omitempty"`
	OutTradeNo       string           `json:"out_trade_no,omitempty"`
	ProviderTradeID  string           `json:"provider_trade_id,omitempty"`
	RefundID         string           `json:"refund_id,omitempty"`
	OutRefundNo      string           `json:"out_refund_no,omitempty"`
	ProviderRefundID string           `json:"provider_refund_id,omitempty"`
	Status           RefundStatus     `json:"status"`
	Amount           RefundAmount     `json:"amount"`
	Exchange         ProviderExchange `json:"-"`
	Raw              any              `json:"raw,omitempty"`
	Extra            map[string]any   `json:"extra,omitempty"`
}

func Refund

func Refund(ctx context.Context, req RefundRequest) (*RefundResponse, error)

type RefundStatus

type RefundStatus string
const (
	RefundPending    RefundStatus = "pending"
	RefundProcessing RefundStatus = "processing"
	RefundSucceeded  RefundStatus = "succeeded"
	RefundFailed     RefundStatus = "failed"
	RefundClosed     RefundStatus = "closed"
)

type Registry

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

func NewRegistry

func NewRegistry() *Registry

func (*Registry) Adapter

func (r *Registry) Adapter(provider Provider) (ProviderAdapter, error)

func (*Registry) Adapters

func (r *Registry) Adapters() map[Provider]ProviderAdapter

func (*Registry) Register

func (r *Registry) Register(adapter ProviderAdapter) error

type ReloadableChannelSelector

type ReloadableChannelSelector interface {
	ChannelSelector
	Reload(bindings []ChannelBinding) error
}

type Service

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

func Default

func Default() (*Service, error)

func From

func From(app *runtime.App) *Service

func NewService

func NewService(cfg ServiceConfig) (*Service, error)

func (*Service) AddPayoutBatchItems added in v0.1.13

func (s *Service) AddPayoutBatchItems(ctx context.Context, req AddPayoutBatchItemsRequest) (*PayoutBatchResponse, error)

func (*Service) ClosePayment

func (s *Service) ClosePayment(ctx context.Context, req ClosePaymentRequest) error

func (*Service) CreateBeneficiary added in v0.1.13

func (s *Service) CreateBeneficiary(ctx context.Context, req CreateBeneficiaryRequest) (*BeneficiaryResponse, error)

func (*Service) CreatePayment

func (s *Service) CreatePayment(ctx context.Context, req CreatePaymentRequest) (*CreatePaymentResponse, error)

func (*Service) CreatePayout added in v0.1.10

func (s *Service) CreatePayout(ctx context.Context, req CreatePayoutRequest) (*PayoutResponse, error)

func (*Service) CreatePayoutBatch added in v0.1.13

func (s *Service) CreatePayoutBatch(ctx context.Context, req CreatePayoutBatchRequest) (*PayoutBatchResponse, error)

func (*Service) GenerateBeneficiarySchema added in v0.1.15

func (s *Service) GenerateBeneficiarySchema(ctx context.Context, req GenerateBeneficiarySchemaRequest) (*BeneficiarySchemaResponse, error)

func (*Service) HandleNotify

func (s *Service) HandleNotify(ctx context.Context, req NotifyRequest) (*NotifyResult, error)

func (*Service) ListPayoutBatchItems added in v0.1.13

func (s *Service) ListPayoutBatchItems(ctx context.Context, req ListPayoutBatchItemsRequest) (*PayoutBatchItemsResponse, error)

func (*Service) QueryBeneficiary added in v0.1.13

func (s *Service) QueryBeneficiary(ctx context.Context, req QueryBeneficiaryRequest) (*BeneficiaryResponse, error)

func (*Service) QueryPayment

func (s *Service) QueryPayment(ctx context.Context, req QueryPaymentRequest) (*QueryPaymentResponse, error)

func (*Service) QueryPayout added in v0.1.10

func (s *Service) QueryPayout(ctx context.Context, req QueryPayoutRequest) (*PayoutResponse, error)

func (*Service) QueryPayoutBatch added in v0.1.13

func (s *Service) QueryPayoutBatch(ctx context.Context, req QueryPayoutBatchRequest) (*PayoutBatchResponse, error)

func (*Service) QueryRefund

func (s *Service) QueryRefund(ctx context.Context, req QueryRefundRequest) (*QueryRefundResponse, error)

func (*Service) Refund

func (s *Service) Refund(ctx context.Context, req RefundRequest) (*RefundResponse, error)

func (*Service) RegisterProvider added in v0.1.10

func (s *Service) RegisterProvider(adapter ProviderAdapter) error

RegisterProvider adds a provider to the running service. Duplicate names are rejected so that an in-flight operation cannot silently change implementation.

func (*Service) ReloadChannels

func (s *Service) ReloadChannels(bindings []ChannelBinding) error

func (*Service) SubmitPayoutBatch added in v0.1.13

func (s *Service) SubmitPayoutBatch(ctx context.Context, req SubmitPayoutBatchRequest) (*PayoutBatchResponse, error)

type ServiceConfig

type ServiceConfig struct {
	Registry        *Registry
	PricingPolicy   PricingPolicy
	ChannelSelector ChannelSelector
}

type StaticChannelSelector

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

func NewStaticChannelSelector

func NewStaticChannelSelector(bindings []ChannelBinding) (*StaticChannelSelector, error)

func (*StaticChannelSelector) Reload

func (s *StaticChannelSelector) Reload(bindings []ChannelBinding) error

func (*StaticChannelSelector) SelectPaymentChannel

type SubmitPayoutBatchRequest added in v0.1.13

type SubmitPayoutBatchRequest struct {
	Provider        Provider `json:"provider"`
	Channel         Channel  `json:"channel"`
	MerchantKey     string   `json:"merchant_key,omitempty"`
	ProviderBatchID string   `json:"provider_batch_id"`
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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