匡佳华 / API-Interfaces · Files

请求地址：

环境	请求地址
测试环境	http://api-test1.yohops.com:9999
正式环境	https://api.yoho.cn

公共请求参数：

参数	类型	是否必填	最大长度	描述	示例值
app_id	String	是	32	分配给开发者的应用ID	2014072300007148
shop_id	String	是	32	商户门店编号	1001
terminal_id	String	是	32	商户机具终端编号	1001
operator_id	String	是	28	商户操作员编号	1001
method	String	是	128	接口名称	yohopay.trade.create
charset	String	否	10	仅支持utf-8	utf-8
sign	String	是	256	请求参数的签名串，详见签名	详见示例
timestamp	String	是	19	发送请求的时间，格式"yyyyMMddHHmmss"	20140724030750

公共响应参数

参数	类型	是否必填	最大长度	描述	示例值
code	String	是	-	网关返回码,详见文档	40004
message	String	否	-	网关返回码描述,详见文档	Business Failed
md5	String	是	-	相应参数MD5值 fd4ad5fcsa0de589af23234ks1923ks
data	JSON	否	-	业务执行成功数据包

yohopay.terminal.register (商户机具终端注册)

商户通过该接口进行机具终端的注册

请求参数：

参数	类型	是否必填	最大长度	描述	示例值
method	String	是	128	接口名称	yohopay.terminal.register
terminal_name	String	是	64	商户机具终端名称	POS01

响应参数

参数	类型	是否必填	最大长度	描述	示例值

yohopay.trade.create (统一收单交易创建接口)

商户通过该接口进行交易的创建下单

请求参数：

参数	类型	是否必填	最大长度	描述	示例值
method	String	是	128	接口名称	yohopay.trade.create
out_trade_no	String	是	64	商户订单号,64个字符以内、只能包含字母、数字、下划线；需保证在商户端不重复
notify_url	String	否	256	服务器主动通知商户服务器里指定的页面http/https路径。	http://api.test.xxx.net/atinterface/receive_notify.htm
total_amount	Price	是	9	订单总金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000] 如果同时传入了【打折金额】，【不可打折金额】，【订单总金额】三者，则必须满足如下条件：【订单总金额】=【打折金额】+【不可打折金额】	88.88
discountable_amount	Price	否	9	可打折金额. 参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000] 如果该值未传入，但传入了【订单总金额】，【不可打折金额】则该值默认为【订单总金额】-【不可打折金额】	8.88
undiscountable_amount	Price	否	9	不可打折金额. 不参与优惠计算的金额，单位为元，精确到小数点后两位，取值范围[0.01,100000000] 如果该值未传入，但传入了【订单总金额】,【打折金额】，则该值默认为【订单总金额】-【打折金额】	80.00
subject	String	是	256	订单标题	Iphone6 16G
body	String	可选	128	对交易或商品的描述	Iphone6 16G
goods_detail	GoodsDetail []	否	-	商品列表信息.Json格式. 详见：“商品明细说明”
└ goods_id	String	是	32	商品的编号	apple-01
└ goods_name	String	是	256	商品名称	ipad
└ quantity	Number	是	10	商品数量	1
└ price	Price	是	9	商品单价，单位为元	2000
└ goods_category	String	否	24	商品类目	34543238
└ body	String	否	1000	商品描述信息	特价手机
└ show_url	String	否	400	商品的展示地址 http://www.xxx.com/xxx.jpg

请求示例
localhost:8080/gateway

method = yohopay.trade.create
app_id  = 1000000001
shop_id  = 123
terminal_id = 8888
operator_id = 6098
out_trade_no = YH123456788
notify_url = www.baidu.com
total_amount = 100
discountable_amount = 0
undiscountable_amount = 0
subject = 奶茶
body = 奶茶,好喝的奶茶
goods_detail =[{"body":"奶茶","goods_id":"naicha123","goods_name":"双拼双色奶茶","price":25,"quantity":4}]
sign = 5BC06ABE02B82618C33CA2639FFF69ED

