NineLogix 商户申请与接入手册

第一章 开始之前

先确认产品适合进入申请流程，并准备可核验的信息。

• NineLogix 面向数字产品商业化和支付接入准备；申请不等于自动获批或立即收款。
• 准备产品网站、产品说明、客户获得内容或服务的方式、定价、退款与支持安排。
• 高风险、受限或信息不足的产品可能需要补充审核、限制能力或无法接入。
• 商户旅程只有四段：提交申请、确认业务资料、配置和验证、准备上线。

第二章 提交接入申请

申请内容越具体，资料确认越高效。

• 填写法律主体、联系人、产品名称、网站和可联系邮箱。
• 用客户能理解的语言描述产品解决什么问题、交付什么以及由谁使用。
• 说明一次性、订阅、用量或混合收费方式；未开放能力不能作为上线承诺。
• 列明目标国家或地区、预计币种、价格区间和预计交易规模。
• 提交前检查网站可访问、政策页面与实际业务一致、联系方式有效。

第三章 确认业务资料

NineLogix 可能要求补充业务、交付和政策证据。

• 补充资料请求会说明缺少什么以及如何提交；请在原申请上下文中回复。
• 网站应清楚展示产品、价格或价格形成方式、交付方式、支持渠道和必要政策。
• 商品名称、描述、定价、退款条件和交付证据应彼此一致。
• 状态可能包括资料待补充、审核中、可进入配置或暂不适合；状态不是支付成功或生产批准。

第四章 获得商户后台

获批后通过受控邀请进入自己的 NineLogix 组织。

• 只使用邀请中的官方入口激活账户，并为账户启用强密码和安全的邮箱。
• Merchant ID 标识商户组织；Store ID 标识具体商店。创建订单时必须使用获批组合。
• 一个 Merchant 可以包含一个或多个 Store；订单、结账会话和凭证均受组织隔离。
• 测试与生产完全分离。测试状态、测试密钥或测试成功都不会自动开放生产。
• 团队成员只应拥有完成其工作所需的最小权限；人员离职时立即撤销访问。

第五章 选择接入方式

从最简单且满足业务需要的方式开始。

• 没有开发团队时优先 Payment Link。
• 网站需要稳定结账入口时优先 Hosted Checkout。
• 需要服务端创建订单、幂等和状态查询时使用 Payment API。
• 嵌入式 JS/SDK 不属于当前已交付能力。

第六章 支付链接

在商户后台创建 NineLogix 域名的测试付款链接。

• 填写商品名称、金额、USD 币种和有效期；确认信息后再创建。
• 链接可发送给受控测试人员，但不得把测试链接描述为生产付款。
• 后台可查看链接和会话状态，并停用不再使用的链接。
• 生产 Payment Link 需要商户、支付方式和真实收款能力独立批准。

第七章 Hosted Checkout

NineLogix 托管结账让客户始终先进入 NineLogix 页面。

• 商户服务端创建 Checkout Session，并把客户带到返回的 NineLogix checkout_url。
• 结账页只展示该商户获批且当前可用的支付方式。
• 成功、取消和 Return 页面只反映浏览器体验，不能直接改变最终支付状态。
• 最终状态必须来自已验签支付 Webhook，或明确启用的可信服务端状态来源。
• 会话有有效期；客户应在页面显示的期限内完成操作，过期后不要复用旧会话。

第八章 开发者准备

所有密钥只在服务端使用。

• 开发者工作区显示 Merchant ID、Store ID、获批 scope 和环境状态。
• 测试 API Key 明文仅显示一次，NineLogix 只保存哈希；立即存入团队的秘密管理工具。
• 不要把 API Key、Webhook secret 放进浏览器代码、移动应用、公开仓库、日志或聊天。
• 按最小 scope 使用凭证；怀疑泄露时立即撤销并轮换。
• 生产 API Key 只能在管理员批准生产 API 后创建；它仍不会自动开放真实收款。

第九章 Payment API 快速开始

使用服务端 Bearer 认证和稳定的幂等键。

