AriaSystems API 中如何获取 proc_payment_id？

2026-10-24支付阿杰

结论

只有在 create_acct_complete 创建账户时实际向支付处理器发起扣款，系统才会生成 proc_payment_id。如果只是创建账户、生成零金额账单、使用免费方案，或没有启用即时收款，该字段为空属于正常情况。

可以按以下步骤处理：

为账户提交有效的支付方式。
在 create_acct_complete 请求中启用即时开票和收款，确认 do_collect 等相关参数已开启。
检查返回的收款状态和错误字段。
如果扣款稍后执行或采用异步处理，请在交易完成后通过 Aria 的支付记录或交易历史接口查询，不要依赖创建账户时的响应。

还要留意字段名称。部分接口或文档使用 payment_proc_id，其他响应结构则可能使用 proc_payment_id，具体应以当前租户所用 API 版本的响应定义为准。

为什么该字段始终为空

proc_payment_id 不是 Aria 创建账户时分配的普通账户编号，而是支付处理器为某次支付交易返回的标识。只有实际完成以下流程，它才可能有值：

创建账户
  → 生成应付账单
  → Aria 向支付网关提交扣款
  → 支付网关受理交易
  → 返回 processor payment ID

以下情况通常不会产生 proc_payment_id：

do_collect 未启用；
创建账户时没有产生应付金额；
方案包含免费试用期，首次扣款日期在未来；
未提供可用于自动扣款的支付方式；
只创建了账单，没有执行收款；
支付由后台任务稍后执行；
请求在到达支付处理器前已经失败；
当前支付处理器不为该类交易返回此标识。

所以，不能只根据 proc_payment_id 是否为空来判断账户有没有创建成功。

请求时启用实际收款

以下是一个示意请求。Aria API 版本不同，参数名称和数据结构也可能不同，请根据当前使用的 create_acct_complete 接口定义进行调整：

{
  "client_no": 12345,
  "auth_key": "REDACTED",
  "client_acct_id": "customer-10001",
  "master_plan_no": 100,
  "do_full_invoicing": true,
  "do_collect": true,
  "payment_method": {
    "payment_method_type": "credit_card",
    "payment_method_token": "TOKEN_FROM_SECURE_PAYMENT_FLOW"
  }
}

仅传入支付资料还不够，请确认请求同时满足以下条件：

do_collect = true
应付金额 > 0
支付方式有效
账单已生成且当前到期
支付处理器配置正常

不要在日志或示例代码中保存完整卡号、CVV 或真实 auth_key。实际项目应优先使用 Aria 或支付服务商支持的 token 化支付方式。

检查完整的收款响应

不要只读取 proc_payment_id。账户号、账单号、错误码、处理器状态和授权码等返回信息也应一并记录：

const result = await createAcctComplete(request);

if (result.error_code && result.error_code !== 0) {
  throw new Error(
    `create_acct_complete failed: ${result.error_code} ${result.error_msg || ""}`
  );
}

console.log({
  acctNo: result.acct_no,
  invoiceNo: result.invoice_no,
  procPaymentId:
    result.proc_payment_id ?? result.payment_proc_id ?? null,
  procAuthCode: result.proc_auth_code ?? null,
  procStatusCode: result.proc_status_code ?? null,
  procStatusText: result.proc_status_text ?? null,
  collectionErrorCode: result.collection_error_code ?? null,
  collectionErrorMsg: result.collection_error_msg ?? null
});

账户创建成功并不代表收款一定成功。如果 collection_error_code 或处理器状态表明收款失败，就不会得到可用的 proc_payment_id。此时应先排查支付失败的原因，例如支付方式无效、网关配置错误或交易被拒绝。

扣款稍后发生时如何获取

如果首次收费日期在未来，或者 Aria 通过后台流程执行收款，那么 create_acct_complete 返回时还没有产生处理器交易 ID。可以这样处理：

保存返回的 acct_no 和 invoice_no。
等待实际支付交易完成。
使用当前 API 版本提供的账户支付历史、交易历史或账单支付查询接口查找对应交易。
从已完成的支付记录中读取 proc_payment_id。

查询时建议结合 acct_no、invoice_no、交易日期和金额进行定位，不要只按日期查找。不同 Aria API 版本的查询方法名称和返回字段可能不同，因此在确认版本前，不应假定某个固定的方法名。

排查清单

如果已经启用即时收款，但该字段仍然为空，可以逐项检查：

请求中的收款开关是否确实传入，是否被客户端默认值覆盖；
创建账户后是否生成了非零金额的 invoice_no；
首次收费日期是否为当前日期；
支付方式是否关联到正确的 billing group；
收款是否在进入支付网关前失败；
collection_error_code、proc_status_code 和相关错误信息是否为空；
Aria 控制台或支付网关后台是否存在对应交易；
当前接口实际返回的是 proc_payment_id 还是 payment_proc_id；
支付处理器是否支持并返回 processor payment ID。

判断时只需确认一点：实际支付交易是否已经发生。如果没有实际扣款，proc_payment_id 自然没有可返回的值。