---
name: xgate-payment-skills
description: 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.
license: MIT
metadata:
  author: xGate
  version: "1.0.0"
  keywords: "vietqr, bank transfer, payment gateway, webhook, hmac-sha256, automation, vietnam banking"
---

# xGate Integration

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

## Quick References
- **Security Guide (HMAC)**: See [references/SECURITY.md](references/SECURITY.md) for detailed validation logic.
- **Payload Schema**: See [assets/payload.json](assets/payload.json) for the mock payload.
- **Supported Banks**: See [assets/banks.json](assets/banks.json) for the list of valid `<BANK_CODE>` values, or fetch dynamically via `GET https://qr.xgate.vn/api/v1/banks`.
- **Testing**: Run [scripts/test-webhook.sh](scripts/test-webhook.sh) to mock a webhook POST.

## 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](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](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](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:
  ```bash
  cd .agents/skills/xgate-integration/scripts
  ./test-webhook.sh
  ```