Documentation ¶
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Account ¶
type Account string
Account * `AVAILABLE` - 可用余额, 多账户资金准备退款可用余额出资账户类型 * `UNAVAILABLE` - 不可用余额, 多账户资金准备退款不可用余额出资账户类型
Enums of Account
type Amount ¶
type Amount struct { // 订单总金额,单位为分 Total *int64 `json:"total"` // 退款标价金额,单位为分,可以做部分退款 Refund *int64 `json:"refund"` // 退款出资的账户类型及金额信息 From []FundsFromItem `json:"from,omitempty"` // 现金支付金额,单位为分,只能为整数 PayerTotal *int64 `json:"payer_total"` // 退款给用户的金额,不包含所有优惠券金额 PayerRefund *int64 `json:"payer_refund"` // 去掉非充值代金券退款金额后的退款金额,单位为分,退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额 SettlementRefund *int64 `json:"settlement_refund"` // 应结订单金额=订单金额-免充值代金券金额,应结订单金额<=订单金额,单位为分 SettlementTotal *int64 `json:"settlement_total"` // 优惠退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠,单位为分 DiscountRefund *int64 `json:"discount_refund"` // 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY。 Currency *string `json:"currency"` }
Amount
func (Amount) MarshalJSON ¶
type AmountReq ¶
type AmountReq struct { // 退款金额,币种的最小单位,只能为整数,不能超过原订单支付金额。 Refund *int64 `json:"refund"` // 退款需要从指定账户出资时,传递此参数指定出资金额(币种的最小单位,只能为整数)。 同时指定多个账户出资退款的使用场景需要满足以下条件:1、未开通退款支出分离产品功能;2、订单属于分账订单,且分账处于待分账或分账中状态。 参数传递需要满足条件:1、基本账户可用余额出资金额与基本账户不可用余额出资金额之和等于退款金额;2、账户类型不能重复。 上述任一条件不满足将返回错误 From []FundsFromItem `json:"from,omitempty"` // 原支付交易的订单总金额,币种的最小单位,只能为整数。 Total *int64 `json:"total"` // 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY。 Currency *string `json:"currency"` }
AmountReq
func (AmountReq) MarshalJSON ¶
type Channel ¶
type Channel string
Channel * `ORIGINAL` - 原路退款, 退款渠道 * `BALANCE` - 退回到余额, 退款渠道 * `OTHER_BALANCE` - 原账户异常退到其他余额账户, 退款渠道 * `OTHER_BANKCARD` - 原银行卡异常退到其他银行卡, 退款渠道
type CreateRequest ¶
type CreateRequest struct { // 子商户的商户号,由微信支付生成并下发。服务商模式下必须传递此参数 SubMchid *string `json:"sub_mchid,omitempty"` // 原支付交易对应的微信订单号 TransactionId *string `json:"transaction_id,omitempty"` // 原支付交易对应的商户订单号 OutTradeNo *string `json:"out_trade_no,omitempty"` // 商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。 OutRefundNo *string `json:"out_refund_no"` // 若商户传入,会在下发给用户的退款消息中体现退款原因 Reason *string `json:"reason,omitempty"` // 异步接收微信支付退款结果通知的回调地址,通知url必须为外网可访问的url,不能携带参数。 如果参数中传了notify_url,则商户平台上配置的回调地址将不会生效,优先回调当前传的这个地址。 NotifyUrl *string `json:"notify_url,omitempty"` // 若传递此参数则使用对应的资金账户退款,否则默认使用未结算资金退款(仅对老资金流商户适用) 枚举值: - AVAILABLE:可用余额账户 * `AVAILABLE` - 可用余额 FundsAccount *ReqFundsAccount `json:"funds_account,omitempty"` // 订单金额信息 Amount *AmountReq `json:"amount"` // 指定商品退款需要传此参数,其他场景无需传递 GoodsDetail []GoodsDetail `json:"goods_detail,omitempty"` }
CreateRequest
func (CreateRequest) Clone ¶
func (o CreateRequest) Clone() *CreateRequest
func (CreateRequest) MarshalJSON ¶
func (o CreateRequest) MarshalJSON() ([]byte, error)
func (CreateRequest) String ¶
func (o CreateRequest) String() string
type FundsAccount ¶
type FundsAccount string
FundsAccount * `UNSETTLED` - 未结算资金, 退款所使用资金对应的资金账户类型 * `AVAILABLE` - 可用余额, 退款所使用资金对应的资金账户类型 * `UNAVAILABLE` - 不可用余额, 退款所使用资金对应的资金账户类型 * `OPERATION` - 运营户, 退款所使用资金对应的资金账户类型 * `BASIC` - 基本账户(含可用余额和不可用余额), 退款所使用资金对应的资金账户类型
const ( FUNDSACCOUNT_UNSETTLED FundsAccount = "UNSETTLED" FUNDSACCOUNT_AVAILABLE FundsAccount = "AVAILABLE" FUNDSACCOUNT_UNAVAILABLE FundsAccount = "UNAVAILABLE" FUNDSACCOUNT_OPERATION FundsAccount = "OPERATION" FUNDSACCOUNT_BASIC FundsAccount = "BASIC" )
Enums of FundsAccount
func (FundsAccount) Ptr ¶
func (e FundsAccount) Ptr() *FundsAccount
type FundsFromItem ¶
type FundsFromItem struct { // 下面枚举值多选一。 枚举值: AVAILABLE : 可用余额 UNAVAILABLE : 不可用余额 * `AVAILABLE` - 可用余额 * `UNAVAILABLE` - 不可用余额 Account *Account `json:"account"` // 对应账户出资金额 Amount *int64 `json:"amount"` }
FundsFromItem
func (FundsFromItem) Clone ¶
func (o FundsFromItem) Clone() *FundsFromItem
func (FundsFromItem) MarshalJSON ¶
func (o FundsFromItem) MarshalJSON() ([]byte, error)
func (FundsFromItem) String ¶
func (o FundsFromItem) String() string
type GoodsDetail ¶
type GoodsDetail struct { // 由半角的大小写字母、数字、中划线、下划线中的一种或几种组成 MerchantGoodsId *string `json:"merchant_goods_id"` // 微信支付定义的统一商品编号(没有可不传) WechatpayGoodsId *string `json:"wechatpay_goods_id,omitempty"` // 商品的实际名称 GoodsName *string `json:"goods_name,omitempty"` // 商品单价金额,单位为分 UnitPrice *int64 `json:"unit_price"` // 商品退款金额,单位为分 RefundAmount *int64 `json:"refund_amount"` // 对应商品的退货数量 RefundQuantity *int64 `json:"refund_quantity"` }
GoodsDetail
func (GoodsDetail) Clone ¶
func (o GoodsDetail) Clone() *GoodsDetail
func (GoodsDetail) MarshalJSON ¶
func (o GoodsDetail) MarshalJSON() ([]byte, error)
func (GoodsDetail) String ¶
func (o GoodsDetail) String() string
type Promotion ¶
type Promotion struct { // 券或者立减优惠id PromotionId *string `json:"promotion_id"` // 枚举值: - GLOBAL- 全场代金券 - SINGLE- 单品优惠 * `GLOBAL` - 全场代金券 * `SINGLE` - 单品优惠 Scope *Scope `json:"scope"` // 枚举值: - COUPON- 代金券,需要走结算资金的充值型代金券 - DISCOUNT- 优惠券,不走结算资金的免充值型优惠券 * `COUPON` - 代金券 * `DISCOUNT` - 优惠券 Type *Type `json:"type"` // 用户享受优惠的金额(优惠券面额=微信出资金额+商家出资金额+其他出资方金额 ),单位为分 Amount *int64 `json:"amount"` // 优惠退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为用户支付的现金,说明详见代金券或立减优惠,单位为分 RefundAmount *int64 `json:"refund_amount"` // 优惠商品发生退款时返回商品信息 GoodsDetail []GoodsDetail `json:"goods_detail,omitempty"` }
Promotion
func (Promotion) MarshalJSON ¶
type QueryByOutRefundNoRequest ¶
type QueryByOutRefundNoRequest struct { // 商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。 OutRefundNo *string `json:"out_refund_no"` // 子商户的商户号,由微信支付生成并下发。服务商模式下必须传递此参数 SubMchid *string `json:"sub_mchid,omitempty"` }
QueryByOutRefundNoRequest
func (QueryByOutRefundNoRequest) Clone ¶
func (o QueryByOutRefundNoRequest) Clone() *QueryByOutRefundNoRequest
func (QueryByOutRefundNoRequest) MarshalJSON ¶
func (o QueryByOutRefundNoRequest) MarshalJSON() ([]byte, error)
func (QueryByOutRefundNoRequest) String ¶
func (o QueryByOutRefundNoRequest) String() string
type Refund ¶
type Refund struct { // 微信支付退款号 RefundId *string `json:"refund_id"` // 商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_-|*@ ,同一退款单号多次请求只退一笔。 OutRefundNo *string `json:"out_refund_no"` // 微信支付交易订单号 TransactionId *string `json:"transaction_id"` // 原支付交易对应的商户订单号 OutTradeNo *string `json:"out_trade_no"` // 枚举值: - ORIGINAL—原路退款 - BALANCE—退回到余额 - OTHER_BALANCE—原账户异常退到其他余额账户 - OTHER_BANKCARD—原银行卡异常退到其他银行卡 * `ORIGINAL` - 原路退款 * `BALANCE` - 退回到余额 * `OTHER_BALANCE` - 原账户异常退到其他余额账户 * `OTHER_BANKCARD` - 原银行卡异常退到其他银行卡 Channel *Channel `json:"channel"` // 取当前退款单的退款入账方,有以下几种情况: 1)退回银行卡:{银行名称}{卡类型}{卡尾号} 2)退回支付用户零钱:支付用户零钱 3)退还商户:商户基本账户商户结算银行账户 4)退回支付用户零钱通:支付用户零钱通 UserReceivedAccount *string `json:"user_received_account"` // 退款成功时间,退款状态status为SUCCESS(退款成功)时,返回该字段。遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。 SuccessTime *time.Time `json:"success_time,omitempty"` // 退款受理时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。 CreateTime *time.Time `json:"create_time"` // 退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往商户平台(pay.weixin.qq.com)-交易中心,手动处理此笔退款。 枚举值: - SUCCESS—退款成功 - CLOSED—退款关闭 - PROCESSING—退款处理中 - ABNORMAL—退款异常 * `SUCCESS` - 退款成功 * `CLOSED` - 退款关闭 * `PROCESSING` - 退款处理中 * `ABNORMAL` - 退款异常 Status *Status `json:"status"` // 退款所使用资金对应的资金账户类型 枚举值: - UNSETTLED : 未结算资金 - AVAILABLE : 可用余额 - UNAVAILABLE : 不可用余额 - OPERATION : 运营户 - BASIC : 基本账户(含可用余额和不可用余额) * `UNSETTLED` - 未结算资金 * `AVAILABLE` - 可用余额 * `UNAVAILABLE` - 不可用余额 * `OPERATION` - 运营户 * `BASIC` - 基本账户(含可用余额和不可用余额) FundsAccount *FundsAccount `json:"funds_account,omitempty"` // 金额详细信息 Amount *Amount `json:"amount"` // 优惠退款信息 PromotionDetail []Promotion `json:"promotion_detail,omitempty"` }
Refund
func (Refund) MarshalJSON ¶
type RefundsApiService ¶
func (*RefundsApiService) Create ¶
func (a *RefundsApiService) Create(ctx context.Context, req CreateRequest) (resp *Refund, result *core.APIResult, err error)
Create 退款申请
# 应用场景 当交易发生之后一段时间内,由于买家或者卖家的原因需要退款时,卖家可以通过退款接口将支付款退还给买家,微信支付将在收到退款请求并且验证成功之后,按照退款规则将支付款按原路退到买家帐号上。
注意: 1、交易时间超过一年的订单无法提交退款 2、微信支付退款支持单笔交易分多次退款,多次退款需要提交原支付订单的商户订单号和设置不同的退款单号。申请退款总金额不能超过订单金额。 一笔退款失败后重新提交,请不要更换退款单号,请使用原商户退款单号 3、请求频率限制:150qps,即每秒钟正常的申请退款请求次数不超过150次
错误或无效请求频率限制:6qps,即每秒钟异常或错误的退款申请请求不超过6次
4、每个支付订单的部分退款次数不能超过50次 5、如果同一个用户有多笔退款,建议分不同批次进行退款,避免并发退款导致退款失败 6、申请退款接口的返回仅代表业务的受理情况,具体退款是否成功,需要通过退款查询接口获取结果
# 错误码 |名称|描述|原因|解决方案| |-|-|-|-| |SYSTEM_ERROR|接口返回错误|系统超时等|请不要更换商户退款单号,请使用相同参数再次调用API。| |USER_ACCOUNT_ABNORMAL|退款请求失败|用户帐号注销|此状态代表退款申请失败,商户可自行处理退款。| |NOT_ENOUGH|余额不足|商户可用退款余额不足|此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。| |PARAM_ERROR|参数错误|请求参数未按指引进行填写|请求参数错误,请重新检查再调用退款申请| |MCH_NOT_EXISTS|MCHID不存在|参数中缺少MCHID|请检查MCHID是否正确| |RESOURCE_NOT_EXISTS|订单号不存在|缺少有效的订单号|请检查你的订单号是否正确且是否已支付,未支付的订单不能发起退款| |SIGN_ERROR|签名错误|参数签名结果不正确|请检查签名参数和方法是否都符合签名算法要求| |FREQUENCY_LIMITED|频率限制|2个月之前的订单申请退款有频率限制|该笔退款未受理,请降低频率后重试| |INVALID_REQUEST|请求参数符合参数格式,但不符合业务规则|不符合业务规则|此状态代表退款申请失败,商户可根据具体的错误提示做相应的处理。| |NO_AUTH|没有退款权限|没有此单的退款权限|此状态代表退款申请失败,请检查是否有退这笔订单的权限|
Example ¶
package main import ( "context" "log" "github.com/wechatpay-apiv3/wechatpay-go/core" "github.com/wechatpay-apiv3/wechatpay-go/core/option" "github.com/wechatpay-apiv3/wechatpay-go/services/refunddomestic" "github.com/wechatpay-apiv3/wechatpay-go/utils" ) func main() { var ( mchID string = "190000****" // 商户号 mchCertificateSerialNumber string = "3775************************************" // 商户证书序列号 mchAPIv3Key string = "2ab9****************************" // 商户APIv3密钥 ) // 使用 utils 提供的函数从本地文件中加载商户私钥,商户私钥会用来生成请求的签名 mchPrivateKey, err := utils.LoadPrivateKeyWithPath("/path/to/merchant/apiclient_key.pem") if err != nil { log.Print("load merchant private key error") } ctx := context.Background() // 使用商户私钥等初始化 client,并使它具有自动定时获取微信支付平台证书的能力 opts := []core.ClientOption{ option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key), } client, err := core.NewClient(ctx, opts...) if err != nil { log.Printf("new wechat pay client err:%s", err) } svc := refunddomestic.RefundsApiService{Client: client} resp, result, err := svc.Create(ctx, refunddomestic.CreateRequest{ SubMchid: core.String("1900000109"), TransactionId: core.String("1217752501201407033233368018"), OutTradeNo: core.String("1217752501201407033233368018"), OutRefundNo: core.String("1217752501201407033233368018"), Reason: core.String("商品已售完"), NotifyUrl: core.String("https://weixin.qq.com"), FundsAccount: refunddomestic.REQFUNDSACCOUNT_AVAILABLE.Ptr(), Amount: &refunddomestic.AmountReq{ Currency: core.String("CNY"), From: []refunddomestic.FundsFromItem{refunddomestic.FundsFromItem{ Account: refunddomestic.ACCOUNT_AVAILABLE.Ptr(), Amount: core.Int64(444), }}, Refund: core.Int64(888), Total: core.Int64(888), }, GoodsDetail: []refunddomestic.GoodsDetail{refunddomestic.GoodsDetail{ GoodsName: core.String("iPhone6s 16G"), MerchantGoodsId: core.String("1217752501201407033233368018"), RefundAmount: core.Int64(528800), RefundQuantity: core.Int64(1), UnitPrice: core.Int64(528800), WechatpayGoodsId: core.String("1001"), }}, }, ) if err != nil { // 处理错误 log.Printf("call Create err:%s", err) } else { // 处理返回结果 log.Printf("status=%d resp=%s", result.Response.StatusCode, resp) } }
Output:
func (*RefundsApiService) QueryByOutRefundNo ¶
func (a *RefundsApiService) QueryByOutRefundNo(ctx context.Context, req QueryByOutRefundNoRequest) (resp *Refund, result *core.APIResult, err error)
QueryByOutRefundNo 查询单笔退款(通过商户退款单号)
# 应用场景 提交退款申请后,通过调用该接口查询退款状态。退款有一定延时,建议查询退款状态在提交退款申请后1分钟发起,一般来说零钱支付的退款5分钟内到账,银行卡支付的退款1-3个工作日到账。 # 错误码 |名称|描述|原因|解决方案| |-|-|-|-| |SYSTEM_ERROR|接口返回错误|系统超时|请尝试再次调用API。| |RESOURCE_NOT_EXISTS|退款单查询失败|退款单号错误或退款单状态不正确|请检查退款单号是否有误以及订单状态是否正确,如:未支付、已支付未退款| |PARAM_ERROR|参数错误|请求参数未按指引进行填写|请求参数错误,请检查参数再调用退款查询| |MCH_NOT_EXISTS|MCHID不存在|参数中缺少MCHID|请检查MCHID是否正确| |SIGN_ERROR|签名错误|参数签名结果不正确|请检查签名参数和方法是否都符合签名算法要求|
Example ¶
package main import ( "context" "log" "github.com/wechatpay-apiv3/wechatpay-go/core" "github.com/wechatpay-apiv3/wechatpay-go/core/option" "github.com/wechatpay-apiv3/wechatpay-go/services/refunddomestic" "github.com/wechatpay-apiv3/wechatpay-go/utils" ) func main() { var ( mchID string = "190000****" // 商户号 mchCertificateSerialNumber string = "3775************************************" // 商户证书序列号 mchAPIv3Key string = "2ab9****************************" // 商户APIv3密钥 ) // 使用 utils 提供的函数从本地文件中加载商户私钥,商户私钥会用来生成请求的签名 mchPrivateKey, err := utils.LoadPrivateKeyWithPath("/path/to/merchant/apiclient_key.pem") if err != nil { log.Print("load merchant private key error") } ctx := context.Background() // 使用商户私钥等初始化 client,并使它具有自动定时获取微信支付平台证书的能力 opts := []core.ClientOption{ option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key), } client, err := core.NewClient(ctx, opts...) if err != nil { log.Printf("new wechat pay client err:%s", err) } svc := refunddomestic.RefundsApiService{Client: client} resp, result, err := svc.QueryByOutRefundNo(ctx, refunddomestic.QueryByOutRefundNoRequest{ OutRefundNo: core.String("1217752501201407033233368018"), SubMchid: core.String("1900000109"), }, ) if err != nil { // 处理错误 log.Printf("call QueryByOutRefundNo err:%s", err) } else { // 处理返回结果 log.Printf("status=%d resp=%s", result.Response.StatusCode, resp) } }
Output:
type ReqFundsAccount ¶
type ReqFundsAccount string
ReqFundsAccount * `AVAILABLE` - 可用余额, 仅对老资金流商户适用,指定从可用余额账户出资
const (
REQFUNDSACCOUNT_AVAILABLE ReqFundsAccount = "AVAILABLE"
)
Enums of ReqFundsAccount
func (ReqFundsAccount) Ptr ¶
func (e ReqFundsAccount) Ptr() *ReqFundsAccount
type Status ¶
type Status string
Status * `SUCCESS` - 退款成功, 退款状态 * `CLOSED` - 退款关闭, 退款状态 * `PROCESSING` - 退款处理中, 退款状态 * `ABNORMAL` - 退款异常, 退款状态