Documentation
¶
Index ¶
- Constants
- Variables
- func Bind(app *runtime.App, service *Service) error
- func CanTransitionPaymentStatus(from, to PaymentStatus) bool
- func Close()
- func ClosePayment(ctx context.Context, req ClosePaymentRequest) error
- func DefaultCurrencyMetadata() map[string]CurrencyMeta
- func IsPaymentClosed(status PaymentStatus) bool
- func IsPaymentExpired(local, provider *time.Time, now time.Time) bool
- func NormalizeCurrency(code string) string
- func PaymentDeadline(local, provider *time.Time) *time.Time
- func RegisterProvider(adapter ProviderAdapter) error
- func ReloadChannels(bindings []ChannelBinding) error
- func SetDefault(service *Service)
- func WithProviderExchange(err error, exchange ProviderExchange) error
- type ActionType
- type AddPayoutBatchItemsRequest
- type BatchPayoutProvider
- type BeneficiaryProvider
- type BeneficiaryResponse
- type BeneficiarySchemaKind
- type BeneficiarySchemaProvider
- type BeneficiarySchemaResponse
- type Capabilities
- type Channel
- type ChannelBinding
- type ChannelSelection
- type ChannelSelectionRequest
- type ChannelSelector
- type ClosePaymentRequest
- type CreateBeneficiaryRequest
- type CreatePaymentRequest
- type CreatePaymentResponse
- type CreatePayoutBatchRequest
- type CreatePayoutRequest
- type CurrencyMeta
- type DefaultPricingPolicy
- type EventType
- type ExchangeRateSnapshot
- type GenerateBeneficiarySchemaRequest
- type ListPayoutBatchItemsRequest
- type Money
- type NotifyAck
- type NotifyRequest
- type NotifyResult
- type PaymentAction
- type PaymentDetails
- type PaymentEvent
- type PaymentOperation
- type PaymentPricing
- type PaymentStatus
- type PayoutBatchItemRequest
- type PayoutBatchItemResponse
- type PayoutBatchItemsResponse
- type PayoutBatchResponse
- func AddPayoutBatchItems(ctx context.Context, req AddPayoutBatchItemsRequest) (*PayoutBatchResponse, error)
- func CreatePayoutBatch(ctx context.Context, req CreatePayoutBatchRequest) (*PayoutBatchResponse, error)
- func QueryPayoutBatch(ctx context.Context, req QueryPayoutBatchRequest) (*PayoutBatchResponse, error)
- func SubmitPayoutBatch(ctx context.Context, req SubmitPayoutBatchRequest) (*PayoutBatchResponse, error)
- type PayoutProvider
- type PayoutResponse
- type PayoutStatus
- type PricingPolicy
- type Provider
- type ProviderAdapter
- type ProviderExchange
- type ProviderSettlement
- type QueryBeneficiaryRequest
- type QueryPaymentRequest
- type QueryPaymentResponse
- type QueryPayoutBatchRequest
- type QueryPayoutRequest
- type QueryRefundRequest
- type QueryRefundResponse
- type RefundAmount
- type RefundRequest
- type RefundResponse
- type RefundStatus
- type Registry
- type ReloadableChannelSelector
- type Service
- func (s *Service) AddPayoutBatchItems(ctx context.Context, req AddPayoutBatchItemsRequest) (*PayoutBatchResponse, error)
- func (s *Service) ClosePayment(ctx context.Context, req ClosePaymentRequest) error
- func (s *Service) CreateBeneficiary(ctx context.Context, req CreateBeneficiaryRequest) (*BeneficiaryResponse, error)
- func (s *Service) CreatePayment(ctx context.Context, req CreatePaymentRequest) (*CreatePaymentResponse, error)
- func (s *Service) CreatePayout(ctx context.Context, req CreatePayoutRequest) (*PayoutResponse, error)
- func (s *Service) CreatePayoutBatch(ctx context.Context, req CreatePayoutBatchRequest) (*PayoutBatchResponse, error)
- func (s *Service) GenerateBeneficiarySchema(ctx context.Context, req GenerateBeneficiarySchemaRequest) (*BeneficiarySchemaResponse, error)
- func (s *Service) HandleNotify(ctx context.Context, req NotifyRequest) (*NotifyResult, error)
- func (s *Service) ListPayoutBatchItems(ctx context.Context, req ListPayoutBatchItemsRequest) (*PayoutBatchItemsResponse, error)
- func (s *Service) QueryBeneficiary(ctx context.Context, req QueryBeneficiaryRequest) (*BeneficiaryResponse, error)
- func (s *Service) QueryPayment(ctx context.Context, req QueryPaymentRequest) (*QueryPaymentResponse, error)
- func (s *Service) QueryPayout(ctx context.Context, req QueryPayoutRequest) (*PayoutResponse, error)
- func (s *Service) QueryPayoutBatch(ctx context.Context, req QueryPayoutBatchRequest) (*PayoutBatchResponse, error)
- func (s *Service) QueryRefund(ctx context.Context, req QueryRefundRequest) (*QueryRefundResponse, error)
- func (s *Service) Refund(ctx context.Context, req RefundRequest) (*RefundResponse, error)
- func (s *Service) RegisterProvider(adapter ProviderAdapter) error
- func (s *Service) ReloadChannels(bindings []ChannelBinding) error
- func (s *Service) SubmitPayoutBatch(ctx context.Context, req SubmitPayoutBatchRequest) (*PayoutBatchResponse, error)
- type ServiceConfig
- type StaticChannelSelector
- type SubmitPayoutBatchRequest
Constants ¶
const DefaultCurrency = "CNY"
const KeyPayment runtime.Key = "payment"
Variables ¶
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 CanTransitionPaymentStatus ¶
func CanTransitionPaymentStatus(from, to PaymentStatus) bool
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
PaymentExpired does not imply that the provider has closed the payment.
func NormalizeCurrency ¶
func PaymentDeadline ¶ added in v0.1.10
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 BatchPayoutProvider ¶ added in v0.1.13
type BatchPayoutProvider interface {
CreatePayoutBatch(context.Context, CreatePayoutBatchRequest) (*PayoutBatchResponse, error)
AddPayoutBatchItems(context.Context, AddPayoutBatchItemsRequest) (*PayoutBatchResponse, error)
SubmitPayoutBatch(context.Context, SubmitPayoutBatchRequest) (*PayoutBatchResponse, error)
QueryPayoutBatch(context.Context, QueryPayoutBatchRequest) (*PayoutBatchResponse, error)
ListPayoutBatchItems(context.Context, ListPayoutBatchItemsRequest) (*PayoutBatchItemsResponse, error)
}
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 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 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"`
}
func CreatePayment ¶
func CreatePayment(ctx context.Context, req CreatePaymentRequest) (*CreatePaymentResponse, error)
type CreatePayoutBatchRequest ¶ added in v0.1.13
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 ¶
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 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 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 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
func ListPayoutBatchItems(ctx context.Context, req ListPayoutBatchItemsRequest) (*PayoutBatchItemsResponse, error)
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 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 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"`
}
func QueryPayment ¶
func QueryPayment(ctx context.Context, req QueryPaymentRequest) (*QueryPaymentResponse, error)
type QueryPayoutBatchRequest ¶ added in v0.1.13
type QueryPayoutRequest ¶ added in v0.1.10
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"`
}
func QueryRefund ¶
func QueryRefund(ctx context.Context, req QueryRefundRequest) (*QueryRefundResponse, error)
type RefundAmount ¶
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) 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 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 ¶
func (s *StaticChannelSelector) SelectPaymentChannel(ctx context.Context, req ChannelSelectionRequest) (*ChannelSelection, error)