1. 简介

QLink支付对接标准文档

2. 环境要求及基础约定

授权：联系QLink获取appKey、appSecret（密钥，用于验证报文信息）。

接口地址：

线下：http://qlink-global-test.800best.com/global-api/v1/pay

生产：http://qlink-global.800best.com/global-api/v1/pay

请求方式：

  • Method: POST
  • Content-Type: application/json

Header参数:

字段名 类型 必填 备注
appKey String 是
sign String 是
serviceProvider String 是

公共响应:

字段名 类型 必填 备注
success boolean 是 业务处理是否成功
errorCode String 否 失败码
result Object 否 业务数据

签名方式:

1、将appKey和content组成json字符串{"appKey":"appKey","content":"具体业务参数"}，content为空时{"appKey":"appKey"}。

2、将第三方分配的客户appSecret添加到json的末尾，得到待加密字串{"appKey":"appKey","content":"具体业务参数"}appSecret。

3、对待加密字串做sha1加密得到签名（org.apache.commons.codec.digest.DigestUtils.sha1Hex(待加密字串)）

4、将签名赋值到公共请求的sign字段

3. 查询支付账户

url:

  • /queryPayAccount

接口参数:

字段名 字段描述 类型 必填 备注
payAccount 支付账号 String 是

返回信息:

字段名 字段描述 类型 必填 备注
serviceProvider 支付服务商 String 是
type 支付方式 String 是
channelCode 支付渠道 String 是
desc 描述 String 否
country 国家 String 是
currencyList 币种 String 是

请求示例: { "payAccount": "account1" }

返回示例:

[ { "serviceProvider": "xendit", "type": "PAY" "channelCode": "QRIS", "desc": "", "country": "ID", "currencyList": ["IDR", "PHP", "VND", "THB", "SGD", "MYR", "USD"], } ]

4. 支付申请

url:

  • /apply

接口参数:

字段名 字段描述 类型 必填 备注
payAccount 支付账号 String 是
type 支付方式 String 是
channelCode 支付渠道 String 是
channelProperties 可传过期时间 Map 是 {"expires_at":"2025-08-19T15:22:06Z"} ISO 8601标准
tradeUuid 请求uuid String 是 appKey下需要唯一
tradeTime 请求交易时间 Date 是
source 支付来源 String 是 QERP_CN、QERP_ASIA
orderCode 订单号 String 是
country 国家二字码 String 是 国家二字码枚举
currency 三个字母的货币代码 String 是 三个字母的货币代码
amount 金额 Bigdecimal 是
description 描述 String 否
metadata 自定义数据 String 否 例：{ "my_custom_id": "merchant-123", "my_custom_order_id": "order-123" }
items 描述 Array 否
└ code 商品编码 String 是
└ type 商品类型 String 否 "DIGITAL_PRODUCT", "PHYSICAL_PRODUCT", "DIGITAL_SERVICE", "PHYSICAL_SERVICE", "FEE"
└ name 商品名称 String 是
└ netUnitAmount 商品单价 number 是
└ quantity 数量 number 是
└ url 商品连接 String 否
└ imageUrl 图片连接 String 否
└ category 商品类目 String 否
└ subcategory 商品子类目 String 否
└ description 描述 String 否
└ metadata 自定义数据 String 否

返回信息:

字段名 字段描述 类型 必填 备注
billCode 账单号 String 是
paymentRequestId 支付服务商唯一请求id String 否
errorCode 失败原因 String 否
actionList 商家完成操作时将使用的具体值 Array 是
└ type 商家系统需要处理以完成支付的操作类型 String 是
└ descriptor 商家系统需要处理以完成支付的操作类型 String 是
└ value 商家完成操作时将使用的具体值 String 是

请求示例:

