/kryptogo-pay-checkout

name: kryptogo-pay-checkout
description: >
  Implements KryptoGO Payment checkout integration including Payment Intent creation,
  React SDK usePayment hook, and Direct API integration. Use when integrating crypto
  payment, creating checkout flows, or building KryptoGO 穩定幣收款頁面.
argument-hint: "[整合方式: SDK/API] [框架: React/Express/Python]"
context: fork
agent: general-purpose
disable-model-invocation: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
user-invocable: true

KryptoGO Payment 收款串接任務

你的任務是在用戶的專案中實作 KryptoGO Payment 穩定幣收款功能。

串接 Checklist

完成以下步驟即可完成串接：

• [ ] **環境確認** - 確認整合方式（SDK / API）與框架類型
• [ ] **環境變數** - 設定 KRYPTOGO_CLIENT_ID、STUDIO_API_KEY、ORIGIN
• [ ] **支付模組** - 建立 Payment Intent 建立與管理功能
• [ ] **支付頁面** - 建立支付 UI 或 API 端點
• [ ] **回調處理** - 建立 Webhook 端點接收狀態更新
• [ ] **測試驗證** - 使用測試環境驗證完整流程

---

Step 1: 確認專案環境

詢問用戶：

1. **整合方式**：你要如何串接？

• React SDK（前端 `usePayment` Hook）
• Direct API（後端 REST API）
• 兩者都要

2. **專案框架**：你使用什麼框架？

• React / Next.js（SDK 整合）
• Node.js (Express / Fastify / NestJS)
• Python (Django / Flask / FastAPI)
• 其他

用戶輸入: `$ARGUMENTS`

Step 2: 檢查環境變數

搜尋專案中的 `.env` 或設定檔，確認是否已設定：

• `KRYPTOGO_CLIENT_ID`（或 `CLIENT_ID`）
• `KRYPTOGO_STUDIO_API_KEY`（或 `STUDIO_API_KEY`）
• `KRYPTOGO_ORIGIN`（或 `ORIGIN`）

