Kryptogo Pay Checkout

KryptoGO Payment 收款串接任務

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

串接 Checklist

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

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

---

Step 1: 確認專案環境

詢問用戶：

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

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

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

• 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 (
    
      
        
          {children}
        
      
    
  );
}

建立支付元件（使用 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 (
    
      
        {isLoading ? '處理中...' : '立即付款'}
      
      {isSuccess && 付款成功！TxHash: {txHash}}
      {isError && 付款失敗：{error?.message}}
    
  );
}

路徑 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 參數

| 參數 | 類型 | 必填 | 說明 | |------|------|:----:|------| | fiatamount | String | ✓ | 法幣金額（最低 0.01）| | fiatcurrency | String | ✓ | TWD 或 USD | | callbackurl | String | | Webhook 回調 URL | | orderdata | 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-fields.md)
• [錯誤代碼](references/error-codes.md)
• [疑難排解](references/troubleshooting.md)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: paid-tw
• Source: paid-tw/skills
• License: MIT

Install and usage instructions live in the source repository linked above.