Payment configuration

Admin → Payment gateways configures platform payment integrations. Customer balance, top-ups and transactions are in Settings → Credits; customers should not need merchant credentials to pay.

Configure EPay

1. Open Payment gateways and inspect each integration’s configured status.
2. Choose Configure for EPay.
3. Enter the merchant ID, gateway URL, notification URL and return URL supplied for your deployment. Enter the merchant signing key privately.
4. Choose the supported Alipay or WeChat Pay methods, and enable the integration when its configuration is ready.
5. Save, then reopen the configuration to confirm the stored state. Reads indicate whether a key exists rather than returning the saved key.

Configuration saves use a revision. Reload after a stale-revision conflict rather than overwriting another administrator’s changes. Keep signing secrets out of source control, public files, screenshots and logs.

The supported gateway inventory can include integrations configured outside this dialog. A listed integration is not a promise that the dashboard can edit it; the current form edits EPay. See the generated EPay configuration operation for exact fields and authorization.

Development gateway

Local development includes a Mock payments card. Open Configure, enable mock payments and save. A fresh development installation leaves it disabled. The saved choice persists across restarts; the application displays a warning whenever it is enabled. Ordinary and production builds cannot activate it.

Only payments are simulated. LLM calls still incur real upstream Provider charges. Keep Niu API keys and Provider API keys private and do not offer public access to a mock-funded environment. Disabling the mock stops new test checkouts; notifications for existing test orders can finish.

Cards distinguish Not configured, Disabled, Needs attention and Verified using the same readiness evidence as workspace admission. Stripe also shows its account check; notification verification is shown separately. Configured is a fallback when verification is unavailable, not proof of readiness. Use Refresh verification to reload the evidence and follow the indicated setup or Credits link for missing requirements.

Verify payment behavior separately

Configured and enabled status do not establish merchant activation or a successful top-up. Verify the actual deployment’s signed checkout, notification handling and funding records before advertising a method as available. A return-page visit is not settlement evidence. Do not grant customer balance from an unverified callback or duplicate an already recorded payment.

External refunds and complete commercial settlement qualification have their own implementation boundaries; do not infer them from a working configuration save.

Stripe readiness

Stripe-backed workspace admission requires a recent successful account check and a verified paid notification for a checkout created with the same effective configuration. Check Stripe account is read-only and creates no payment; it does not establish notification delivery. The server refreshes account checks every five minutes, and successful evidence expires after ten minutes. A temporary check outage cannot extend that expiry; rejected credentials or disabled charges revoke readiness immediately.

To verify the payment integration, an authorized account owner uses Settings → Credits to create a top-up through the configured Stripe checkout. Account funding remains accessible while workspace features are blocked. Only a signed, matching notification that settles the saved order establishes notification evidence. Visiting the return page, polling an order, or a payment from an older configuration does not qualify the current integration. Real checkout may charge money; use the deployment’s Stripe test configuration when validating a test installation. Changing credentials, notification secrets, checkout settings or currency requires evidence for the changed configuration.

A company with explicit funding, an uncorrected noncash grant or an approved credit allowance can use the self-hosted path without merchant setup. This does not certify Stripe or waive request balance checks. The account-check rule above applies to Stripe; EPay and ZhifuX use the integration evidence described below.

EPay and ZhifuX integration evidence

Disabling EPay stops new checkouts while keeping signed notifications for existing orders available. While orders remain unsettled, a pure enable/disable change is allowed; changing credentials or checkout fields is blocked to preserve their original verification settings.

EPay requires a verified signed payment notification and durable settlement for a checkout created with the current configuration. The first checkout captures that configuration atomically with its saved link. A legacy order whose original configuration is unknown can still settle, but cannot qualify a new configuration.

Native ZhifuX requires both a verified signed notification and independent server-confirmed settlement for the same configuration-bound order. Either may arrive first. The existing query permission and rate limits still apply; no additional periodic merchant-health query is introduced. Notification receipt alone never funds an account, and reconciliation alone does not establish callback delivery.

These adapters expose integration evidence rather than Stripe-style live account eligibility. Changing merchant credentials, endpoints, notification/return addresses or payment methods invalidates previous configuration evidence. Evidence from a successful integration check is not a guarantee that every later payment succeeds. Pending payments retain their individual recovery workflow.

Credit and administrator gifts

