# Kryptogo Pay Webhook

> >

- **Type:** Skill
- **Install:** `agentstack add skill-paid-tw-skills-kryptogo-pay-webhook`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [paid-tw](https://agentstack.voostack.com/s/paid-tw)
- **Installs:** 0
- **Category:** [Finance & Payments](https://agentstack.voostack.com/c/finance-and-payments)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [paid-tw](https://github.com/paid-tw)
- **Source:** https://github.com/paid-tw/skills/tree/main/plugins/kryptogo-pay/skills/kryptogo-pay-webhook

## Install

```sh
agentstack add skill-paid-tw-skills-kryptogo-pay-webhook
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# KryptoGO Payment Webhook 回調處理任務

你的任務是在用戶的專案中實作 KryptoGO Payment Webhook 回調處理。

## 串接 Checklist

- [ ] **端點建立** - 建立 POST endpoint 接收回調
- [ ] **狀態處理** - 處理所有 5 種支付狀態
- [ ] **冪等處理** - 實作冪等性避免重複處理
- [ ] **回應確認** - 回應 HTTP 200 確認收到
- [ ] **測試驗證** - 驗證端點可正常運作

---

## Step 1: 確認環境

詢問用戶：

1. **框架類型**：你使用什麼後端框架？
   - Node.js (Express / Fastify / NestJS)
   - Python (Django / Flask / FastAPI)
   - 其他

2. **資料庫**：使用什麼資料庫儲存訂單？
   - 需要知道如何更新訂單狀態

用戶輸入: `$ARGUMENTS`

## Step 2: 建立 Webhook 端點

建立 POST 端點接收 KryptoGO 的回調通知。

**端點路徑建議**: `/api/payment/callback` 或 `/webhook/kryptogo`

**必要行為**:
1. 接收 POST JSON body
2. 驗證 `payment_intent_id` 存在於資料庫
3. 根據 `status` 更新訂單狀態
4. 回應 HTTP 200

## Step 3: 處理所有支付狀態

必須處理以下 5 種狀態：

| 狀態 | 處理邏輯 |
|------|---------|
| `pending` | 通常不會收到此狀態的回調 |
| `success` | 更新訂單為已付款，記錄 `payment_tx_hash` |
| `expired` | 標記訂單為過期 |
| `insufficient_not_refunded` | 記錄異常，等待退款 |
| `insufficient_refunded` | 記錄退款資訊 `refund_tx_hash`、`refund_amount` |

## Step 4: 實作冪等性

確保同一個 `payment_intent_id` 的回調不會被重複處理：
- 檢查訂單是否已經更新為最終狀態
- 使用 `payment_intent_id` 作為冪等鍵

## Step 5: 測試

1. 建立一個 Payment Intent（帶 `callback_url`）
2. 完成支付後確認端點收到回調
3. 驗證訂單狀態正確更新
4. 驗證回應 HTTP 200

---

## Callback Payload 格式

```json
{
  "payment_intent_id": "0h39QkYfZps7AUD1xQsj3MDFVLIMaGoV",
  "client_id": "9c5a79fc1117310f976b53752659b61d",
  "fiat_amount": "300.0",
  "fiat_currency": "TWD",
  "payment_deadline": 1715462400,
  "status": "success",
  "payment_chain_id": "arb",
  "symbol": "USDT",
  "crypto_amount": "2.53",
  "payment_tx_hash": "0x1234567890abcdef...",
  "received_crypto_amount": "2.53",
  "aggregated_crypto_amount": "2.50",
  "order_data": {
    "order_id": "uid_12345",
    "item_id": "100"
  },
  "callback_url": "https://example.com/callback",
  "group_key": "buy_stone_with_usdt"
}
```

## 重要欄位

| 欄位 | 說明 |
|------|------|
| `payment_intent_id` | 用來比對你資料庫中的訂單 |
| `status` | 判斷該做什麼處理 |
| `payment_tx_hash` | 成功時的區塊鏈交易 Hash |
| `received_crypto_amount` | 實際收到的加密貨幣金額 |
| `aggregated_crypto_amount` | 扣除手續費後的金額 |
| `refund_tx_hash` | 退款時的區塊鏈交易 Hash |
| `refund_amount` | 退款金額 |
| `order_data` | 你建立 Payment Intent 時傳入的自訂資料 |

---

## 詳細參考文件

- [程式碼範例 (Node.js/Python)](references/code-examples.md)
- [Callback Payload 完整格式](references/callback-payload.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](https://github.com/paid-tw)
- **Source:** [paid-tw/skills](https://github.com/paid-tw/skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-paid-tw-skills-kryptogo-pay-webhook
- Seller: https://agentstack.voostack.com/s/paid-tw
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.