payeer API 文档

完整 API 参考,助您快速接入 payeer

API 凭证

每个商户账户都有三项凭证,位于 商户设置。请仅在服务器端使用,切勿用于浏览器或移动客户端代码。

App ID

您的商户账户标识。将其作为 appid 参数发送,用于 创建订单 和 查询订单.

API Key

您的私密签名密钥。它 不会 作为请求参数发送。仅可在您的服务器上用于:

  • 计算 sign 字段,用于 /api/createorder (参见 签名)
  • 校验发送至以下地址的支付通知: notify_url (参见 回调通知)

密钥

独立的查询凭证,与您的 App ID 配合用于只读订单查询,接口为 GET /api/order。请将其作为 key 查询参数传入,并同时传入 appid.

获取位置: 登录商户后台并打开 商户设置 ,App ID、API Key 和 Key 均显示在此处,并附有复制按钮。如果您刚完成注册,这些凭证已在创建账户时自动生成。

快速接入

按照以下步骤完成您的第一笔收款。请先在 沙箱调试台 中使用测试凭证调试,再切换到正式密钥。

API 基础地址

所有接口均相对于您的网关源地址(当前部署: https://payeer.online):

  • POST https://payeer.online/api/createorder :JSON API(推荐用于服务端收款)
  • GET …/api/createorder?… :托管 HTML 收银台页面(上手最快;自动轮询状态并跳转至 return_url)
  • GET …/api/order :查询订单状态

选择接入方式

模式 适用场景 您将获得
POST JSON 在您的网站或应用后端进行正式收款 JSON,包含 redirectUrl / selectUrl :由您自行跳转付款人
GET 链接 快速测试或简单的“立即支付”链接 HTML 支付页面(二维码、状态轮询、自动跳转至 return_url)

步骤

  1. 注册或登录 :注册账户请前往 /merchant/register ,登录请前往 /merchant/login.
  2. 复制凭证 :打开 商户设置 并复制您的 App ID、API Key 和 Key(参见 API 凭证).
  3. 配置 Webhook 推送 :在设置中配置默认回调地址 或 为每个订单传入 notify_url 。保存的地址将用于已支付订单的 Webhook(参见 回调通知)。如果两者都为空,则不会发送 Webhook。
  4. 创建订单 :调用 POST /api/createorder (JSON),或打开 GET /api/createorder (托管页面),参数包括 appid, clientip, action=createorder, amount, currency, paymentMethod和 sign。将 clientip 设置为 发起请求的机器的公网 IP (参见 身份验证).
  5. 引导客户付款 :根据 JSON 响应,将付款人引导至 redirectUrl 或 selectUrl (以实际返回的为准)。 selectUrl means an extra step (pick a payment method or crypto) before paying; nextAction 描述该步骤。如果两者都不存在,请使用 /payment/{paymentId} (本网关地址)。
  6. 处理 Webhook :支付成功后,我们会向该订单的回调地址发送 GET 请求,所有参数都放在查询字符串中。请使用您的 API Key 校验签名,并返回 HTTP 200,响应体为 success (参见 回调通知).
  7. 校验订单状态(可选) :创建订单时,设置 return_url ,并在其中加入 {paymentId} 占位符(参见 创建订单),例如 https://yoursite.com/success?paymentId={paymentId}。支付完成后,客户会被跳转回您的页面,并且 {paymentId} 会被替换为真实的订单 ID。请从该 URL 读取 paymentId 查询参数,然后调用 查询订单 ,在服务器端同步最新状态,然后再显示支付成功信息: GET /api/order?action=order&appid=YOUR_APPID&paymentId=PAYMENT_ID_FROM_URL&sign=SIGN (使用您的 key 签名;参见查询订单)。根据响应中的字段 status / status_str 更新本地订单。Webhook 仍是权威的异步通知方式;此流程用于付款人回到您的返回页面时即时确认。

端到端示例(POST JSON)

服务端最简流程,前提是您已计算出 sign (参见 签名):

// 1. Create order (run on your server; replace YOUR_* placeholders) const res = await fetch('https://payeer.online/api/createorder', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ appid, clientip, action: 'createorder', amount: 100, currency: 'CNY', paymentMethod: 'alipay', clientOrderId: 'ORDER-001', return_url, notify_url, sign, sign_type: 'MD5' }) }); const { data } = await res.json(); // 2. Redirect payer to checkout const checkoutUrl = data.redirectUrl || data.selectUrl || `/payment/${data.paymentId}`; // response.redirect(checkoutUrl) — your framework // 3. Webhook handler (express example) app.get('/api/notify', (req, res) => { const expected = signStr(req.query, process.env.API_KEY); // same algorithm as #signature if (expected !== req.query.sign) return res.status(400).send('invalid sign'); // update your order if req.query.status_str === 'paid' res.status(200).send('success'); // must be the string "success" });
提示: 上线前,请先在 沙箱调试台 中测试签名和示例请求。

身份验证

请参阅 API 凭证 ,获取您的 appid。创建订单请求还必须提供 clientip ,即发起该 HTTP 请求的客户端公网 IP(通常是您后端服务器的出口 IP;如果您从浏览器代理请求,则为付款人的 IP)。

clientip 必须与请求 IP 一致。 如两者不一致, /api/createorder 返回 HTTP 403,错误信息为 Request IP does not match clientip。如部署在反向代理之后,请确保服务器转发真实的客户端 IP,并将同一值传入 clientip.
安全提示: 请妥善保管 API Key 和 Key,切勿在客户端代码、移动应用或公开仓库中泄露。只有 App ID 和已签名的请求可以离开您的后端。

签名验证

所有创建或修改数据的 API 请求都需要签名验证,以确保数据完整、防止篡改。

签名原理

签名基于所有请求参数(不包括 sign 和 sign_type)以及您的 API Key(安全保存在服务器端)计算得出。

签名算法:
  1. 收集所有参数,排除 sign 和 sign_type
  2. 按键名的字母顺序对参数排序
  3. 将参数拼接为 key=value 键值对,连接符为 &
  4. 将您的 API Key 追加到字符串末尾
  5. 对结果字符串计算 MD5 哈希(小写)

签名参数

参数 类型 必填 描述
sign string 必填 所有参数的 MD5 签名(使用您的 API Key 计算)
sign_type string 可选 签名类型,目前仅支持 MD5 (默认: MD5)
重要: 签名必须完全一致。如果签名验证失败,请求将被拒绝并返回 400 错误。请对 扁平的 请求字段签名,即发送至 /api/createorder 的字段(而非嵌套的 JSON 对象)。空字符串也参与签名;仅忽略值为 null / undefined 的字段。

计算示例(createorder)

已知 API Key 42ba8e8f-7cbb-4bf9-ba2a-57904f3d9451 及以下参数(尚未加入 sign):

签名明文(排序后的 key=value,以 &),然后追加 API Key 并计算 MD5:

action=createorder&amount=100&appid=YOUR_APPID&clientOrderId=YOUR_ORDER_ID_123&clientip=127.0.0.1&currency=CNY&description=Test order&notify_url=https://example.com/api/notify&paymentMethod=alipay&return_url=https://example.com/payment/success?paymentId={paymentId}42ba8e8f-7cbb-4bf9-ba2a-57904f3d9451 sign = 9bb303e3116d862fbeb23bd8a8a8b07d

sign_type 会随请求发送,但 不参与 签名。数值类型的 amount 在 JSON 中按发送时的原样参与签名(例如 100,而不是 100.00).

代码示例

计算 sign ,在您的服务器上使用与请求中相同的扁平参数进行计算:

import hashlib API_KEY = 'YOUR_API_KEY' def sign_createorder(params: dict) -> str: filtered = { k: v for k, v in params.items() if k not in ('sign', 'sign_type') and v is not None } plain = '&'.join(f'{k}={filtered[k]}' for k in sorted(filtered)) return hashlib.md5((plain + API_KEY).encode('utf-8')).hexdigest().lower() payload = { 'appid': 'YOUR_APPID', 'clientip': '127.0.0.1', 'action': 'createorder', 'amount': 100, 'currency': 'CNY', 'paymentMethod': 'alipay', 'description': 'Test order', 'clientOrderId': 'YOUR_ORDER_ID_123', 'return_url': 'https://example.com/payment/success?paymentId={paymentId}', 'notify_url': 'https://example.com/api/notify', } payload['sign'] = sign_createorder(payload) payload['sign_type'] = 'MD5'
const crypto = require('crypto'); const API_KEY = 'YOUR_API_KEY'; function signCreateorder(params) { const filtered = {}; for (const [k, v] of Object.entries(params)) { if (k === 'sign' || k === 'sign_type') continue; if (v === null || v === undefined) continue; filtered[k] = v; } const plain = Object.keys(filtered).sort() .map((k) => `${k}=${filtered[k]}`) .join('&'); return crypto.createHash('md5').update(plain + API_KEY).digest('hex').toLowerCase(); } const payload = { appid: 'YOUR_APPID', clientip: '127.0.0.1', action: 'createorder', amount: 100, currency: 'CNY', paymentMethod: 'alipay', description: 'Test order', clientOrderId: 'YOUR_ORDER_ID_123', return_url: 'https://example.com/payment/success?paymentId={paymentId}', notify_url: 'https://example.com/api/notify', }; payload.sign = signCreateorder(payload); payload.sign_type = 'MD5';
<?php $apiKey = 'YOUR_API_KEY'; function sign_createorder(array $params, string $apiKey): string { unset($params['sign'], $params['sign_type']); $params = array_filter($params, fn($v) => $v !== null); ksort($params); $plain = implode('&', array_map( fn($k) => $k . '=' . $params[$k], array_keys($params) )); return md5($plain . $apiKey); } $payload = [ 'appid' => 'YOUR_APPID', 'clientip' => '127.0.0.1', 'action' => 'createorder', 'amount' => 100, 'currency' => 'CNY', 'paymentMethod' => 'alipay', 'description' => 'Test order', 'clientOrderId' => 'YOUR_ORDER_ID_123', 'return_url' => 'https://example.com/payment/success?paymentId={paymentId}', 'notify_url' => 'https://example.com/api/notify', ]; $payload['sign'] = sign_createorder($payload, $apiKey); $payload['sign_type'] = 'MD5';

创建订单

创建支付订单。根据支付方式,响应中包含收银台地址(redirectUrl / selectUrl)和/或二维码图片地址,具体取决于支付方式。

POST /api/createorder 需要鉴权

发送 JSON 请求体,需设置 Content-Type: application/json。返回包含收银台地址的 JSON,供您的服务器跳转付款人。

请求参数

参数 类型 必填 描述
appid string 必填 您的应用 ID
clientip string 必填 您的客户端 IP 地址
action string 必填 必须为 createorder
amount number 必填 订单金额(例如 100.00)
currency string 必填 币种代码: CNY, USD,或 BDT (使用 BDT 配合 eps, paystation,或 aamarpay)
paymentMethod string 必填 支付方式(参见支付方式章节)
sign string 必填 MD5 签名(参见签名章节)
sign_type string 可选 签名类型(默认: MD5)
description string 可选 订单描述
customerName string 可选 客户姓名
customerEmail string 可选 客户邮箱
customerPhone string 可选 客户手机号
freekassaSystemId integer 可选 当 paymentMethod=freekassa时:FreeKassa 支付系统 ID(i). 不传 则延后选择:响应包含 selectUrl 和 nextAction=freekassa_select ,供付款人选择支付方式并获取汇率报价。若传入该参数,则立即初始化 FreeKassa。之后通过以下接口确认: POST /api/freekassa/confirm.
allowedPaymentMethods string 可选 当 paymentMethod=select时:以逗号分隔的网关代码,指定付款人选择页面上显示的支付方式(例如 alipay,wxpay,freekassa)。不传则显示该订单币种和商户账户已启用的所有支付方式。USD 订单默认包含 balance (已登录客户的账户余额);如需排除,可传入例如 allowedPaymentMethods=alipay,wxpay。参与签名。
lang string 可选 付款人选择页面的界面语言(例如 en, zh, es)。默认 en。若不为 en, selectUrl 会使用语言路径前缀(例如 /zh/payment/{orderId}?step=select)。提供时参与签名。
return_url string 可选 支付完成后的返回地址(如提供,将自动跳转)。您可以使用 {paymentId} 占位符,跳转时会自动替换为实际的支付 ID。示例: https://example.com/success?paymentId={paymentId}
notify_url string 可选 该订单的 Webhook 地址。如未传入,则使用 商户设置 中的默认回调地址。如果两者都为空,则不会为该订单发送 Webhook。
clientOrderId string 可选 客户自己的订单标识,会被保存并在响应中返回。提供该参数后,若同一商户的订单仍处于 pending 或 ready 状态,重复的创建请求将返回已有订单(幂等;可放心刷新 GET 支付链接)。当订单变为 paid, failed,或 cancelled,之后即可新建订单,并可沿用相同的 clientOrderId.
payerRef string 可选 您为付款客户设定的稳定标识(1–64 个字符: A-Z a-z 0-9 _ . : -;请勿传入邮箱或手机号)。对于支持自动确认的加密货币网络,相同的 payerRef 始终对应同一个充值地址,回头客可以重复使用。若不传 payerRef,每个订单都会分配独立的一次性地址。每次付款前请务必先创建订单;没有对应订单的转账将由人工处理。
重要说明:
  • IP 地址校验: 请求中的 clientip 参数必须与实际请求 IP 地址一致,否则请求将被拒绝(403 错误)。
  • 签名验证: 所有请求都必须包含有效的 MD5 签名。签名计算错误将导致请求失败(400 错误)。
  • 返回地址占位符: 您可以使用 {paymentId} 占位符,放在 return_url中。付款完成后跳转时,系统会自动将其替换为实际的支付 ID。
  • 回调地址: 按订单传入的 notify_url 会覆盖设置中的地址;否则将设置中的默认地址保存到订单上。仅当保存的地址非空时才会发送 Webhook。
  • 幂等 clientOrderId: 重复 POST 或刷新 GET 支付链接时,如使用相同的 clientOrderId ,不会创建新订单,前提是订单状态为 pending 或 ready.

请求示例

成功响应

响应字段(data)

字段 描述
paymentId / orderId 网关订单标识(两者值相同)。可用于 查询订单 和 return_url 占位符。
redirectUrl 立即引导付款人支付的地址(网关页面、外部 PSP 或托管收银台)。
selectUrl 付款人需要先选择支付方式时返回(paymentMethod=select, deferred FreeKassa/NOWPayments, or USDT Direct). Often equals redirectUrl 相同。
nextAction 当返回 selectUrl 时的下一步提示,例如: payment_method_select, freekassa_select, nowpayments_select, usdt_direct_pay.
payableAmount 当 paymentMethod=usdt_direct时:付款人需支付的精确 USDT 金额(含一段小额随机尾数用于识别)。对已有 USDT Direct 会话进行幂等重复获取时也会返回。
qrImageUrl 二维码图片地址(如适用;对仅支持跳转的支付方式可能为 null )。
status / statusString 订单状态,参见 订单状态。余额支付可能会立即返回 paid 状态。

跳转规则: redirectUrl || selectUrl || /payment/{paymentId}.

错误响应

签名验证: 该接口需要签名验证。签名须基于所有参数(不包括 sign 和 sign_type)以及您的 API Key 计算。详见 签名 一节。
GET /api/createorder 需要鉴权

创建新的支付订单并获取 HTML 支付页面。页面每 4 秒自动轮询订单状态,3 分钟后超时,并会自动跳转至 return_url (支付完成时)。

请求参数

备注: 所有参数均以查询参数(URL 参数)形式传递,参数与上方 POST 请求相同。

参数 类型 必填 描述
appid string 必填 您的应用 ID
clientip string 必填 您的客户端 IP 地址
action string 必填 必须为 createorder
amount number 必填 订单金额(例如 100.00)
currency string 必填 币种代码: CNY, USD,或 BDT (使用 BDT 配合 eps, paystation,或 aamarpay)
paymentMethod string 必填 支付方式(参见支付方式章节)
sign string 必填 MD5 签名(参见签名章节)
sign_type string 可选 签名类型(默认: MD5)
description string 可选 订单描述
customerName string 可选 客户姓名
customerEmail string 可选 客户邮箱
customerPhone string 可选 客户手机号
freekassaSystemId integer 可选 当 paymentMethod=freekassa时:FreeKassa 支付系统 ID(i). 不传 则延后选择:响应包含 selectUrl 和 nextAction=freekassa_select ,供付款人选择支付方式并获取汇率报价。若传入该参数,则立即初始化 FreeKassa。之后通过以下接口确认: POST /api/freekassa/confirm.
allowedPaymentMethods string 可选 当 paymentMethod=select时:以逗号分隔的网关代码,指定付款人选择页面上显示的支付方式(例如 alipay,wxpay,freekassa)。不传则显示该订单币种和商户账户已启用的所有支付方式。USD 订单默认包含 balance (已登录客户的账户余额);如需排除,可传入例如 allowedPaymentMethods=alipay,wxpay。参与签名。
lang string 可选 付款人选择页面的界面语言(例如 en, zh, es)。默认 en。若不为 en, selectUrl 会使用语言路径前缀(例如 /zh/payment/{orderId}?step=select)。提供时参与签名。
return_url string 可选 支付完成后的返回地址(支付成功时页面会在 1 秒后自动跳转)。您可以使用 {paymentId} 占位符,跳转时会自动替换为实际的支付 ID。示例: https://example.com/success?paymentId={paymentId}
notify_url string 可选 该订单的 Webhook 地址。如未传入,则使用商户设置中的默认回调地址。如果两者都为空,则不会发送 Webhook。
clientOrderId string 可选 客户自己的订单标识,会被保存并在响应中返回。提供该参数后,若同一商户的订单仍处于 pending 或 ready 状态,重复的创建请求将返回已有订单(幂等;可放心刷新 GET 支付链接)。当订单变为 paid, failed,或 cancelled,之后即可新建订单,并可沿用相同的 clientOrderId.
payerRef string 可选 您为付款客户设定的稳定标识(1–64 个字符: A-Z a-z 0-9 _ . : -;请勿传入邮箱或手机号)。对于支持自动确认的加密货币网络,相同的 payerRef 始终对应同一个充值地址,回头客可以重复使用。若不传 payerRef,每个订单都会分配独立的一次性地址。每次付款前请务必先创建订单;没有对应订单的转账将由人工处理。

请求示例

GET /api/createorder?appid=YOUR_APPID&clientip=127.0.0.1&action=createorder&amount=100¤cy=CNY&paymentMethod=alipay&description=Test+order&clientOrderId=YOUR_ORDER_ID_123&return_url=https%3A%2F%2Fexample.com%2Fsuccess%3FpaymentId%3D%7BpaymentId%7D¬ify_url=https://example.com/api/notify&sign=CALCULATED_SIGNATURE&sign_type=MD5
重要说明:
  • IP 地址校验: 请求中的 clientip 参数必须与实际请求 IP 地址一致,否则请求将被拒绝(403 错误)。
  • 签名验证: 所有请求都必须包含有效的 MD5 签名。签名计算错误将导致请求失败(400 错误)。
  • 返回地址占位符: 您可以使用 {paymentId} 占位符,放在 return_url中。付款完成后跳转时,系统会自动将其替换为实际的支付 ID。
  • 回调地址: 按订单传入的 notify_url 会覆盖设置中的地址;否则将设置中的默认地址保存到订单上。
  • 幂等 clientOrderId: 刷新此支付链接(或重复请求)时,如使用相同的 clientOrderId ,不会创建新订单,前提是订单状态为 pending 或 ready.

响应

返回一个 HTML 支付页面,包含:

  • 订单信息展示
  • 支付二维码(订单就绪时)
  • 自动轮询状态(每 4 秒)
  • 3 分钟倒计时
  • 自动跳转至 return_url (支付完成时)
页面功能:
  • 每 4 秒自动轮询订单状态
  • 显示 3 分钟倒计时
  • 自动跳转至 return_url (支付完成后延迟 1 秒)
  • 3 分钟后自动超时
  • 显示供扫码支付的二维码
签名验证: 该接口需要签名验证。签名须基于所有参数(不包括 sign 和 sign_type)以及您的 API Key 计算。详见 签名 一节。

查询订单

查询单个订单详情或列出多个订单。

典型用法:付款人经由 return_url 配合 paymentId={paymentId},回到您的页面后,使用解析出的 paymentId 调用此接口,在您的成功页面同步订单状态(参见 快速接入 第 7 步)。

GET /api/order 需要鉴权

请求参数

参数 类型 必填 描述
appid string 必填 您的应用 ID
sign string 必填(或 key) 推荐。将其余所有参数按名称排序,拼接为 k=v&k=v,并在末尾直接拼接您的 key,再计算 MD5(小写),方式与 createorder 的签名相同(后者使用您的 apikey)。这样 key 就不会出现在 URL 中。
key string 旧版 您的 key(UUID 格式),以明文发送。目前仍可使用,但任何记录 URL 的环节(代理、CDN)都能看到它。请改用 sign ;不要同时发送两者。
timestamp, nonce number, string 可选 防重放保护,适用于包括 createorder 在内的所有签名请求。 timestamp 为以秒或毫秒表示的 Unix 时间,且与服务器时间相差不得超过 5 分钟。 nonce 为随机字符串(最长 128 个字符),且只能使用一次。两者均属于签名参数,并可设置为您账户的必填项。
action string 必填 order (单个)或 orders (列表)
paymentId string action=order 时必填 要查询的支付 ID
page number 可选 页码(默认 1,仅适用于 action=orders)
limit number 可选 每页条数(最大 50,默认 10,仅适用于 action=orders)

请求示例

GET /api/order?action=order&appid=YOUR_APPID&nonce=8f3a1c&paymentId=abc123def456&timestamp=1793000000&sign=MD5_OF_SORTED_PARAMS_PLUS_KEY

单个订单响应

订单列表响应

回调通知

当订单状态变为 paid,系统会自动向您指定的地址发送回调通知。

回调地址配置:
  • 创建订单时传入 notify_url ,为该订单单独指定 Webhook 地址
  • 如未传入,则将 商户设置 中的默认回调地址保存到订单上
  • 仅当订单保存了非空的回调地址(来自任一来源)时才会发送 Webhook

回调请求

系统会发送 GET 请求至您的回调地址,参数通过查询字符串传递,如下:

参数 类型 描述
paymentId string 唯一支付标识
amount string 订单金额(字符串形式,例如 “2.2”)
currency string 币种代码: CNY, USD,或 BDT (使用 BDT 配合 eps, paystation,或 aamarpay)
status string 订单状态码: "2" (已支付)
status_str string 订单状态字符串: "paid"
paymentMethod string 使用的支付方式: alipay, wxpay, crypto, eps, paystation,或 aamarpay
description string 订单描述(如有提供)
completedTime string 支付完成时间,ISO 8601 格式(例如 “2025-12-01T02:32:05.877Z”)
createdAt string 订单创建时间,ISO 8601 格式(例如 “2025-12-01T02:31:43.997Z”)
clientOrderId string 客户订单号(如创建订单时提供)
sign string 用于校验回调真实性的 MD5 签名
sign_type string 签名类型: MD5

回调示例

签名验证

您必须校验回调签名,以确保请求真实可信。签名计算方法与 API 请求相同:

  1. 收集所有参数,排除 sign 和 sign_type
  2. 按键名的字母顺序对参数排序
  3. 将参数拼接为 key=value 键值对,连接符为 &
  4. 将您的 API Key 追加到字符串末尾
  5. 对结果字符串计算 MD5 哈希(小写)
  6. 将计算出的签名与 sign 参数进行比对
安全提示: 处理付款前务必校验回调签名。不要信任签名无效的回调。

回调响应

您的回调接口必须返回特定响应,以确认已成功接收:

  • 成功: 返回 HTTP 200 状态码,且响应体包含字符串 "success" (不区分大小写)。响应体必须恰好为 "success" (例如 "success", "SUCCESS",或 "Success")。其他任何响应都将视为失败并触发重试。
  • 失败: 返回任何非 200 状态码,或返回 HTTP 200 但响应体不是 "success" (不区分大小写),都会触发重试
重要: 仅在满足以下条件时,回调才被视为成功:
  1. HTTP 状态码为 200
  2. 响应体(去除首尾空白,不区分大小写)等于 "success"

成功响应示例:

  • "success" ✓
  • "SUCCESS" ✓
  • "Success" ✓

失败响应示例(会触发重试):

  • {"code": 1, "message": "success"} ✗(不是字符串“success”)
  • "ok" ✗(不是“success”)
  • "received" ✗(不是“success”)
  • HTTP 500 或任何非 200 状态码 ✗

重试机制

系统对失败的回调实现了自动重试机制:

  • 最大尝试次数: 20 次
  • 重试间隔: 指数退避(重试间隔逐步增加)
  • 重试条件: 以下情况会重试回调:
    • 您的服务器返回非 200 状态码
    • 您的服务器返回 HTTP 200,但响应体不是 "success" (不区分大小写)
    • 请求失败(网络错误、超时等)
  • 成功: 一旦您的服务器返回 HTTP 200 且响应体为 "success" (不区分大小写)后,系统将不再为该订单发送回调
最佳实践:
  • 实现幂等:处理订单前先检查该订单是否已处理过
  • 处理前先校验签名
  • 收到并校验回调后,立即返回 HTTP 200,响应体为 "success" ,然后再按需异步处理订单
  • 记录所有回调请求,便于调试和审计
  • 回调地址请使用 HTTPS,确保传输安全
  • 重要: 请确保处理成功时,回调接口准确返回字符串 "success" (不区分大小写)

订单状态码

订单有以下几种状态值:

代码 字符串 描述
0 pending 订单已创建,已保存在本地
1 ready 订单已提交至支付服务商,已生成二维码
2 paid 支付成功
3 failed 支付失败
4 cancelled 订单已取消

支付方式

支持的支付方式及其币种兼容性:

方式 代码 支持的币种 描述
支付宝 alipay CNY, USD 支付宝移动支付
微信支付 wxpay CNY, USD 微信移动支付
Heleket(加密货币) heleket USD Redirect to Heleket payment page. Webhook: POST /api/gatewaynotification/heleket/webhook.
信用卡 / 借记卡 eps BDT, USD 支持信用卡 / 借记卡支付。
信用卡 / 借记卡 paystation BDT, USD PayStation(孟加拉国):通过 PayStation 收银台支持银行卡及本地支付方式。USD 订单按配置的 USD→BDT 汇率以 BDT 扣款。
aamarpay aamarpay BDT, USD aamarpay(孟加拉国):跳转收银台。BDT 原样发送;USD 按系统 USD→BDT 汇率(与 EPS/PayStation 相同)在本地换算后以 BDT 扣款。回调: /api/gatewaynotification/aamarpay/return/success (通过 Search Transaction 核验)。
FreeKassa freekassa RUB, USD, EUR, UAH, KZT 两步流程: createorder 不带 freekassaSystemId 时返回 selectUrl;付款人在网关页面选择支付方式(如需会提供汇率报价),然后调用 POST /api/freekassa/confirm。ID 列表: /api/freekassa/currencies。通知地址: /api/gatewaynotification/freekassa/notify (需响应 YES).
NOWPayments(加密货币) nowpayments USD, EUR, GBP, BRL, NZD 两步流程: createorder 时返回 selectUrl; payer chooses crypto on gateway page (min-amount check via NOWPayments API), then confirm creates invoice with pay_currency. IPN: POST /api/gatewaynotification/nowpayments/ipn 配合 x-nowpayments-sig verification.
USDT 直付 usdt_direct CNY, USD, BDT 托管收银台地址: /payment/{orderId}/usdt-direct。付款人选择网络(TRC20/BEP20 等),按页面显示支付 精确的 payableAmount USDT,然后提交链上交易哈希。自动审核会根据高级设置中的币种配置,采用链上验证、Binance hisrec、dual 或 Binance Pay 方式。不经过第三方 IPN:哈希验证通过或经超级管理员批准后,在内部完成结算。响应包含 nextAction=usdt_direct_pay 和 payableAmount (初始化后)。
余额 balance CNY, USD 使用商户账户余额支付。即时结算,无需跳转或二维码。响应包含 paidWithBalance: true 和 status=2 (已支付)。
付款人自选(多网关) select CNY, USD, BDT, EUR, GBP, BRL, NZD 延迟选择流程: createorder 配合 paymentMethod=select 时返回 selectUrl 和 nextAction=payment_method_select。可选参数 lang (默认 en)用于设置付款人选择页面的语言及 URL 前缀(例如 /zh/payment/{orderId}?step=select)。付款人会看到订单金额及各支付方式的最低/最高限额,然后调用 POST ?step=confirm 配合 paymentMethod。USD 订单还可使用 balance:付款人须先登录 /merchant/login;款项将从付款人的平台账户余额中扣除,并记入商户账户。可选参数 allowedPaymentMethods restricts the list. FreeKassa / NOWPayments still use their secondary selection pages after confirm. usdt_direct 确认后跳转至 USDT Direct 收银台。
币种与支付方式兼容性:
  • CNY(人民币): 支持 alipay, wxpay, usdt_direct和 balance
  • USD(美元): 支持 alipay, wxpay, eps, paystation, aamarpay, freekassa, heleket, nowpayments, usdt_direct和 balance
  • BDT(孟加拉塔卡): 支持 eps, paystation, aamarpay和 usdt_direct
  • RUB / UAH / KZT: 支持 freekassa (仅此一种)
  • EUR: 支持 freekassa 和 nowpayments
  • GBP / BRL / NZD: 支持 nowpayments (仅此一种)

错误码

常见错误码及其含义:

代码 描述
400 请求错误:参数无效或业务逻辑错误
401 未授权:appid 或 apikey 无效
403 禁止访问: clientip 与请求 IP 不一致,或商户账户已被停用
429 请求过多:超出频率限制
500 服务器内部错误:服务端出错