响应参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	是	64	商户订单号	20150423001001
trade_no	String	是	64	有货交易号	2015042321001004720200028594
timeout_express	String	是	6	该笔订单允许的最晚付款时间，逾期将关闭交易，格式"yyyyMMddHHmmss"。	20140724030750

响应成功JSON格式如下所示:

{
  "alg": "SALT_MD5",
  "code": 200,
  "data": {
    "out_trade_no": "YH123456788",
    "timeout_express": "20170223110713",
    "trade_no": "487818333550105"
  },
  "md5": "51eb8b28000a20e4d34e2b18b449ea23",
  "message": "third order create"
}

yohopay.trade.query (统一收单线下交易查询)

该接口提供所有支付订单的查询，商户可以通过该接口主动查询订单状态，完成下一步的业务逻辑。 需要调用查询接口的情况： 当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知； 调用支付接口后，返回系统错误或未知交易状态情况；

请求参数：

参数	类型	是否必填	最大长度	描述	示例值
method	String	是	128	接口名称	yohopay.trade.query
out_trade_no	String	特殊可选	64	商户订单号	20150423001001
trade_no	String	特殊可选	64	有货交易号	2013112011001004330000121536

请求示例
localhost:8080/gateway

method = yohopay.trade.query
out_trade_no=YH123456789
trade_no=123456789
sign=159D8FA7E868CA35D8A45E773E88527D

响应参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	必须	64	商户订单号	20150423001001
trade_no	String	必填	64	有货交易号	2013112011001004330000121536
trade_status	String	必填	32	交易状态：WAIT_BUYER_PAY（交易创建，等待买家付款）、TRADE_CLOSED（未付款交易超时关闭，或支付完成后全额退款）、TRADE_SUCCESS（交易支付成功）	TRADE_CLOSED
total_amount	Price	必填	11	交易的订单金额，单位为元，两位小数。	88.88
buyer_pay_amount	Price	必填	11	买家实付金额，单位为元，两位小数。	15.25
yoho_coin_amount	Price	选填	11	有货币支付金额，单位为元，两位小数。	10
buyer_payment	String	必填		支付方式
buyer_payment_str	String	必填		支付方式中文

响应成功JSON格式如下所示:

{
  "alg": "SALT_MD5",
  "code": 200,
  "data": {
    "buyer_pay_amount": 100.01,
    "out_trade_no": "YH123456789",
    "total_amount": 100.01,
    "trade_no": "123456789",
    "trade_status": "TRADE_CANCEL",
    "yoho_coin_amount": 0,
    "buyer_payment":"offlineCash",
    "buyer_payment_str":"现金"
  },
  "md5": "4eef7b693d86f525124f6ebfcc05c02a",
  "message": "third order query"
}

yohopay.trade.refund (统一收单交易退款接口)

当交易发生之后一段时间内，由于买家或者卖家的原因需要退款时，卖家可以通过退款接口将支付款退还给买家，系统将在收到退款请求并且验证成功之后，按照退款规则将支付款按原路退到买家帐号上。总退款金额不能超过用户实际支付金额

请求参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	特殊可选	64	商户订单号	20150320010101001
trade_no	String	特殊可选	64	有货交易号	2014112611001004680073956707
out_request_no	String	否	64	标识一次退款请求，同一笔交易多次退款需要保证唯一，如需部分退款，则此参数必传。
refund_amount	Price 是	9	需要退款的金额，该金额不能大于订单金额,单位为元，支持两位小数	200.12
refund_reason	String	是	256 退款的原因说明	正常退款
goods_detail	GoodsDetail []	可选	-	商品列表信息.Json格式. 详见：“商品明细说明”
└ goods_id	String	必填	32	商品的编号	apple-01
└ goods_name	String	必填	256	商品名称	ipad
└ quantity	Number	必填	10	商品数量	1
└ price	Price	必填	9	商品单价，单位为元	2000
└ goods_category	String	可选	24	商品类目	34543238
└ body	String	可选	1000	商品描述信息	特价手机
└ show_url	String	可选	400	商品的展示地址 http://www.xxx.com/xxx.jpg
└ refund_reason	String	是	256 退款的原因说明	正常退款

