开发者

简体中文

English

简体中文

English

Appearance

代收订单创建

更新时间: 2026-08-03 00:12
POST

创建一笔代收订单并返回付款继续信息。创建结果无法确认时，先按原 merchantOrderNo 查单；仍查不到再用同一单号和原请求重发。

请求参数

Content-Type / Accept / Api-Key / Timestamp / Nonce / Signature
BODY

请求体

Body 最大限制: 64 KiB
merchantOrderNo必填string(32)

商户订单号：商户侧唯一订单号，必须在同一个商户编号下唯一，用于创建订单时幂等。

  • 示例值：DEMO_PAY_202606010001
productCode必填string(32)

产品编码：商户已开通的产品目录编码，按支持产品编码选择；它决定交易币种和金额精度，不要自行拼接或解析。

  • 示例值：PH_PHP_PAYMENT_QRPH_GCASH
amount必填object

订单金额：创建请求金额对象，只传 value；交易币种由 productCode 决定。

orderDescription必填string(128)

订单描述：本笔代收订单的商品或订单描述；在所选收银台、钱包或渠道支持展示时，可能会展示给付款方，不要放敏感信息。

payer可选object

付款人信息：代收订单的付款人联系方式；需要记录付款人联系方式时传入。

customData可选object

商户自定义数据：可选的商户自定义键值对象，会在订单和最终状态通知中回显；仅用于商户侧关联。最多 20 个键，键名使用 lowerCamelCase 且最多 40 个字符，值为字符串且最多 256 个字符；不要放 Secret、签名、银行卡号、证件号、手机号、邮箱等敏感信息。

  • 示例值：{"cartId":"CART-10001","customerRef":"CUST-90001"}

响应参数

Content-Type / Request-Id / Timestamp / Nonce / Signature
BODY

响应体

platOrderNo必填string(32)

平台订单号：平台侧订单号，用于技术排查和对账；业务查单仍以 merchantOrderNo 为准。

  • 示例值：PHI112606010000000001001
merchantOrderNo必填string(32)

商户订单号：商户侧唯一订单号，必须在同一个商户编号下唯一，用于创建订单时幂等。

  • 示例值：DEMO_PAY_202606010001
status必填string

订单状态：订单当前业务生命周期状态，具体枚举值见下方。

  • 枚举值：
    PROCESSING订单处理中。
    SUCCEEDED订单已成功。
    CANCELED代收订单在成功前已过期或关闭。
failReason可选string(256)

失败原因：订单进入 FAILED 或 CANCELED 等非成功最终状态时返回，面向商户运营展示或排障；商户判断订单状态只看 status。

productCode必填string(32)

产品编码：本笔订单实际使用的产品目录编码；它决定订单国家、币种和金额精度，见支持产品编码。

  • 示例值：PH_PHP_PAYMENT_QRPH_GCASH
country必填string

国家编码：交易或余额所属国家，使用 ISO 3166-1 alpha-2 两位大写编码。见支持国家与币种。

  • 示例值：PH
amount必填object

订单金额：包含金额值和交易币种的金额对象。

referenceNo可选string(64)

上游参考号：平台在已取得上游支付网络、付款机构或收款机构参考号时返回，用于将付款凭证或收款核实结果关联到订单；不是商户订单号、平台订单号或渠道订单号。

  • 示例值：REF-20260601-0001
nextAction可选object

后续动作：创建代收订单时返回的付款继续信息，可能是跳转地址、二维码内容或客户端支付参数；无需继续操作时为空或不返回。

payerSummary可选object

付款人摘要：代收订单返回的付款人联系方式摘要，有值时用于商户对账和客服排查。

customData可选object

商户自定义数据：创建请求中传入的商户自定义键值对象，有值时回显。

  • 示例值：{"cartId":"CART-10001","customerRef":"CUST-90001"}
createTime必填timestamp

创建时间：资源创建时的 Unix 秒级时间戳，JSON number；从 1970-01-01T00:00:00Z 起按秒计数，不携带时区且不受时区影响；展示当地时间时由商户自行转换。

updateTime必填timestamp

更新时间：代收、代付订单中表示当前状态生效时间；余额中表示余额数据更新时间。均为从 1970-01-01T00:00:00Z 起按秒计数的 Unix 时间戳，以 JSON number 返回，不携带时区且不受时区影响；展示当地时间时由商户自行转换。

错误码

本表列出该接口可能返回的错误码。错误体结构见基本规则。

HTTP状态码错误码描述商户如何处理
400INVALID_REQUEST请求无法解析，或不符合 API 契约。检查 requestMethod、requestUrl、Query、Header 和 JSON Body。
400INVALID_JSON请求体不是合法 JSON。发送 UTF-8 编码的合法 JSON 对象。
400PARAMETER_INVALID请求参数值不合法。按 API 字段说明修正不合法字段后重试。
400PARAMETER_MISSING缺少必填请求参数。补齐必填字段后重试。
400AMOUNT_FORMAT_INVALIDamount.value 格式不合法。按主币种单位传正数十进制字符串，例如 100.50。
401INVALID_API_KEYAPI Key 缺失、停用或不存在。检查商户后台配置的 API Key。
401INVALID_SIGNATURE请求签名验签失败。用 API Secret 重新生成签名原文和 Signature。
401TIMESTAMP_INVALIDTimestamp 缺失、格式错误或超出允许窗口。同步服务器时间，并重新生成 Timestamp、Nonce 和 Signature。
401NONCE_REPLAYED同一 API Key 下 Nonce 已被使用。生成新的 Nonce 和 Signature 后再重试。
403PERMISSION_DENIED商户或凭据没有该操作权限。检查凭据权限、商户状态和生产访问权限。
403PRODUCT_NOT_ENABLED商户未开通请求的产品。开通产品后再发送该请求。
409MERCHANT_ORDER_NO_CONFLICTmerchantOrderNo 与已有业务订单冲突。停止变化参数重试，先查询已有 merchantOrderNo。
413REQUEST_BODY_TOO_LARGE请求体超过 64 KiB。缩小 JSON Body 后重试。
415UNSUPPORTED_MEDIA_TYPEPOST Body 不是 UTF-8 JSON。发送 UTF-8 编码的 application/json。
422BUSINESS_REJECTED业务校验拒绝本次请求。阅读 error.message，并修正被拒绝的业务条件。
422AMOUNT_LIMIT_EXCEEDED金额超出产品或商户已配置限额。调整金额或产品配置。
422AMOUNT_PRECISION_INVALIDamount.value 小数位超过所选产品和币种允许的金额精度。按支持国家与币种中的 amountScale 调整金额小数位后重试。
422COUNTRY_UNSUPPORTED当前商户或资源不支持请求的国家。按产品或余额目录选择已支持国家。
422CURRENCY_UNSUPPORTED当前国家、产品或商户不支持请求的币种。按产品或余额目录选择已支持币种。
422PRODUCT_UNSUPPORTED当前国家、币种或商户不支持该产品。使用产品目录中已开通的产品编码。
429FREQUENCY_LIMITED请求过于频繁。短暂等待后再重试；创建类请求结果不确定时先查单。
503ORDER_RESULT_UNKNOWN平台无法确认创建请求是否已产生订单；ErrorResponse 不含 platOrderNo。先按原 merchantOrderNo 查询同类型订单；按间隔查询一段时间后仍不存在时，只能使用同一 merchantOrderNo 和完全一致的原请求重试。