Agent skill

kryptogo-pay-checkout

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 穩定幣收款頁面.

Stars 236
Forks 18

Install this agent skill to your Project

npx add-skill https://github.com/paid-tw/skills/tree/main/plugins/kryptogo-pay/skills/kryptogo-pay-checkout

SKILL.md

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 整合

安裝依賴:

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

建立 Provider 設定:

tsx
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):

tsx
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 端點範例

javascript
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 端點接收支付狀態更新:

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

Expand your agent's capabilities with these related and highly-rated skills.

paid-tw/skills

kryptogo-pay-webhook

Implements KryptoGO Payment webhook/callback handling for receiving payment status notifications. Use when building webhook endpoints, handling payment callbacks, or implementing 支付狀態通知 for KryptoGO Payment.

236 18
Explore
paid-tw/skills

kryptogo-pay

Provides KryptoGO Payment integration overview and guides users to the appropriate skill. Use when starting KryptoGO crypto payment integration, setting up environment, or needing general guidance about KryptoGO 穩定幣支付.

236 18
Explore
paid-tw/skills

kryptogo-pay-query

Implements KryptoGO Payment query functionality for checking payment intent status and listing payment intents. Use when building order status checking, transaction verification, or payment confirmation features for KryptoGO 穩定幣支付.

236 18
Explore
paid-tw/skills

kryptogo-pay-transfer

Implements KryptoGO Payment token transfer/withdrawal functionality using the Asset Pro Transfer API. Use when building withdrawal features, sending tokens to users, or implementing 穩定幣提領轉帳 for KryptoGO Payment.

236 18
Explore
paid-tw/skills

payuni-webhook

Implements PAYUNi webhook handling including signature verification, replay attack prevention, and payment status updates. Use when building payment notification endpoints for 統一金流.

236 18
Explore
paid-tw/skills

payuni-checkout

Implements PAYUNi UPP checkout integration including AES256 encryption, form submission, and payment callback handling. Use when integrating payment gateway, creating checkout flows, or building 統一金流 payment pages.

236 18
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results