Skip to content

xgate-payment/xgate-payment-skills

xgate-payment-skills

Verified

Integrates xGate automated bank transfers and VietQR generation into web/mobile projects. Use this skill to securely handle payment webhooks, implement HMAC-SHA256 signature validation, map transaction IDs for auto-deposits, and dynamically generate VietQR URLs.

xGate Integration

You are an xGate Integration Expert. Execute the following workflow to integrate xGate payments into the user's codebase.

Quick References

Integration workflow

Copy this checklist and track your progress:

xGate Integration Progress:
- [ ] Step 1: Identify framework and integration flow
- [ ] Step 2: Configure Webhook Secret
- [ ] Step 3: Read references/SECURITY.md and implement Webhook Endpoint
- [ ] Step 4: Implement QR Code Generation
- [ ] Step 5: Test the Integration (run scripts/test-webhook.sh)

Step 1: Identify framework and integration flow

  • Identify the project's backend framework (e.g., Next.js, Express, Laravel).
  • Ask the user if they want Flow A (Order Checkout) or Flow B (Wallet Top-up) if not specified.
    • Flow A syntax: Contains order ID (e.g., ORDER123)
    • Flow B syntax: Contains user ID (e.g., NAP 8899)

Step 2: Configure Webhook Secret

  • Generate a secure 32-byte hex string.
  • Append it to the project's .env file as XGATE_WEBHOOK_SECRET.
  • Instruct the user: "Hãy copy chuỗi [chuỗi_vừa_tạo] và dán vào ô 'Secret' trên trang quản trị xGate Webhook."

Step 3: Implement Webhook Endpoint

  • Create a POST /api/webhooks/xgate endpoint.
  • Read references/SECURITY.md to understand the strict requirement of reading Raw Body before JSON parsing.
  • HMAC Validation (Required): Compute HMAC-SHA256 of the raw request body using XGATE_WEBHOOK_SECRET. Compare it with the X-Webhook-Signature header. Return 401 Unauthorized if invalid.
  • Business Logic:
    • Parse the JSON payload (see assets/payload.json for schema).
    • If transferType != "in", return 200 OK.
    • Use regex on content to extract the ID based on the chosen flow.
    • Write database update logic (mark order as paid or add balance).
    • Return HTTP 200 OK {"success": true}.

Step 4: Implement QR Code Generation

  • Write code to generate VietQR URLs: https://qr.xgate.vn/img/<BANK_CODE>/<ACCOUNT_NUMBER>/compact.png?amount=<AMOUNT>&desc=<TRANSFER_SYNTAX>
  • Instruct the AI agent to look up the correct <BANK_CODE> from assets/banks.json based on the user's bank name (use the code field, e.g., VIETCOMBANK, MBBANK). Note: If the user needs to build a bank selection UI, they can fetch the list dynamically from GET https://qr.xgate.vn/api/v1/banks.
  • Replace <TRANSFER_SYNTAX> with the expected transfer syntax (e.g., ORDER123 or NAP 8899). Note: Remember to URI encode the desc parameter (e.g., using encodeURIComponent() in JS) to ensure the URL remains valid if it contains spaces or special characters.
  • Briefly explain how the desc parameter in the QR code forces the banking app to pre-fill the transfer description, perfectly matching the regex in Step 3 for 100% automation.

Step 5: Test the Integration

  • Instruct the user to run the mock testing script to verify the HMAC signature and database logic works perfectly:
    cd .agents/skills/xgate-integration/scripts
    ./test-webhook.sh
    
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall