Back to Details

integrate-1bill

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Integrate 1BILL

集成1BILL

Build reliable 1LINK 1BILL integrations without confusing 1BILL with 1GO/Raast P2M, 1IBFT, a card gateway, or an unrelated product named OneBill.
构建可靠的1LINK 1BILL集成，注意不要将1BILL与1GO/Raast P2M、1IBFT、卡支付网关或其他名为OneBill的无关产品混淆。

First: inspect and classify

第一步：检查与分类

Always inspect the repository before planning or writing code. Search for 1LINK or 1BILL SDKs, clients, URLs, credentials, biller prefixes, PSID or consumer-number generation, inquiry/payment/void/status handlers, schemas, database records, message signatures, settlement files, reconciliation jobs, tests, and certification artifacts.
  • If an integration exists, identify its exact 1LINK product, API/catalogue version, organization role, environment, endpoints, authentication/signing scheme, and implemented flows. Repair the current design with minimal disruption.
  • If no integration exists, design it using the project's language, framework, data model, security, logging, job, and testing conventions.
  • Never invent request fields, response codes, signatures, encryption, URLs, credentials, prefix rules, PSID length, or timeout behavior. Obtain them from the merchant's current 1LINK sandbox/certification documentation.
Determine the integration role before choosing a flow:
  1. 1LINK member bank or non-bank initiator consuming 1BILL APIs;
  2. billing entity exposing or connecting billing data for collection;
  3. government or institutional collection through an approved partner;
  4. merchant actually seeking 1GO/Raast P2M or card checkout rather than 1BILL.
在规划或编写代码前，务必先检查代码仓库。搜索1LINK或1BILL的SDK、客户端、URL、凭证、账单服务商前缀、PSID或消费者编号生成逻辑、查询/支付/撤销/状态处理程序、数据模型、数据库记录、消息签名、结算文件、对账任务、测试用例以及认证相关文件。
  • 若集成已存在，明确其对应的具体1LINK产品、API/目录版本、组织角色、环境、端点、认证/签名方案以及已实现的流程。以最小改动为原则修复现有设计。
  • 若集成不存在，则遵循项目的语言、框架、数据模型、安全、日志、任务及测试规范进行设计。
  • 切勿自行定义请求字段、响应码、签名、加密方式、URL、凭证、前缀规则、PSID长度或超时行为。这些信息需从商户当前的1LINK沙箱/认证文档中获取。
在选择流程前，先确定集成角色：
  1. 1LINK成员银行或非银行发起方，调用1BILL API；
  2. 账单机构，暴露或对接账单数据以完成收款；
  3. 通过认证合作伙伴进行收款的政府或机构；
  4. 实际需要1GO/Raast P2M或卡支付结账而非1BILL的商户。

Confirm the product

确认产品

1BILL is a unified bill-payment rail. It supports fixed invoice/voucher payments, variable/top-up payments, credit-card bill payments, and package/bundle flows. Customers normally enter a biller-prefixed consumer, bill, or PSID reference in a participating bank, wallet, ATM, or over-the-counter channel; the channel fetches bill details and submits payment.
Do not present 1BILL as an embedded card form, subscription engine, wallet push API, or instant Stripe replacement. If the requirement is QR, alias, IBAN, or Request to Pay merchant acceptance, evaluate 1GO/Raast P2M instead. If it is card checkout, evaluate an approved payment gateway.
1BILL是一个统一的账单支付通道，支持固定发票/凭证支付、可变金额/充值支付、信用卡账单支付以及套餐/捆绑服务流程。客户通常会在合作银行、钱包、ATM或线下柜台渠道输入带有账单服务商前缀的消费者编号、账单编号或PSID参考码，渠道会获取账单详情并提交支付请求。
请勿将1BILL宣传为嵌入式卡表单、订阅引擎、钱包推送API或Stripe的即时替代方案。若需求是二维码、别名、IBAN或请求支付的商户收款，应评估1GO/Raast P2M；若为卡支付结账，则评估已认证的支付网关。

Workflow