{ "payAccount": "account1", "type": "ONLINE", "channelCode": "QRIS", "channelProperties": { "expires_at": "2025-08-11T23:59:59Z" }, "tradeUuid": "uuid", "tradeTime": "2025-08-04 13:45:21", "orderCode": "O20250804001", "country": "ID", "currency": "IDR", "amount": 1, "description": "描述", "metadata": "", "items": [ { "code": "SKU01", "type": "DIGITAL_PRODUCT", "name": "商品01", "netUnitAmount": 1, "quantity": "1", "url": "http://", "imageUrl": "http://", "category": "", "subcategory": "", "description": "", "metadata": "" } ] }

返回示例:

{ "billCode": "账单号", "paymentRequestId": "11111", "actionList": [ { "type": "", "descriptor": "", "value": "" } ] "errorCode": "" }

5. 模拟支付（xendit）

url:

  • /simulatePay

接口参数:

字段名 字段描述 类型 必填 备注
payAccount 支付账号 String 是
tradeUuid 请求uuid String 否 tradeUuid、billCode不可同时为空，都不为空时使用tradeUuid
billCode qlink单据号 String 否 tradeUuid、billCode不可同时为空

请求示例:

{ "payAccount": "account1", "tradeUuid": "uuid", "billCode": "billCode" }

6. 查询支付状态

url:

  • /getPayStatus

接口参数:

字段名 字段描述 类型 必填 备注
tradeUuidList 请求uuid Array 否 tradeUuidList、billCodeList不可同时为空，都不为空时使用tradeUuidList
billCodeList 账单号 Array 否 tradeUuidList、billCodeList不可同时为空

返回信息:

字段名 字段描述 类型 必填 备注
tradeUuid 请求uuid String 是
billCode 帐号号 String 是
paymentRequestId 支付服务商唯一请求id String 是
orderCode 订单号 String 是
status 支付状态 String 是 支付状态枚举
payTime 支付时间 Date 否 已支付时必填
amount 金额 Bigdecimal 否
currency 三个字母的货币代码 String 否 三个字母的货币代码
errorCode 失败编码 String 否

请求示例:

{ "tradeUuidList": ["uuid1"], "billCodeList": ["billCode1"] }

返回示例: [ { "amount": 1, "billCode": "billCode1", "currency": "IDR", "errorCode": "", "orderCode": "O20250804001", "payTime": "", "paymentRequestId": paymentRequestId"", "status": "PAY_WAIT", "tradeUuid": "uuid1" }, { "amount": 2, "billCode": "billCode2", "currency": "IDR", "errorCode": "", "orderCode": "O20250804002", "payTime": "2025-08-04 13:45:21", "paymentRequestId": "paymentRequestId", "status": "PAY_SUCCESS", "tradeUuid": "uuid2" } ]

7. 取消支付

url:

  • /cancel

接口参数:

字段名 字段描述 类型 必填 备注
tradeUuid 请求uuid String 否 tradeUuid、billCode不可同时为空，都不为空时使用tradeUuid
billCode 账单号 String 否 tradeUuid、billCode不可同时为空

返回信息:

字段名 字段描述 类型 必填 备注
status 取消状态 String 是 取消状态枚举
cancelTime 取消时间 Date 否
errorCode 失败编码 String 否

请求示例:

{ "tradeUuid": "uuid1", "billCode": "billCode1" }

返回示例:

{ "status": "WAIT", "cancelTime": "", "errorCode": "" }

8. Webhook

9. 支付状态通知

url:

  • /qlink/payNotification

接口参数:

字段名 字段描述 类型 必填 备注
tradeUuid 请求uuid String 是 需要唯一
billCode 支付账单号 String 是
orderCode 订单号 String 是
paymentRequestId 订单号 String 是
status 支付状态 String 是 支付状态枚举
payTime 支付时间 Date 否 支付成功时必传
errorCode 失败编码 String 否 支付失败时必传
notificationTime Long 是

请求示例:

{ "tradeUuid": "uuid1", "billCode": "billCode1", "orderCode": "O20250804001", "paymentRequestId": "O20250804001", "status": "WAIT", "payTime": "", "errorCode": "" "notificationTime": 1756191428000 }

© Copyright QianYi Team 2025 All Rights Reserved            Updated 2025-09-12 03:34:28

results matching ""

    No results matching ""