ADOPAY 开发者平台

外观

获取凭证链接 ​

按商户订单号获取凭证页面访问链接。

接口 ​

GET /proof/link

认证 ​

Merchant Credential。详见 认证。

接口背景 ​

开放状态： 本接口为待接入的对外契约，实际可用时间以发布确认为准。

商户通过商户订单号 merchantOrderNo，获取自有付款订单的凭证页面访问链接 linkUrl。凭证类型由 proofType 指定，当前仅支持 APS（代付订单）。

获取规则 ​

  • 仅允许查询认证商户自己的订单；merchantOrderNo 应与付款下单时使用的商户订单号一致，proofType 应与该订单的实际类型一致。
  • 付款凭证必须已存在。本接口只生成访问链接，不创建凭证，也不改变订单状态。
  • 订单或凭证不存在时，不返回可用链接。获取凭证失败不代表付款失败，交易结果请通过付款订单查询确认。
  • 请直接使用完整的 linkUrl，保留其中的 key 查询参数。链接应作为访问凭证保管，仅分享给预期接收人；示例域名及 key 仅作展示，以实际返回的完整 URL 为准。

接口请求字段 ​

字段名位置类型字段长度是否必填说明
X-Merchant-IdHeaderstring64是商户号，从请求头读取，用于隔离不同商户的订单数据。
X-TimestampHeaderint19是Unix 秒级请求时间戳，用于请求时效校验。
X-NonceHeaderstring64是请求防重放随机字符串。
DigestHeaderstring52是请求摘要，格式为 SHA-256=<Base64摘要>；本接口无请求体，使用空字节串计算。
AuthorizationHeaderstring不定长是ES256 请求签名信息，其中 keyId 为商户密钥版本号。
merchantOrderNoQuerystring64是付款下单时使用的商户订单号，不能为空白，不能超过 64 字节。
proofTypeQuerystring16是凭证类型，当前仅支持 APS（代付订单）。

请求示例 ​

http
GET /proof/link?merchantOrderNo=CASHOUT202608160001&proofType=APS HTTP/1.1
X-Merchant-Id: 92315566000120
X-Timestamp: 1786845600
X-Nonce: 550e8400-e29b-41d4-a716-446655440000
Digest: SHA-256=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=
Authorization: Signature keyId="v1",alg="ES256",headers="(request-target) x-timestamp x-nonce digest",signature="<ES256_SIGNATURE_BASE64>"

GET 请求不携带请求体。实际调用时使用当前时间戳、新的随机串，并使用实际请求路径及完整查询字符串计算签名，详见请求签名。

接口响应字段 ​

接口使用统一的 status、msg、data 响应结构。仅当 status = 200 且 data.linkUrl 非空时，才表示成功获取凭证链接。

字段名类型字段长度是否必返说明
statusint4是响应码；200 表示请求处理成功。
msgstring128是与 status 对应，成功时为 "sucesso"。
dataobject不适用否凭证链接结果；请求处理失败时可能不返回或为 null。
data.merchantOrderNostring64成功时商户订单号。
data.platOrderNostring64成功时平台订单号。
data.linkUrlstring128成功时完整的付款凭证页面访问链接，包含 key 查询参数；成功时非空，不是凭证 JSON 或文件内容。

业务处理失败时，status 为非 200，原因见 msg，不可使用此时的链接字段。验签、协议解析等业务处理前的失败可能不返回 data。

响应示例 ​

json
{
  "status": 200,
  "msg": "sucesso",
  "data": {
    "merchantOrderNo": "CASHOUT202608160001",
    "platOrderNo": "APS202608160000000001",
    "linkUrl": "https://proof.example.com/payment?key=PROOF_KEY"
  }
}