概述

1Pass 支持微信 Native 支付（PC 扫码付），使用与登录相同的 AK/SK 签名体系。你的后端创建订单后，用户在 1Pass 提供的支付页面扫码付款，付款成功后 1Pass 通知你的后端。

支付流程

第一步：创建支付订单

使用与 /token 相同的 AK/SK 签名方式调用：

POST https://1pass.top/pay/wechat/native
Content-Type: application/json
X-1Pass-AK: your_ak
X-1Pass-Ts: 1706601234
X-1Pass-Nonce: random-uuid
X-1Pass-Sign: hmac_signature

{
    "out_trade_no": "order_20240101_001",
    "description": "VIP月卡",
    "amount_total": 2990,
    "currency": "CNY",
    "expire_minutes": 15,
    "return_url": "https://shop.example.com/orders/order_20240101_001"
}

请求参数

字段	类型	必填	说明
out_trade_no	string	✅	商户订单号（6~64 字符，字母数字下划线横杠）
description	string	✅	商品描述（≤127 字符）
amount_total	integer	✅	金额（单位：分，如 2990 = ¥29.90）
currency	string	❌	币种，默认 CNY
expire_minutes	integer	❌	过期时间（分钟），默认 15
return_url	string	❌	支付成功后的浏览器返回地址。须为 HTTPS，且与站点登录回调地址的域名和端口一致；最长 2048 字符。
client_notify_url	string	❌	客户服务端接收支付通知的公网 HTTP(S) 地址，与浏览器返回地址分开。

成功响应

{
    "out_trade_no": "order_20240101_001",
    "code_url": "weixin://wxpay/bizpayurl?pr=...",
    "prepay_id": "wx2024...",
    "status": "pending",
    "checkout_url": "https://1pass.top/pay/wechat/checkout?token=ck_..."
}

第二步：展示支付页面

方式一（推荐）：将用户重定向到 checkout_url。1Pass 提供完整的支付 UI，包含二维码、支付成功页和自动状态轮询。

方式二：使用 code_url 自行渲染二维码，并通过以下接口轮询支付状态：

GET https://1pass.top/pay/wechat/status?token=ck_...

支付后返回商家页面（可选）

此参数由接入开发者在服务端创建订单时传入，不是在控制台填写，也不要追加到 checkout_url 上。使用 1Pass 平台商户收款，无需配置自己的微信商户。

1. 在控制台“站点管理”中启用微信支付，并确认该站点的登录回调地址。例如 https://shop.example.com/auth/callback。
2. 准备自己站点的订单详情页，例如 https://shop.example.com/orders/order_20240101_001。返回地址须与登录回调地址同源，路径可以不同；不能使用其他域名、HTTP 或携带用户名密码的地址。
3. 把 return_url 加入 POST /pay/wechat/native 的 JSON 请求体，再对完整请求体计算签名。SK 只保存在客户服务端。
4. 照常打开接口返回的 checkout_url。支付成功后可点击“返回商家页面”，也可等待 3 秒自动跳转。不传参数则保留成功页。

跳转发生在打开收银台的窗口；新窗口支付会在该新窗口返回。自行使用 code_url 绘制二维码时，页面更新和跳转由客户站点实现。

返回页面应通过客户服务端确认订单已支付，再展示权益或发货，不能仅凭跳转判断支付成功。平台不会向返回地址追加支付凭证或成功标记；请在路径或查询参数中带上自己的订单号。同一订单号重试下单须保持返回地址不变，旧订单不能通过重复下单补加返回地址。

第三步：接收支付结果

方式一：回调通知（推荐）

创建订单时传入可选的 client_notify_url，支付成功后 1Pass 会 POST 通知到你的后端：

{
    "site_id": "site_123",
    "out_trade_no": "order_20240101_001",
    "transaction_id": "420000000000000000000",
    "trade_state": "SUCCESS",
    "amount": { "total": 2990, "currency": "CNY" },
    "event_type": "TRANSACTION.SUCCESS"
}

方式二：主动轮询

GET https://1pass.top/pay/wechat/status?token=ck_...

返回 status 字段值：

状态	说明
created	已创建
pending	等待支付
paid	已支付
failed	支付失败
closed	已关闭
refunded	已退款

代码示例（Node.js）

const crypto = require('crypto');

async function createPaymentOrder(ak, sk, orderData) {
    const ts = Math.floor(Date.now() / 1000).toString();
    const nonce = crypto.randomBytes(16).toString('hex');
    const body = JSON.stringify(orderData);

    // 签名方式与 /token 完全一致
    const bodyHash = crypto.createHash('sha256').update(body).digest('hex');
    const canonical = `${ts}\n${nonce}\nPOST\n/pay/wechat/native\n${bodyHash}`;
    const sign = crypto.createHmac('sha256', sk)
        .update(canonical).digest('base64url');

    const resp = await fetch('https://1pass.top/pay/wechat/native', {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
            'X-1Pass-AK': ak, 'X-1Pass-Ts': ts,
            'X-1Pass-Nonce': nonce, 'X-1Pass-Sign': sign,
        },
        body,
    });
    return await resp.json();
}

// 使用：
const orderNo = 'order_' + Date.now();
const result = await createPaymentOrder('ak_xxx', 'sk_xxx', {
    out_trade_no: orderNo,
    description: 'VIP月卡',
    amount_total: 2990,
    return_url: 'https://shop.example.com/orders/' + orderNo,
});
// 重定向用户到 result.checkout_url

支付错误码

错误码	HTTP	说明
missing_fields	400	缺少必填字段（out_trade_no / description / amount_total）
invalid_out_trade_no	400	商户订单号格式不正确
invalid_amount	400	金额无效（须为正整数，单位分）
invalid_currency	400	不支持的币种（仅支持 CNY）
description_too_long	400	描述超过 127 字符
payment_not_configured	400	站点未配置微信支付
out_trade_no_conflict	409	商户订单号已被其他站点使用
wechat_create_failed	502	微信下单失败（请查看错误详情）
invalid_return_url	400	返回地址无效：检查 HTTPS、与登录回调地址同源及长度限制。
out_trade_no_mismatch	409	重复下单的金额、商品、通知地址或返回地址与原订单不一致。