PaymentOne 开发者接入指引

这份文档面向要把业务系统接入 PaymentOne 的开发者。PaymentOne 负责创建支付意图、展示聚合收银台、路由上游支付通道、同步支付状态，并在确认成功后通知你的业务系统。用户余额、订单状态、会员权益、订阅开通和幂等入账仍由业务系统自己负责。

选择接入方式

接入前先在后台完成配置：

1. 在“应用”里创建业务应用，复制易支付 PID、KEY，或标准 API 的应用 ID 和标准接口密钥。
2. 在应用里填写允许通知的域名，例如 merchant.example.com。notify_url 的 host 必须匹配该配置。
3. 在“支付通道”里创建并启用上游通道，例如 EasyPay、Stripe 或其他已接入 provider。
4. 用一笔小额订单跑通创建支付、付款、异步通知、订单查询和重复通知幂等处理。

最小接入流程

不管选择易支付兼容模式还是标准 JSON API，业务系统都建议按下面的顺序实现：

1. 在业务库里创建本地订单，状态为 pending，记录订单号、金额、币种和用户 ID。
2. 服务端向 PaymentOne 创建支付，易支付模式调用 mapi.php 或跳转 submit.php，标准模式调用 POST /v1/payment-intents。
3. 前端打开 payurl / checkout_url，或展示 qrcode 给用户扫码。
4. PaymentOne 收到上游支付成功事件后，向订单的 notify_url 投递回调。
5. 业务系统验签，核对订单号、金额、币种和应用身份。
6. 业务系统用本地唯一约束做幂等入账，把订单更新为已支付并发放权益。
7. 业务系统返回 HTTP 2xx，建议正文返回 success。
8. 如果用户页面先跳回 return_url，只展示处理中页面，再由后端订单状态或查询接口确认结果。

易支付兼容接入

易支付兼容模式适合已有易支付 SDK、插件或配置页的系统。业务侧通常只需要替换网关地址，签名算法和核心字段沿用易支付习惯。

接口总览

pid、key 和签名

所有创建支付请求都必须带 pid、sign、sign_type=MD5。签名步骤如下：

1. 去掉 sign、sign_type 和值为空的字段。
2. 按参数名 ASCII 升序排序。
3. 拼接为 k=v，字段之间用 & 连接。
4. 在拼接串末尾直接追加应用 KEY。
5. 对最终字符串做 MD5，得到小写十六进制摘要。

签名原文不要 URL 编码。额外兼容字段如果参与请求，也必须参与签名。

sign_source = "money=9.90&name=Recharge&notify_url=https://merchant.example/pay/notify&out_trade_no=order_123&pid=1000&return_url=https://merchant.example/pay/return&type=alipay" + KEY
sign = md5_lower_hex(sign_source)

签名示例代码

PHP 易支付 MD5 示例：

function epay_sign(array $params, string $key): string {
    unset($params['sign'], $params['sign_type']);

    $filtered = [];
    foreach ($params as $name => $value) {
        if ($value === '' || $value === null) {
            continue;
        }
        $filtered[$name] = (string) $value;
    }

    ksort($filtered, SORT_STRING);

    $pairs = [];
    foreach ($filtered as $name => $value) {
        $pairs[] = $name . '=' . $value;
    }

    return md5(implode('&', $pairs) . $key);
}

Node.js 标准 API HMAC 示例：

import crypto from 'node:crypto';