Approved credit permits a customer balance to become negative up to its configured limit, after outstanding reservations. Zero credit implements prepaid access. Changing credit creates no receipt and adds no balance. The existing credit-policy endpoint requires installation write authority and a matching revision.

A platform administrator can issue a noncash gift using grantCustomerBalance or NiuAdminClient.grantCustomerBalance. Supply an exact positive nanounit amount, a reason and a UUID idempotency key. Preserve that key when retrying an uncertain result. Identical retries return the original gift; changing its amount, currency or reason conflicts. Customer owner/admin roles cannot issue their own gifts. Use Admin → Account balances → Grant noncash balance to prepare and explicitly issue the saved gift.

For a mistaken wholly unused gift, open Noncash grants → Issued gifts → Correct unused gift, review its original amount and reason, and enter a correction reason. Confirm Remove unused gift. The platform-only correction API and SDK method correctUnusedCustomerBalanceGrant append a separate audited adjustment. The full original amount must match; partial correction is not supported. Accounts with paid request history, consumption, refunds, open request reservations or unknown financial sources are refused. Approved credit and all historical grants remain unchanged. A correction is neither a merchant refund nor a consumption/revenue adjustment.

An uncertain response requires Check saved status or getIssuedCustomerBalanceGrant. An absent correction in one snapshot does not prove an in-flight request failed. Retry only the same original input and idempotency key; do not create a new gift or adjustment. One original gift can have one full correction. Issued-gift history includes older direct API grants, while Saved intents retains preparation and issuance recovery.

Gift issuance is neither cash collection nor income. Gifts are a separate funding source for subsequent consumption; they do not retrospectively forgive debt or change a request’s pinned selling price. The source allocation records the gift and non-gift components, and a customer refund restores those components. Do not use a gift as a verified payment or an external cash refund.

Revenue and receipts

Read the platform-only financial summary with NiuAdminClient.getCustomerFinancialSummary({ currency: 'USD', days: 30 }). It reports a UTC posting interval, independent of the Provider comparison’s dispatch interval. Choose 7, 30 or 90 days.

The following is the required accounting example, not a claimed completed payment:

Measure	Amount
Nominal consumption	100
Consumed gift / sales allowance	5
Recognized revenue	95
Cash received	95

Do not present revenue as 100 and an offsetting expense as 5. Gift issuance alone creates no revenue or promotional expense. A prepaid receipt precedes consumption; credit-backed consumption can precede payment. A later credit repayment does not recognize the same revenue again. Customer refunds reduce the original non-gift revenue and restore the original gift component; refund-period revenue can be negative.

Missing or unknown historical source allocation leaves the full revenue and gift-allowance totals unavailable. The explicitly named known subtotals are partial. They cannot replace complete totals. Verified cash receipts are separate from consumption; overlapping legacy invoice-payment and balance-funding references leave the combined receipt total unavailable pending reconciliation. A recorded funding reversal is not evidence of an external refund transfer.

The summary is an operational reconciliation read. Populated gift-consumption/refund workflows, closed-period accounting and the complete financial dashboard still require acceptance; a saved gift or successful summary read does not establish them.

管理后台 → 支付网关（Admin → Payment gateways）用于配置平台支付集成。客户余额、充值和交易记录位于设置 → 额度与充值（Settings → Credits）中；客户无需拥有商户凭证即可完成支付。

配置易支付（EPay）

1. 打开支付网关（Payment gateways），检查各项集成的配置状态。
2. 为 EPay 选择配置（Configure）。
3. 输入为您的部署环境提供的商户 ID、网关 URL、异步通知 URL（notification URL）和同步跳转 URL（return URL）。请私密输入商户签名密钥。
4. 选择受支持的支付宝（Alipay）或微信支付（WeChat Pay）方式，并在配置就绪后启用该集成。
5. 保存后重新打开配置以确认已存储的状态。读取操作仅会指示密钥是否存在，而不会返回已保存的密钥明文。

配置保存受修订版本控制。如果遇到过期修订版本冲突，请重新加载页面，切勿直接覆盖其他管理员所做的更改。请勿将签名密钥放入源代码版本控制、公开文件、截图或日志中。

受支持的支付网关清单可能包含在此对话框之外配置的集成。列出的集成并不承诺都可在控制台中编辑；当前表单仅用于编辑 EPay。有关确切字段与授权要求，请参阅自动生成的 EPay 配置操作。