工作流程

  1. Obtain the latest 1LINK developer-portal product selection, private API specification/OpenAPI file, onboarding pack, credentials, rate limits, test data, certification cases, and production cutover instructions.
  2. Record the exact catalogue/API version and compare it with any existing implementation before changing code.
  3. Define bill category, biller prefix/reference rules, amount rules, expiry, duplicate-payment policy, payer-visible fields, and internal invoice lifecycle.
  4. Model inquiry, payment, void/reversal where contracted, payment-status inquiry, reconciliation, and exception handling as separate idempotent operations.
  5. Keep the server authoritative for bill references, amounts, expiry, paid status, and settlement. Never trust a client screenshot or client-reported result.
  6. Store correlation identifiers needed to trace the application record, 1LINK request, channel transaction, status inquiry, settlement, and support case.
  7. Protect credentials and message integrity exactly as specified in the current certification pack. Reject invalid, replayed, unauthorized, or malformed requests safely.
  8. Test duplicate, delayed, missing, reversed, timed-out, and ambiguous transactions—not only successful payment.
  9. Complete 1LINK sandbox testing and formal certification before production. Change only approved environment configuration during cutover.
  1. 获取最新的1LINK开发者门户产品选型、私有API规范/OpenAPI文件、入职包、凭证、速率限制、测试数据、认证用例以及生产环境切换说明。
  2. 记录确切的目录/API版本，并在修改代码前与现有实现进行对比。
  3. 定义账单类别、账单服务商前缀/参考规则、金额规则、有效期、重复支付策略、付款人可见字段以及内部发票生命周期。
  4. 将查询、支付、合同约定范围内的撤销/退款、支付状态查询、对账以及异常处理建模为独立的幂等操作。
  5. 由服务器统一管理账单参考码、金额、有效期、已支付状态及结算信息。切勿信任客户端截图或客户端上报的结果。
  6. 存储用于追踪应用记录、1LINK请求、渠道交易、状态查询、结算以及支持工单所需的关联标识符。
  7. 严格按照当前认证包中的要求保护凭证和消息完整性。安全拒绝无效、重放、未授权或格式错误的请求。
  8. 测试重复、延迟、缺失、撤销、超时以及模糊的交易场景，而不仅仅是成功支付的情况。
  9. 在上线生产环境前，完成1LINK沙箱测试和正式认证。切换环境时仅修改已获批的配置。

Reliability rules

可靠性规则

  • Treat timeouts and transport failures as unknown outcomes until status inquiry or reconciliation proves the result; never retry payment blindly.
  • Make bill inquiry read-only and payment posting idempotent under the contracted unique transaction identifiers.
  • Enforce unique constraints for external transaction IDs and internal bill/payment references.
  • Use transactional state changes and an append-only audit trail for financial events.
  • Do not mark a bill paid only from the user's return screen, screenshot, SMS, or frontend request.
  • Reconcile transaction records with 1LINK/settlement reports and surface mismatches to operators.
  • Keep human-readable support data such as channel, reference, amount, date/time, and trace/transaction identifiers without logging secrets or full sensitive payloads.
  • 超时和传输故障应视为未知结果，直到状态查询或对账确认最终结果；切勿盲目重试支付。
  • 确保账单查询为只读操作，支付提交在合同约定的唯一事务标识符下具备幂等性。
  • 对外部交易ID和内部账单/支付参考码实施唯一性约束。
  • 对金融事件使用事务性状态变更和追加式审计追踪。
  • 切勿仅根据用户返回界面、截图、短信或前端请求标记账单已支付。
  • 将交易记录与1LINK/结算报告进行对账，并将不一致情况反馈给操作人员。
  • 保留易于人工读取的支持数据，如渠道、参考码、金额、日期/时间以及追踪/交易标识符，但不得记录密钥或完整的敏感负载。

Reference routing

参考文档指引

  • Read references/product-and-api-surface.md to choose the correct 1LINK product and understand publicly confirmed 1BILL operations.
  • Read references/implementation-workflow.md for state modeling, inquiry/payment/status/void flows, PSID/reference UX, and certification.
  • Read references/security-and-reliability.md before implementing authentication, financial state, retries, logging, reconciliation, or production rollout.
  • Read references/research-notes.md for dated official sources, public-doc limitations, recent community reports, and what must be re-verified.
  • 阅读references/product-and-api-surface.md以选择正确的1LINK产品，并了解公开确认的1BILL操作。
  • 阅读references/implementation-workflow.md以了解状态建模、查询/支付/状态/撤销流程、PSID/参考码用户体验以及认证相关内容。
  • 在实现认证、金融状态、重试、日志、对账或生产环境部署前，阅读references/security-and-reliability.md。
  • 阅读references/research-notes.md以获取过时的官方来源、公开文档的局限性、近期社区报告以及需要重新验证的内容。

Verification and output

验证与输出

Run relevant formatting, linting, type checking, and tests. Report whether 1BILL was found or added from scratch, the role and product selected, versions and private specifications inspected, implemented operations, idempotency strategy, reconciliation plan, certification status, and remaining 1LINK or partner configuration. Clearly label assumptions and never describe sandbox success as production approval.
运行相关的格式化、代码检查、类型校验和测试。报告是否已存在1BILL集成或需从零开始新增，所选的角色和产品，已查阅的版本和私有规范，已实现的操作，幂等性策略，对账计划，认证状态以及剩余的1LINK或合作伙伴配置。明确标注假设条件，切勿将沙箱测试成功描述为生产环境获批。