function paymentoneSignature(secret, timestamp, rawBody) {
  return crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`)
    .digest('hex');
}

const rawBody = JSON.stringify({
  app_order_id: 'order_123',
  amount: 990,
  currency: 'CNY',
  subject: 'Recharge',
  provider: 'paymentone',
  method: 'alipay',
  notify_url: 'https://merchant.example/pay/notify',
  return_url: 'https://merchant.example/pay/return'
});
const timestamp = Math.floor(Date.now() / 1000).toString();
const signature = paymentoneSignature(process.env.PAYMENTONE_SECRET, timestamp, rawBody);

Webhook 验签时使用收到的原始请求体，不要解析后再重新 JSON.stringify 或重新拼表单。

公共创建参数

submit.php 和 mapi.php 使用同一组核心参数。

跳转收银台 submit.php

适合浏览器端通过表单发起支付。推荐使用 POST，也支持 GET。

<form method="post" action="https://payment.agentone.work/easypay/submit.php">
  <input name="pid" value="1000">
  <input name="type" value="alipay">
  <input name="out_trade_no" value="order_123">
  <input name="name" value="Recharge">
  <input name="money" value="9.90">
  <input name="notify_url" value="https://merchant.example/pay/notify">
  <input name="return_url" value="https://merchant.example/pay/return">
  <input name="sign" value="<MD5签名>">
  <input name="sign_type" value="MD5">
  <button type="submit">Pay</button>
</form>

成功时 PaymentOne 返回 302 Found，Location 指向 PaymentOne 聚合收银台。签名错误返回 HTTP 400 和纯文本 fail；创建支付失败通常返回 HTTP 502。

API 创建支付 mapi.php

适合服务端创建订单后，把支付链接或二维码交给前端展示。

curl -X POST "https://payment.agentone.work/easypay/mapi.php" \
  -F "pid=1000" \
  -F "type=alipay" \
  -F "out_trade_no=order_123" \
  -F "name=Recharge" \
  -F "money=9.90" \
  -F "notify_url=https://merchant.example/pay/notify" \
  -F "return_url=https://merchant.example/pay/return" \
  -F "sign=<MD5签名>" \
  -F "sign_type=MD5"

成功响应示例：

{
  "code": 1,
  "msg": "success",
  "trade_no": "paymentone_pi_xxx",
  "out_trade_no": "order_123",
  "payurl": "https://pay.example.com/checkout/pi_xxx",
  "qrcode": "https://pay.example.com/checkout/pi_xxx/qrcode.png",
  "img": "https://pay.example.com/checkout/pi_xxx/qrcode.png"
}

字段说明：

请求成功不等于支付成功。mapi.php 只表示支付单创建成功，是否到账必须以后续 notify_url 通知或 api.php?act=order 查询为准。

订单查询 api.php

当前易支付兼容查询只支持查询单个订单：act=order。

curl "https://payment.agentone.work/easypay/api.php?act=order&pid=1000&out_trade_no=order_123&key=<KEY>"

也可以不用 key，改为对 act、pid、out_trade_no 等查询参数做 MD5 签名并传 sign、sign_type=MD5。

待支付响应示例：

{
  "code": 1,
  "msg": "success",
  "pid": "1000",
  "out_trade_no": "order_123",
  "trade_no": "paymentone_pi_xxx",
  "type": "alipay",
  "name": "Recharge",
  "money": "9.90",
  "status": 0,
  "trade_status": "WAIT_BUYER_PAY"
}

已支付时 status=1，trade_status=TRADE_SUCCESS。查询接口会在订单仍是 created 或 pending 时尝试同步一次上游状态；如果上游暂时不可用，仍会返回本地当前状态。

返回码与错误

回调处理：异步通知 notify_url

PaymentOne 确认支付成功后，会向创建支付时传入的 notify_url 发起 POST 请求。

兼容易支付的通知体为 application/x-www-form-urlencoded：

通知请求还会带标准 Webhook 头：

兼容易支付系统时，至少校验表单里的 MD5 签名、pid、out_trade_no、money 和 trade_status=TRADE_SUCCESS。如果你是新系统，也建议同时校验标准 Webhook 头。

处理成功后返回 HTTP 2xx，正文建议返回纯文本 success。PaymentOne 当前以 HTTP 2xx 判断投递成功；如果业务返回 4xx、5xx 或网络超时，会进入失败重试和后台投递记录。

回调重试策略

Webhook 投递 worker 每 5 秒扫描一次待投递记录，每次 HTTP 请求超时时间为 10 秒。投递失败后会按 attempts^2 分钟退避重试：第 1 次失败约 1 分钟后重试，第 2 次失败约 4 分钟后重试，第 3 次失败约 9 分钟后重试，以此类推。累计 10 次失败后投递状态会变为 failed。

后台“Deliveries”页面可以查看每次投递的 URL、状态、尝试次数、下一次投递时间和最近错误。业务系统收到重复通知时必须幂等处理；已经入账的订单直接返回 2xx 即可。

页面返回 return_url

return_url 是用户浏览器跳回业务站点的地址。它可能发生在异步通知之前，也可能被用户刷新、复制或伪造，所以只适合展示“支付处理中/请稍候”的页面。

正确做法是：页面进入后用业务订单号查询你自己的后端状态；后端以 notify_url 幂等入账或服务端查询 api.php?act=order 的结果为准。

兼容差异

PaymentOne 的易支付兼容层覆盖支付接入主流程，但不是完整复制所有易支付平台行为。

不支持接口

PaymentOne 当前不是完整的易支付商户后台 API，只提供支付接入所需的兼容面。

标准 JSON API 接入

标准 API 适合新系统。它使用 JSON 请求、最小货币单位和 HMAC-SHA256 签名，字段更稳定，也更适合服务端集成。

接口总览

provider/method 可用值

provider 决定 PaymentOne 使用哪个上游通道，method 表示支付方式。实际是否可用还取决于后台是否启用了对应支付通道。

如果 provider 留空，PaymentOne 会根据 method 推断 provider：card 走 Stripe，alipay / wxpay 等走 EasyPay，未知值默认按 EasyPay 处理。新系统建议显式传 provider。

请求认证

除 GET /v1/payment-methods 外，标准 API 都需要以下请求头：

raw_body 必须是实际发送给 PaymentOne 的原始请求体字节。GET 或空 body 的 POST 也要签名，签名原文是 <timestamp>.。

raw_body = exact JSON bytes sent to PaymentOne
timestamp = unix_seconds()
signature = hmac_sha256_hex(StandardSecret, timestamp + "." + raw_body)

创建支付意图

curl -X POST "https://payment.agentone.work/v1/payment-intents" \
  -H "Content-Type: application/json" \
  -H "X-App-Id: demo" \
  -H "X-PaymentOne-Timestamp: <timestamp>" \
  -H "X-PaymentOne-Signature: <signature>" \
  --data '{
    "app_order_id": "order_123",
    "amount": 990,
    "currency": "CNY",
    "subject": "Recharge",
    "provider": "paymentone",
    "method": "alipay",
    "return_url": "https://merchant.example/pay/return",
    "notify_url": "https://merchant.example/pay/notify",
    "metadata": {
      "user_id": "user_123"
    }
  }'

请求字段：

响应字段：

创建成功响应：

{
  "payment_intent_id": "pi_123",
  "app_order_id": "order_123",
  "status": "pending",
  "provider": "paymentone",
  "provider_trade_no": "paymentone_pi_123",
  "amount": 990,
  "currency": "CNY",
  "subject": "Recharge",
  "checkout_url": "https://pay.example.com/checkout/pi_123",
  "qrcode": "https://pay.example.com/checkout/pi_123/qrcode.png",
  "expires_at": null,
  "paid_at": null
}

查询待支付响应：

{
  "payment_intent_id": "pi_123",
  "app_order_id": "order_123",
  "status": "pending",
  "provider": "easypay",
  "provider_trade_no": "epay_20260703123456",
  "amount": 990,
  "currency": "CNY",
  "subject": "Recharge",
  "checkout_url": "https://pay.example.com/pay/epay_20260703123456",
  "qrcode": "https://pay.example.com/qrcode/epay_20260703123456.png",
  "expires_at": "2026-07-03T08:30:00Z",
  "paid_at": null
}

查询已支付响应：

{
  "payment_intent_id": "pi_123",
  "app_order_id": "order_123",
  "status": "paid",
  "provider": "easypay",
  "provider_trade_no": "epay_20260703123456",
  "amount": 990,
  "currency": "CNY",
  "subject": "Recharge",
  "checkout_url": "https://pay.example.com/pay/epay_20260703123456",
  "qrcode": "https://pay.example.com/qrcode/epay_20260703123456.png",
  "expires_at": "2026-07-03T08:30:00Z",
  "paid_at": "2026-07-03T08:10:12Z"
}

查询和同步

查询支付意图：

curl -X GET "https://payment.agentone.work/v1/payment-intents/{payment_intent_id}" \
  -H "X-App-Id: demo" \
  -H "X-PaymentOne-Timestamp: <timestamp>" \
  -H "X-PaymentOne-Signature: <signature-for-empty-body>"

主动同步：

curl -X POST "https://payment.agentone.work/v1/payment-intents/{payment_intent_id}/sync" \
  -H "X-App-Id: demo" \
  -H "X-PaymentOne-Timestamp: <timestamp>" \
  -H "X-PaymentOne-Signature: <signature-for-empty-body>"

GET 查询会在必要时尝试同步；POST /sync 会强制请求上游状态。两者响应结构都和创建支付意图一致。业务系统可以把查询作为补偿手段，但最终入账仍建议以 Webhook 幂等处理为主。

标准 Webhook

标准 API 创建的订单支付成功后，PaymentOne 会向 notify_url 发送 JSON：

{
  "event_id": "evt_123",
  "type": "payment.succeeded",
  "payment_intent_id": "pi_123",
  "app_id": "demo",
  "app_order_id": "order_123",
  "amount": 990,
  "currency": "CNY",
  "provider": "stripe",
  "provider_trade_no": "cs_test_123",
  "paid_at": "2026-07-02T10:20:30Z"
}

通知头：

验签通过后，再核对 app_id、app_order_id、amount、currency 和本地订单是否一致。处理成功返回任意 HTTP 2xx。

业务侧幂等要求

不要只看“通知到了”就入账。每次通知至少检查：

1. 签名合法，时间戳在可接受窗口内。
2. app_id 或 pid 属于当前业务系统。
3. app_order_id 或 out_trade_no 能匹配本地订单。
4. 金额和币种与本地订单一致。
5. 订单尚未入账；如果已经入账，直接返回成功。

推荐以业务订单号或 PaymentOne payment_intent_id 建唯一入账约束。重复通知只能更新日志，不能重复增加余额或发放权益。

测试与联调

本地联调可以使用 mock provider，避免真实扣款：

PAYMENTONE_MOCK_PROVIDERS=true \
PAYMENTONE_WEBHOOK_ALLOW_PRIVATE_HOSTS=true \
PAYMENTONE_WEBHOOK_ALLOWED_HOSTS=localhost,127.0.0.1 \
PAYMENTONE_PUBLIC_BASE_URL=http://localhost:8080 \
go run ./cmd/paymentone

PAYMENTONE_MOCK_PROVIDERS=true 会为未配置的 provider 注册 mock provider。创建支付后打开 checkout_url，mock 收银台会显示“标记为已支付”按钮，点击后 PaymentOne 会把订单标记为 paid 并向 notify_url 投递回调。

本地回调到 localhost、127.0.0.1 或内网地址时，需要 PAYMENTONE_WEBHOOK_ALLOW_PRIVATE_HOSTS=true。生产环境不要打开这个开关，生产环境应使用 HTTPS 的公网回调地址，并在应用里配置允许通知域名。

建议至少验证这些场景：

• 签名正确时能创建支付，签名错误时会失败。
• notify_url 收到成功通知后能验签、核对金额并幂等入账。
• 重复投递同一订单不会重复发放权益。
• return_url 先到达时页面只展示处理中，不直接入账。
• 使用 api.php?act=order 或标准查询接口能补偿确认订单状态。

上线检查清单

• 已在后台应用里配置允许通知域名，生产环境不要放开任意 host。
• 已启用真实支付通道，并在上游后台配置 PaymentOne 的 provider webhook 地址。
• 业务系统已实现回调验签、金额核对、订单幂等和失败日志。
• 标准 API 请求全部在服务端签名，前端只拿 checkout_url 或 qrcode。
• 不要在前端暴露 KEY 或标准接口密钥，不要把密钥写入公开日志。
• 已验证 submit.php、mapi.php、api.php?act=order、notify_url、return_url 的完整流程。
• 已用重复通知、重复创建订单、金额不一致、签名错误等场景做过测试。

排错顺序

1. 创建支付失败：先看 pid / X-App-Id、签名、金额格式、应用密钥和 provider 是否启用。
2. 支付页无法打开：检查 payurl / checkout_url 是否为空，以及聚合收银台是否有可用支付方式。
3. 订单一直 pending：用后台支付意图详情和 api.php?act=order / 标准查询接口确认当前状态。
4. 回调未到账：查看 Webhook 投递列表，确认 notify_url host 是否允许、下游是否返回 2xx、是否超时。
5. 业务未入账：先查业务侧幂等表，再查 PaymentOne 支付状态、通知签名和投递记录。