开发环境模拟网关

本地开发环境包含一张模拟支付（Mock payments）卡片。点击配置（Configure），启用模拟支付并保存。全新的开发环境默认禁用该项。已保存的选择在重启后依然保留；只要启用了模拟支付，应用顶部就会显示醒目警告。普通构建与生产构建无法激活该功能。

模拟支付仅模拟充值付款环节，大语言模型调用仍会产生真实的上游模型供应商费用。请妥善保管 Niu API 密钥与供应商 API 密钥，切勿向公众开放使用模拟资金充值的环境。禁用模拟支付会停止创建新的测试结账单，但已有测试订单的回调通知仍可完成处理。

各网关卡片使用与工作空间准入相同的就绪证据，区分未配置（Not configured）、已禁用（Disabled）、需要处理（Needs attention）和已验证（Verified）状态。Stripe 还会额外显示其账户检查结果，并将回调通知验证状态分开展示。当验证信息不可用时，已配置（Configured）仅作为回退显示，不构成就绪证明。可点击刷新验证（Refresh verification）重新加载验证证据，并按照提示的设置链接或“额度与充值”（Credits）链接补齐缺失项。

独立验证支付行为

“已配置”和“已启用”状态并不代表商户已激活或充值已成功。在对外宣称某种支付方式可用之前，请先验证实际部署环境中的签名结账、回调通知处理以及入账记录。访问同步返回页面（return page）不能作为资金结算凭证。切勿根据未经验证的回调向客户增加余额，也不要重复入账已记录的支付。

外部原路退款与完整的商业结算资质有其各自独立的实现边界；请勿仅凭配置保存成功就推断这些能力已经就绪。

Stripe 就绪验证

基于 Stripe 的工作空间准入要求同时具备近期成功的账户检查结果，以及针对相同生效配置所创建结账单的已验证付款回调通知。检查 Stripe 账户（Check Stripe account）为只读操作，不会创建付款，也不能证明回调通知可达。服务端每 5 分钟刷新一次账户检查，成功证据在 10 分钟后过期。临时的检查网络故障不会延长过期时间；一旦凭证被拒绝或收款权限被禁用，就绪状态会立即吊销。

要验证支付集成，经授权的账户所有者需通过设置 → 额度与充值（Settings → Credits）使用已配置的 Stripe 结账流程发起一笔充值。在工作空间功能受阻期间，账户充值入口仍然可用。只有经过签名校验且成功结算已保存订单的匹配回调通知，才能建立回调通知验证证据。仅访问同步返回页面、轮询订单状态，或使用旧配置完成的付款，均不能验证当前配置。真实结账可能会产生实际扣款；在验证测试实例时，请使用部署环境的 Stripe 测试配置。更改凭证、回调签名密钥、结账设置或币种后，必须针对更改后的新配置重新完成验证。

拥有显式资金入账、未冲正的非现金赠金或已批准授信额度的公司，可以在不配置商户网关的情况下使用私有化自托管路径。但这并不会认证 Stripe，也不会豁免请求级别余额检查。上述账户检查规则适用于 Stripe；EPay 与 ZhifuX 则使用下文所述的集成验证证据。

EPay 与 ZhifuX 集成验证证据

禁用 EPay 会停止创建新的结账单，同时保持既有订单的签名回调通知正常可用。当存在未决订单时，系统允许执行单纯的启用/禁用切换，但会阻止修改凭证或结账字段，以保护既有订单原始的验签配置。

EPay 要求针对使用当前配置创建的结账单收到经验证的签名支付回调通知并完成持久化入账结算。首次结账会在保存支付链接的同时，以原子方式捕获当时的配置快照。原始配置未知的历史遗留订单仍可正常入账结算，但不能用于验证新配置的就绪状态。

原生 ZhifuX 要求针对同一笔绑定配置的订单，同时具备经验证的签名回调通知以及独立的服务端查单确认结算（两者到达顺序不限）。现有的查单权限与速率限制依然适用，系统不会引入额外的周期性商户健康轮询。仅收到回调通知绝不会直接为账户入账，仅靠查单对账也不能证明回调通知投递正常。