若未設定，引導用戶前往 [KryptoGO Studio](https://studio.kryptogo.com) 取得金鑰。

Step 3: 建立支付模組

路徑 A: React SDK 整合

**安裝依賴:**

npm install @kryptogo/kryptogokit-sdk-react wagmi viem@2.x @tanstack/react-query

**建立 Provider 設定:**

import { WagmiProvider } from 'wagmi';
import { getDefaultConfig, KryptogoKitProvider } from '@kryptogo/kryptogokit-sdk-react';
import { QueryClientProvider, QueryClient } from '@tanstack/react-query';
import '@kryptogo/kryptogokit-sdk-react/styles.css';

const queryClient = new QueryClient();
const clientId = process.env.NEXT_PUBLIC_KRYPTOGO_CLIENT_ID;
const config = getDefaultConfig();

function App({ children }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <KryptogoKitProvider clientId={clientId}>
          {children}
        </KryptogoKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

**建立支付元件（使用 `usePayment` Hook）:**

import { usePayment } from '@kryptogo/payment';

function PaymentButton() {
  const {
    openPaymentModal,
    closePaymentModal,
    data,
    txHash,
    error,
    isLoading,
    isSuccess,
    isError
  } = usePayment();

  const handlePayment = () => {
    openPaymentModal({
      fiat_amount: '100',
      fiat_currency: 'TWD',
      callback_url: 'https://your-server.com/payment/callback',
      order_data: {
        orderId: '12345',
        productName: 'Product Name',
      },
      group_key: 'product_purchase',
    });
  };

  return (
    <div>
      <button onClick={handlePayment} disabled={isLoading}>
        {isLoading ? '處理中...' : '立即付款'}
      </button>
      {isSuccess && <p>付款成功！TxHash: {txHash}</p>}
      {isError && <p>付款失敗：{error?.message}</p>}
    </div>
  );
}

路徑 B: Direct API 整合

**建立位置建議:**

• Express: `services/kryptogo-payment.js`
• NestJS: `src/payment/payment.service.ts`
• Python: `services/kryptogo_payment.py`

**核心功能:** 1. `createPaymentIntent(fiatAmount, fiatCurrency, options)` - 建立 Payment Intent 2. `getPaymentIntent(paymentIntentId)` - 查詢單筆支付 3. `listPaymentIntents(filters)` - 列出支付意圖 4. `handleWebhook(payload)` - 處理 Webhook 回調

Step 4: 建立支付端點

Express API 端點範例

const express = require('express');
const axios = require('axios');
const router = express.Router();

const KG_BASE_URL = 'https://wallet.kryptogo.app';
const headers = {
  'Content-Type': 'application/json',
  'X-Client-ID': process.env.KRYPTOGO_CLIENT_ID,
  'Origin': process.env.KRYPTOGO_ORIGIN,
  'X-STUDIO-API-KEY': process.env.KRYPTOGO_STUDIO_API_KEY,
};

// 建立 Payment Intent
router.post('/payment/intent', async (req, res) => {
  const { fiat_amount, fiat_currency, callback_url, order_data, group_key } = req.body;

  const response = await axios.post(
    `${KG_BASE_URL}/v1/studio/api/payment/intent`,
    { fiat_amount, fiat_currency, callback_url, order_data, group_key },
    { headers }
  );

  res.json(response.data);
});

Step 5: 建立回調處理

建立 Webhook 端點接收支付狀態更新：

router.post('/payment/callback', (req, res) => {
  const payment = req.body;

  switch (payment.status) {
    case 'success':
      // 更新訂單為已付款
      break;
    case 'expired':
      // 標記訂單為過期
      break;
    case 'insufficient_not_refunded':
      // 金額不足，等待退款
      break;
    case 'insufficient_refunded':
      // 已退款處理
      break;
  }

  res.status(200).send();
});

Step 6: 測試驗證

引導用戶進行測試： 1. 在 KryptoGO Studio 建立測試用 Client ID 2. 建立一個小額 Payment Intent（fiat_amount: "0.01"） 3. 驗證 Payment Intent 回傳正確 4. 確認 Webhook 回調可正常接收 5. 確認支付狀態更新正確

---

API 參考

端點

| 方法 | 路徑 | 說明 | |------|------|------| | POST | `/v1/studio/api/payment/intent` | 建立 Payment Intent | | GET | `/v1/studio/api/payment/intent/{id}` | 查詢單筆 Payment Intent | | GET | `/v1/studio/api/payment/intents` | 列出 Payment Intents | | POST | `/v1/studio/api/asset_pro/transfer` | 代幣轉帳/提領 |

Required Headers

| Header | 說明 | |--------|------| | `X-Client-ID` | KryptoGO Client ID | | `X-STUDIO-API-KEY` | Studio API Key | | `Origin` | 你的網域 | | `Content-Type` | `application/json` |

建立 Payment Intent 參數

| 參數 | 類型 | 必填 | 說明 | |------|------|:----:|------| | fiat_amount | String | ✓ | 法幣金額（最低 0.01）| | fiat_currency | String | ✓ | `TWD` 或 `USD` | | callback_url | String | | Webhook 回調 URL | | order_data | Object | | 自訂訂單資料（最多 1000 字元）| | group_key | String | | 支付分類標籤 |

Payment Status 狀態

| 狀態 | 說明 | |------|------| | `pending` | 等待付款 | | `success` | 付款成功 | | `expired` | 付款逾時 | | `insufficient_not_refunded` | 金額不足，等待退款 | | `insufficient_refunded` | 金額不足，已退款 |

---

詳細參考文件

• [程式碼範例 (Node.js/Python)](references/code-examples.md)
• [Payment Intent 完整欄位](references/payment-intent