请求示例
localhost:8080/gateway

method=yohopay.trade.refund
app_id  = 1000000001
shop_id  = 123
terminal_id = 8888
operator_id = 6098
out_trade_no=YH123456788
trade_no=
out_request_no=
refund_reason=不想要了
refund_amount=100
goods_detail=[{"body":"奶茶","goods_id":"naicha123","goods_name":"双拼双色奶茶","price":25,"quantity":4}]
sign=744E8424967544F73600FD2DE15119B7

响应参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	必须	64	商户订单号	20150423001001
trade_no	String	必填	64	有货交易号	2013112011001004330000121536
out_request_no	String	选填	64 本笔退款对应的退款请求号	20150320010101001
fund_change	String	必填	1	本次退款是否发生了资金变化	Y
refund_total	Price	必填	11	退款总金额	88.88
refund_buyer_pay	Price	必填	11 退用户实付金额	15.25
refund_yoho_coin	Price	必填	11 退用户有货比支付金额	10
gmt_refund_pay	Date	必填	32	退款支付时间	20141127154557

响应成功JSON格式如下所示:

{
  "alg": "SALT_MD5",
  "code": 200,
  "data": {
    "fund_change": "Y",
    "gmt_refund_pay": "20170223105748",
    "out_request_no": "",
    "out_trade_no": "YH123456788",
    "refund_buyer_pay": 0,
    "refund_total": 100,
    "refund_yoho_coin": 100,
    "trade_no": "487818333550105"
  },
  "md5": "f861261007a30b2f4918bc8a23cab441",
  "message": "third refund order"
}

yohopay.trade.fastpay.refund.query (统一收单交易退款查询)

商户可使用该接口查询自已通过yohopay.trade.refund提交的退款请求是否执行成功。

请求参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	特殊可选	64	商户订单号	2014112611001004680073956707
trade_no	String	特殊可选	64	有货交易号	20150320010101001
out_request_no	String	否	64	标识一次退款请求，同一笔交易多次退款需要保证唯一，如需部分退款，则此参数必传。

请求示例
localhost:8080/gateway

method=yohopay.trade.fastpay.refund.query
out_trade_no=YH123456788
trade_no=
out_request_no=
sign=2D50BC4D67CFFC0BC185CCE72470B72A
}

响应参数

参数	类型	是否必填	最大长度	描述	示例值
out_trade_no	String	必须	64	商户订单号	20150423001001
trade_no	String	必填	64	有货交易号	2013112011001004330000121536
out_request_no	String	选填	64	本笔退款对应的退款请求号	20150320010101001
fund_change	String	必填	1	本次退款是否发生了资金变化	Y
refund_total	Price	必填	11	退款总金额	88.88
refund_buyer_pay	Price	必填	11	退用户实付金额	15.25
refund_yoho_coin	Price	必填	11	退用户有货比支付金额	10
gmt_refund_pay	Date	必填	32	退款支付时间	20141127154557

响应成功JSON格式如下所示:

{
  "alg": "SALT_MD5",
  "code": 200,
  "data": {
    "fund_change": "Y",
    "gmt_refund_pay": "1487818668",
    "out_request_no": "",
    "out_trade_no": "YH123456788",
    "refund_buyer_pay": 100,
    "refund_total": 100,
    "refund_yoho_coin": 0,
    "trade_no": "487818333550105"
  },
  "md5": "a170f3cd8637401a6b30620bfb55c2a3",
  "message": "third refund query"
}

yohopay.trade.system.cancel(取消订单)

商户可使用该接口取消交易

响应成功JSON格式如下所示:

{
  "alg": "SALT_MD5",
  "code": 200,
  "data": {
  },
  "md5": "a170f3cd8637401a6b30620bfb55c2a3",
  "message": "third system cancel success"
}