这些适配器展示的是集成验证证据，而非 Stripe 式的实时账户收款资格。更改商户凭证、端点地址、异步通知/同步返回地址或支付方式，会使先前的配置验证证据失效。单次集成验证成功并不保证后续每一笔支付都会成功。未决支付保留其独立的恢复工作流。

授信额度与管理员赠金

已批准的授信额度允许客户余额在扣除未决预留后变为负数，直至达到其配置的授信上限。零授信额度即代表预付费访问模式。修改授信额度不会生成收款记录，也不会增加账户余额。现有的授信策略端点需要安装实例写入权限以及匹配的修订版本。

平台管理员可以使用 grantCustomerBalance 或 NiuAdminClient.grantCustomerBalance 发放非现金赠金（noncash gift）。调用时需提供精确的正数纳单位（nanounit）金额、原因以及 UUID 幂等键。在对不确定结果进行重试时，请保留该幂等键。完全相同的重试会返回原始赠金记录；若更改金额、币种或原因则会产生冲突。客户所有者/管理员角色无法自行给自己发放赠金。请使用管理后台 → 账户余额 → 发放非现金余额（Admin → Account balances → Grant noncash balance）来准备并显式发放已保存的赠金。

对于误发且完全未使用的赠金，请打开非现金发放 → 已发放赠金 → 冲正未使用赠金（Noncash grants → Issued gifts → Correct unused gift），核对其原始金额与原因，并输入冲正原因，然后确认移除未使用赠金（Remove unused gift）。仅限平台调用的冲正 API 与 SDK 方法 correctUnusedCustomerBalanceGrant 会追加一条独立的受审计调整记录。冲正金额必须与原始全额完全一致，不支持部分冲正。凡存在付费请求历史、已发生消耗、退款、未决请求预留或资金来源未知的账户，均会被拒绝冲正。已批准的授信额度及所有历史发放记录保持不变。冲正操作既不是商户外部退款，也不是消耗或收入调整。

如果收到不确定的响应，请使用检查已保存状态（Check saved status）或 getIssuedCustomerBalanceGrant。单次快照中未出现冲正记录，并不能证明仍在处理中的请求已经失败。重试时请仅使用完全相同的原始输入和幂等键，切勿新建赠金或调整记录。同一笔原始赠金最多只能执行一次全额冲正。已发放赠金历史包含早期通过 API 直接发放的记录，而已保存意图（Saved intents）则保留了准备阶段与发放恢复状态。

发放赠金既不是现金收款，也不构成收入。赠金是供后续消耗使用的独立资金来源；它不会追溯免除既有债务，也不会更改请求已锁定的销售价格。资金来源分配会分别记录赠金部分与非赠金部分，客户退款也会按原比例恢复这两部分额度。请勿将赠金当作已核实的支付收款或外部现金退款使用。

收入与收款

可通过 NiuAdminClient.getCustomerFinancialSummary({ currency: 'USD', days: 30 }) 读取仅限平台访问的财务摘要。该接口报告按 UTC 划分的记账区间（posting interval），独立于模型供应商对比报表所使用的分发区间（dispatch interval）。可选择 7、30 或 90 天。

以下是规定的会计核算示例，而非宣称已完成的实际支付：

指标	金额
名义消耗（Nominal consumption）	100
已消耗赠金 / 销售折让（Consumed gift / sales allowance）	5
确认收入（Recognized revenue）	95
实收现金（Cash received）	95

请勿将收入记为 100 同时将冲抵费用记为 5。单独发放赠金不会产生收入或促销费用。预付费收款发生在消耗之前；而基于授信额度的消耗可以发生在付款之前。后续偿还授信欠款时，不会再次重复确认同一笔收入。客户退款会减少原始的非赠金收入，并恢复原始的赠金部分；因此退款期间的确认收入可能为负数。

如果历史资金来源分配缺失或未知，完整的收入总额和赠金折让总额将保持不可用状态。明确标出的已知小计仅为部分汇总，不能替代完整总额。已核实的现金收款与消耗相互独立；若旧版账单付款与余额充值引用存在重叠，在完成对账前合并收款总额将保持不可用。已记录的资金冲回并不构成外部退款转账已完成的证据。

该财务摘要属于运营对账读取接口。完整的赠金消耗/退款工作流、关账期间会计核算以及完整的财务看板仍需另行验收；成功保存赠金或成功读取摘要并不代表这些能力已全部就绪。