1. 扫码支付功能介绍

扫码⽀付，⽤户能够通过扫描Gate提供的，由商家展示的⼆维码进⾏⽀付。

• 商家与Gate合作，注册商户信息后。为不同的产品订单获取不同的QR码，商家显示⼆维码提供给⽤户扫码
• ⽤户打开Gate APP并扫描⼆维码
• ⽤户通过输⼊密码点击 "确认"按钮确认⽀付
• 在⽀付完成后，Gate通知商户和⽤户付款状态

2. 扫码⽀付

2.1 流程图

请商家务必注意:

• 采⽤HTTPS协议传输交易数据，防⽌数据被截获、解密
• 采⽤api_secret做数据签名 ，明确交易身份，保证交易主体的正确性和唯⼀性

2.2 调⽤流程

1. 商家系统调⽤(/v1/pay/transactions/native扫码下单接⼝)，获得该订单的⼆维码串qr_code，开发者需要利⽤⼆维码⽣成⼯具获得最终的订单⼆维码图⽚。
2. 发起轮询获得⽀付结果：等待5秒后调⽤订单状态查询接⼝(/v1/pay/order/query)，通过⽀付时候传⼊的商户订单号(merchantTradeNo)获取⽀付结果。如果返回的结果是等待⽤户⽀付(PENDING)，则再次等待 5 秒后继续查询，直到返回确切的⽀付结果(订单⽀付成功或者订单关闭)
3. 除了主动轮询，当订单⽀付成功时，商家也可以通过设置异步通知（notify_url）来获得GatePay服务器返回的⽀付结果

3. 扫码⽀付API列表

3.1 下单

• 数据类型：JSON （content-type：application/json）
• 请求⽅式：POST
• 路径Path: /v1/pay/transactions/native
• 验证方式：签名验证
• 请求体内容:

字段名	类型	是否必须	说明
merchantTradeNo	string	是	商户订单号
currency	string	是	订单币种，大写形式，如USDT、BTC等
orderAmount	string	是	订单金额，最高精度为6位，范围0.000001-50000
env	Env type	是	交易来源
goods	goods type	是	商品说明
orderExpireTime	int64	否	订单过期时间，UTC时间戳，millisecond。不设置时默认为1小时，最大过期时间为1小时
returnUrl	string	否	订单支付成功后返回跳转地址，最长256字符
cancelUrl	string	否	订单支付失败后返回跳转地址，最长256字符
channelId	string	否	客户名称

Env type

字段名	类型	是否必须	说明
terminalType	string	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS

Goods type

字段名	类型	是否必须	商品名称，最长160字符
goodsName	string	是	商品名称，最长160字符
goodsDetail	string	否	商品描述，最长256字符

请求示例:

curl --location --request POST 'https://openplatform.gateapi.io/v1/pay/transactions/native' \
--header 'Content-Type: application/json' \
--header 'X-GatePay-Certificate-ClientId: zb6WUrBDZlRAT7qz' \
--header 'X-GatePay-Timestamp: 1674117221032' \
--header 'x-GatePay-Nonce: 7436636664' \
--header 'x-GatePay-Signature: 11e658cf6b09d917caf9d4bb6ec4493431c55f066a694e58a5571a4a1a114ebc2011d346f340e54a5a2e2edaa172e907742fbdc99b94d009dade4b551daabd07' \
--data-raw '{
    "MerchantTradeNo": "118223456797",
    "currency":"USDT",
    "orderAmount":"1.9",
    "env": {
        "terminalType": "APP"
    },
    "goods": {
            "goodsName": "NF2T",
            "goodsDetail": "nef-book"
    },
    "orderExpireTime":1674118228000,
    "returnUrl":"http://47.99.158.63:8205/payment/callback",
    "channelId":"123456"
}'

请求响应:

{
    "status": "SUCCESS",
    "code": "000000",
    "errorMessage": "",
    "data": {
        "prepayId": "50984376880599040",
        "terminalType": "APP",
        "expireTime": 1674118228000,
        "qrContent": "http://openplatform.gate.io/qr/amaA9duknMfGKvM5H77Q0STgoTgVPmbPyuPDzlFvJO8="
    }
}

字段名	类型	是否必须	说明
status	string	是	SUCCESS 或者 FAIL
code	string	是	出错代码
data	data type	否	退款单信息
errorMessage	string	否	错误信息

data格式:

字段名	类型	是否必须	说明
prepayId	string	是	创建成功的预订单id
terminalType	string	是	交易来源，可选值：APP、WEB、WAP、MINIAPP、OTHERS
expireTime	int64	是	订单过期时间，UTC时间戳，millisecond。不设置时默认为1小时，最大过期时间为1小时
qrContent	string	是	订单二维码（有效时间 1 小时）以字符串的格式返回，开发者需要自己使用工具根据内容生成二维码图片。

4. 错误码

错误码	描述	解决方案
400000	请求参数格式错误	检查请求数据格式
400002	签名校验失败	检查商户签名是否正确
400003	请求时间戳超时	检查请求head里的时间戳字段
400007	不支持的media type	查看接口支持的media type
400603	订单超时	请核实订单是否过期
400621	错误的支付金额	检查请求金额
400620	订单重复支付	请核实商户订单号是否重复提交
500008	未找到对应商户	检查请求商户ID是否正确
500100	支付二维码过期	重新下单生成新二维码
500101	二维码重复支付	请核实订单状态

5. 常⻅问题

Q: 通过预下单接⼝⽣成的⼆维码多⻓时间有效？

A：⽤户可指定过期时间，最⼤和默认有效期是⼀⼩时。