| 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
完成以下步驟即可完成串接:
Step 1: 確認專案環境
詢問用戶:
-
整合方式:你要如何串接?
- React SDK(前端
usePayment Hook)
- Direct API(後端 REST API)
- 兩者都要
-
專案框架:你使用什麼框架?
- 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
核心功能:
createPaymentIntent(fiatAmount, fiatCurrency, options) - 建立 Payment Intent
getPaymentIntent(paymentIntentId) - 查詢單筆支付
listPaymentIntents(filters) - 列出支付意圖
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,
};
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: 測試驗證
引導用戶進行測試:
- 在 KryptoGO Studio 建立測試用 Client ID
- 建立一個小額 Payment Intent(fiat_amount: "0.01")
- 驗證 Payment Intent 回傳正確
- 確認 Webhook 回調可正常接收
- 確認支付狀態更新正確
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 | 金額不足,已退款 |
詳細參考文件