OXXO

支付流程

1、用户在商户网站进行下单选择oxxo付款；

2、商户向Payful发起oxxo支付请求；

3、Payful返回oxxo付款码信息。

4、商户将该付款码参考展示给用户；

5、用户保存付款码信息到oxxo便利店支付；

6、付款成功；

7、Payful通知商户订单成功。

请求地址

环境名称	URL
SandBox	POST https://sandbox-gateway.payful.com/api/supefina/transactions/payin
正式环境	POST https://gateway.payful.com/api/supefina/transactions/payin

请求参数

请求头

Key	Value
Content-Type	application/json

请求体

变量名	类型	必填	描述
countryId	String	是	国家编号 参照：字典表-国家编号 墨西哥：MEX
currency	String	是	币种 参照：字典表-货币 墨西哥比索：MXN
orderAmount	String	是	订单金额 单位比索，需要分可以传入小数，支持两位小数
payProduct	String	是	支付类型 oxxo：32
merId	String	是	商户ID 商户ID获取路径：Supefina商户后台-商户管理-基本信息-商户ID
merOrderNo	String	是	商户订单号
sign	String	是	签名 具体参照：签名算法
nonceStr	String	是	随机字符串 长度不能超过32位
callbackUrl	String	是	回调地址 详见通知回调说明

请求示例

{
  "callbackUrl": "http://test.com",
  "countryId": "MEX",
  "currency": "MXN",
  "merId": "8102401785904873",
  "merOrderNo": "2026011918295925593025317",
  "nonceStr": "e4658505b611417daa36981ff021506a",
  "orderAmount": 20,
  "payProduct": "32",
  "sign": "1E3685ED6881BA05106C4CFB012955D1"
}

签名组装字符串

callbackUrl=http://test.com&countryId=MEX&currency=MXN&merId=8102401785904873&merOrderNo=2026011918295925593025317&nonceStr=e4658505b611417daa36981ff021506a&orderAmount=20&payProduct=32&key=8102401785904873

响应参数

变量名	类型	描述
code	String	响应编码 具体参照：响应状态码
data	Object	响应数据
amount	BigDecimal	订单金额
fee	BigDecimal	预收手续费
merCode	String	商户ID
merOrderNo	String	商户订单号
supefinaOrderNo	String	supefina订单号
transactionStatus	String	下单状态 该笔订单的的发起状态是否成功，与订单真正的交易状态无关。 00：下单成功 04：下单失败
orderExpirationTime	String	过期时间
channelName	String	渠道
identifier	String	付款参考，oxxo付款码值
url	String	收银台交易链接地址
msg	String	响应描述

响应示例

{
  "code": "200",
  "msg": "success ",
  "data": {
    "merCode": "8102401785904873",
    "merOrderNo": "2026011918295925593025317",
    "supefinaOrderNo": "2026011903010295e3cf5583e7a4e",
    "amount": 20,
    "fee": 0.6,
    "transactionStatus": "00",
    "url": "https://h5.supefina.tech/mex/oxxo?token=lTuw6Sl%2BbO4OK2qpqcBYLQ5V11Yzyani09/b8G2Spcw=",
    "identifier": "8204230000011759",
    "channelName": "oxxo",
    "orderExpirationTime": "2026-01-31T10:30:00.843"
  }
}

回调通知

提交方式：POST

变量名	类型	描述
amount	String	订单金额
countryId	String	国家编号 参照：字典表-国家编号
fee	String	预收手续费
identifier	String	付款参考，oxxo条形码值
merId	String	商户ID
merOrderId	String	商户订单号
nonceStr	String	随机字符串 长度不能超过32位
realityAmount	String	实收金额
realityFee	String	实收手续费
reference	String	付款参考，oxxo付款码值
sign	String	签名
status	String	交易状态 具体参照：字典表——交易订单状态
supefinaOrderId	String	supefina订单号
transactionType	String	交易类型 01：代收 02：代付

回调通知示例

{
	"amount": "20.00",
	"countryId": "MEX",
	"fee": "1.00",
	"merId": "8302109931230575",
	"merOrderId": "2025072919104648604106643",
	"nonceStr": "e2ffce1e-c54b-456d-8f5a-3cadfd",
	"realityAmount": "20",
	"realityFee": "1.00",
	"reference": "CRTPPY8MAQ67WU8AUGWDPL4N25KCTOT",
	"sign": "A89A7822C07E94CA68B814A4A3AC9902",
	"status": "01",
	"successTime": 1753787454313,
	"supefinaOrderId": "202507290301000b99dfd47bbba43",
	"transactionType": "01"
}

签名组装字符串

amount=20.00&countryId=MEX&fee=1.00&merId=8302109931230575&merOrderId=2025072919104648604106643&nonceStr=e2ffce1e-c54b-456d-8f5a-3cadfd&realityAmount=20&realityFee=1.00&reference=CRTPPY8MAQ67WU8AUGWDPL4N25KCTOT&status=01&successTime=1753787454313&supefinaOrderId=202507290301000b99dfd47bbba43&transactionType=01&key=10b8a891ff6a479e8135f3367c17e87d

回调通知响应

商户成功收到回调后需同步返回指定字符串：SUCCESS 不返回或返回其他内容默认通知失败 如：

public String test(){
	return "SUCCESS";
}