• Base URL：https://www.ninelogix.com/api/v1
• 认证：Authorization: Bearer nlx_test_...
• 创建请求必须携带 Idempotency-Key；相同业务动作重试时复用同一键。
• POST /checkout-sessions 创建测试会话；GET /checkout-sessions/{session_id} 查询状态。
• 响应 checkout_url 始终是 NineLogix 地址，不应解析或替换为任何上游地址。
• 常见错误：401 凭证错误；403 scope、环境或批准不足；409 幂等冲突；422 参数错误；429 请求过多。

curl -X POST https://www.ninelogix.com/api/v1/checkout-sessions \
  -H "Authorization: Bearer nlx_test_REPLACE" \
  -H "Idempotency-Key: order-demo-001" \
  -H "Content-Type: application/json" \
  -d '{"store_id":"store_REPLACE","amount_minor":1000,"currency":"USD","product_name":"Demo product"}'

第十章 Webhook

Webhook 是服务端接收最终状态变化的方式。

• 在开发者工作区登记 HTTPS endpoint；私网、localhost 和不安全地址会被拒绝。
• 签名 secret 仅显示一次。使用原始请求体、时间戳和 HMAC-SHA256 验签，并做常量时间比较。
• 按 event_id 去重并拒绝过期时间戳；同一事件重复到达不应重复交付商品。
• 先发送签名测试事件，记录接收时间、event_id 和验签结果。
• 当前可用的是签名测试事件。自动生产投递、持久重试、死信和人工重发仍未开放；上线审批会明确可用边界。

第十一章 完成测试联调

用可重复的测试证据证明接入正确。

• 创建一笔金额和商品清楚的测试订单，并打开 Hosted Checkout。
• 确认桌面与移动端页面可用，成功、取消和过期体验清楚。
• 接收并验签测试 Webhook，重复发送同一 event_id 时保持幂等。
• 用同一 Idempotency-Key 重放创建请求，确认不会产生第二笔业务订单。
• 向 NineLogix 提交测试订单号、时间、环境、结果和必要截图，不提交任何密钥。

第十二章 申请生产上线

测试完成只是申请生产能力的前提。

• 管理员可批准或暂停生产 API；生产 API 批准不等于真实收款开放。
• 支付方式、币种、市场和一次性或订阅能力必须按具体商户单独批准。
• 生产密钥只在批准后创建并一次显示；上线前验证回调来源、scope 和密钥保管。
• 首笔真实交易必须按批准的受控方案执行，并在交易后观察 Webhook 和订单状态。
• Alipay+ 一次性付款已有受控生产证据；不据此承诺全部钱包、国家、币种或订阅。

第十三章 日常运营

订单、支付和客户支持需要持续对照。

• 使用 NineLogix Order、Checkout Session 和 Payment 状态处理客户问题。
• 失败或超时时先核对订单号、创建时间、会话状态和客户看到的提示；不要盲目重复创建。
• 退款与争议当前不是商户自助执行能力；按支持流程提交申请和交付证据。
• 手续费、对账与结算能力当前未开放为自动化商户功能，以单独运营确认结果为准。
• 联系支持时提供 NineLogix 标识、环境、时间和安全截图，不发送密钥或完整付款令牌。

第十四章 安全

把凭证、状态最终性和人员权限作为上线条件。

• API Key 与 Webhook secret 只能放在服务端秘密管理系统。
• 不要通过聊天、工单正文、截图或客户端错误信息发送 secret。
• 不要依赖浏览器 Return 判定付款成功；只信任已验签 Webhook 或获批服务端状态。
• 定期检查团队权限；人员离职、设备丢失或疑似泄露时立即撤销并轮换。
• 发现可疑交易、异常重放或身份冒用时暂停交付并联系 NineLogix。

第十五章 FAQ

常见问题的简短答案。

• 申请通过后能立即收款吗？不能。先完成测试，生产 API、支付方式和真实收款分别批准。
• 测试 Key 可以用于生产吗？不能。测试和生产凭证严格分离。
• Return 页面显示成功就能交付吗？不能，必须等待已验签 Webhook 或可信服务端最终状态。
• 可以使用订阅、退款或自动结算吗？当前不能将这些能力视为已开放。
• 可以承诺所有 Alipay+ 钱包和国家吗？不能，范围以具体商户获批能力为准。
• 如何获得帮助？提供 Merchant ID、Store ID、NineLogix 订单或会话标识、时间和环境，不提供 secret。