kryptogo-pay-checkout

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 取得金鑰。

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)
• Payment Intent 完整欄位
• 錯誤代碼
• 疑難排解