Huifu Payment Integration

Integration Challenges

When integrating Huifu Payment, developers often encounter concrete issues such as selecting among multiple product lines, managing interface complexity, and adhering to security protocols. Huifu Payment offers aggregation payment, hosting payment, and checkout-js, each with distinct APIs, SDKs, and business rules. This leads to difficulties in decision-making for initial integration or extending existing systems—for example, distinguishing between aggregation payment (suitable for rapid transactions) and hosting payment (fit for split payments), or clarifying server-side versus front-end responsibilities. Additionally, interfaces involve numerous nested fields, requiring handling of sign signatures, verification, idempotency, and payment finality confirmation. Debug misconfigurations can risk exposing sensitive data like private keys. Multi-platform adaptation adds complexity, such as initialization order differences in Java, PHP, Python SDKs, or misunderstandings about checkout-js front-end callbacks not being final states.

How the Skill Works

This skill provides a structured approach to streamline Huifu Payment integration, with core capabilities and key steps as follows:

Execution Flow and Precise Routing

The skill follows a five-step process: identifying dimensions like product line, tech stack, and existing systems; checking hard checkpoints (e.g., stopping with 🔴 CHECKPOINT · HARD STOP if integration methods are ambiguous); selecting 3-5 documents from references/ based on scenarios (e.g., aggregation-order.md for order placement); outputting solution cards or regression checks; and finally applying rules like signatures and idempotency. Key designs include:
- Hard Checkpoints: Pausing generation when ambiguities or missing info arise, such as when users request runnable code without unique context, to ask only the highest-priority question.
- Field Management: Providing complete field catalogs that distinguish wire paths (e.g., raw JSON keys) from decoded paths (e.g., trade_no), avoiding placeholder descriptions; links are processed by purpose, with bad anchors like #业务返回码 mapped to the full public error code set.
- Security Boundaries: Private keys and system numbers must be read from server-side configurations, prohibited from frontend or logs; PHP SDK must fix DEBUG=false before loading any files to prevent official Demo logs from leaking MerConfig.

Core Capabilities and Adaptation

The skill covers end-to-end processes from quick integration to go-live checks:
- Aggregation Payment: Supports order placement, queries, refunds, etc., where a single notify_url handles both forward and reverse scan notifications, parsed by trade_type.
- Hosting Payment: Includes pre-orders, split payment queries, with checkout-js requiring confirmed notification verification and idempotency.
- SDK Adaptation: Selecting reference docs by language (e.g., Java uses aggregation-java-adapter.md), ensuring use of official SDK Requests (like dg-lightning-sdk 1.0.5), and prohibiting hand-written HTTP clients to bypass signatures.
- Local Sandbox: Only verifying protocol loops and state machines, not simulating real merchant permissions or production rates, with frozen contract files as immutable historical evidence.

Key Steps Example

Integration requires: 1) Checking SDK versions and request headers in projects; 2) Completing fields based on trade type (e.g., aggregation refund references aggregation-refund.md and payment-complete-field-catalog.md); 3) Confirming payment finality via notification verification (verify signature first, then check amounts) and query compensation, forbidding fabricated notifications; 4) Pre-go-live checks for TLS certificate chains and skill_source defaults (e.g., only this skill uses hfps/1.3.4).

Applicability and Boundaries

This skill focuses on payment transaction integration with clear limitations:
- Excludes Onboarding: Merchant onboarding, image material reviews, etc., must use the separate $huifu-merchant-onboarding skill, preventing misreading docs from this skill.
- Finality Confirmation: Synchronous approvals, jump_urls, browser redirects, or front-end callbacks are not final states; server-side notification verification and query APIs (e.g., aggregation-query-payment-query.md) are mandatory.
- Security Red Lines: Production merchant numbers, RSA keys, etc., reside only server-side; example code must not expose them; PHP integration must reject official Demo entries (like BsPayDemo/loader.php) to avoid DEBUG log leaks.
- Capability Gap Reporting: If official SDKs lack specific Requests (e.g., for certain endpoint forms), report the gap explicitly without hand-writing HTTP replacements.
- Sandbox Limitations: Local testing does not validate channel rates, risk controls, or production access, serving only as a logic verification aid.

Adherence to guidelines ensures compliance with checkpoints and security norms, building reliable payment systems.