mapi.php 直连创建支付 - Kyren Pay

/epay/mapi.php 是服务端到服务端的 Epay 兼容端点。它接收表单 POST，创建或复用 Kyren 订单，并根据所选渠道返回 payurl、qrcode、img、trade_no 等 Epay 风格字段。该端点使用 pid + sign，不使用 x-api-key。由于它是服务端直连端点，开启 API IP 白名单时可能会校验来源 IP。白名单校验失败时可能返回数字 code 为 0，并附带 msg。

参数

必填参数：

参数	说明
`pid`	Kyren 发放的商户 Epay 兼容商户 ID。
`type`	支付类型。支持值包括 `alipay`、`wxpay`、`creditcard`、`crypto`、`paynow`。
`out_trade_no`	你的商户订单号。
`notify_url`	商户支付结果通知 URL。
`name`	订单或商品名称。
`money`	十进制字符串金额，例如 `"9.99"`。
`clientip`	你的服务端采集到的终端用户 IP。
`sign`	Epay 兼容 MD5 签名。
`sign_type`	签名类型，通常为 `MD5`。

可选参数：

参数	说明
`return_url`	渠道需要支付页时使用的浏览器返回 URL。
`money_type`	你的现有集成传入的币种或金额类型。
`device`	可选设备提示：`pc` 或 `mobile`。同一订单号复用到不同支付宝/微信设备支付形态时可能被拒绝。
`display_merchant_name`	本次支付在 Kyren 中间页展示的商户名称。
`param`	商户透传元数据，会在通知中返回。
`userId`	可选的商户用户标识；渠道支持时会传给支付网关。
`channel_param`	非信用卡支付类型可选的渠道扩展 JSON 字符串。当 `type=creditcard` 时，其原始值仍参与 Epay 签名，但 Kyren 在验签后会完全忽略该值。禁止通过 `channel_param` 传入卡号、有效期、CVV、账单资料或联系信息；买家将在 Kyren 或上游托管页面输入卡片资料。顶层 `email`、`phone` 和 `userId` 参数不受影响。

请求示例

curl -X POST https://api.kyrenpay.com/epay/mapi.php \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "pid=10001" \
  --data-urlencode "type=alipay" \
  --data-urlencode "out_trade_no=ORDER_10002" \
  --data-urlencode "notify_url=https://merchant.example.com/notify" \
  --data-urlencode "name=AI credits" \
  --data-urlencode "money=9.99" \
  --data-urlencode "display_merchant_name=Campaign Store" \
  --data-urlencode "clientip=203.0.113.10" \
  --data-urlencode "sign=lowercase_md5_signature" \
  --data-urlencode "sign_type=MD5"

成功响应示例

{
  "code": 1,
  "trade_no": "K202605260001",
  "out_trade_no": "ORDER_10002",
  "payurl": "https://payment.kyren.io/epay/redirect/order_abc123"
}

Paydify：返回本地支付页，不直接返回付款码

商户一次性加密货币通道绑定 Paydify 时，传 type=crypto，沿用标准签名，不新增 App / 网络等商户必填字段。money 为商品计价金额，money_type 省略时为 CNY；应付 USDT 数量由 Kyren 本地页的有效报价确定。以下是响应结构示例，不是实际交易回包：

{
  "code": 1,
  "trade_no": "order_paydify_example",
  "out_trade_no": "ORDER_PAYDIFY_EXAMPLE",
  "payurl": "https://payment.kyren.io/epay/redirect/order_paydify_example"
}

此响应不包含 Paydify 上游 qrcode 或 img；商户应让买家打开 payurl。不要把 payurl 当成可直接向上游付款的二维码内容。
code=1 仅说明本地订单受理成功，不代表已创建 Paydify 上游支付或已收款。
买家选择 App / 网络并确认 USDT 报价后才创建上游支付，本地页直接展示该笔上游二维码图片。当前不支持 Paydify USDC。
重复提交相同 out_trade_no 时保持原金额、币种和支付方式；未知创建结果由原订单恢复，不通过换订单号重建上游支付。
最终以验签的易支付成功通知或 api.php?act=order 的付款状态为准。环境开通要求见接入概览。

失败响应示例

{
  "code": 0,
  "msg": "IP not allowed"
}

查看 Epay MD5 签名和 mapi.php API 参考。