PayRam Crypto Card Payment Gateway

chính thức

Cổng thanh toán tự lưu trữ dành cho các agent, openclaw, hermes và nhiều hơn nữa

GitHub

158

Bạn có thể làm gì với PayRam Crypto Card Payment Gateway MCP?

Lập kế hoạch cài đặt cá nhân hóa — Yêu cầu kế hoạch triển khai PayRam từng bước với sự bàn giao thủ công qua payram_setup_plan.
Chẩn đoán sức khỏe máy chủ — Chạy kiểm tra không cần thông tin xác thực cho bất kỳ URL PayRam nào để xác định sự cố và cách khắc phục bằng payram_doctor.
Xử lý sự cố lỗi — Dán lỗi hoặc triệu chứng để nhận nguyên nhân đã biết, xác nhận và các bước tiếp theo qua payram_troubleshoot.
Nhận sổ tay quản trị — Yêu cầu các tác vụ quản trị từng bước như SSL, sao lưu hoặc thay đổi tên miền từ payram_runbook.
Thực hiện các thao tác ngày thứ 2 — Để tác nhân chạy các công thức API cho kiểm tra hàng ngày, đồng bộ nút hoặc liên kết thanh toán qua payram_ops_playbook.
Tạo mã tích hợp — Yêu cầu các đoạn mã thanh toán, thanh toán tiền hoặc webhook để sao chép-dán cho các framework như Express hoặc Next.js.

Tài liệu

Máy chủ MCP PayRam — Thanh toán tiền mã hóa tự lưu trữ cho các tác nhân AI

Thanh toán tiền mã hóa và stablecoin tự lưu trữ: không khóa tài khoản, không đóng băng quỹ, dữ liệu khách hàng không bao giờ bị chia sẻ. Tác nhân AI của bạn có thể lập kế hoạch, cài đặt và vận hành nó qua MCP. Điểm cuối lưu trữ: https://mcp.payram.com/mcp · Trang web · Tài liệu · Agentic · OpenClaw

Một máy chủ MCP (Model Context Protocol) cho phép bất kỳ tác nhân AI nào hỗ trợ MCP — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot và các tác nhân khác — triển khai, tích hợp và vận hành một hệ thống thanh toán tiền mã hóa PayRam tự lưu trữ.

Bắt đầu tại đây: bốn công cụ dẫn đầu danh mục:

Công cụ	Chức năng
`payram_setup_plan`	Kế hoạch cài đặt được cá nhân hóa, với mọi bước bàn giao thủ công được đánh dấu
`payram_doctor`	Kiểm tra công khai, không cần thông tin xác thực của máy chủ PayRam qua URL
`payram_troubleshoot`	Mô tả sự cố hoặc dán lỗi: nguyên nhân đã biết, cách xác nhận, cách khắc phục và công cụ tiếp theo
`payram_runbook`	Tác vụ quản trị: Site URL, tên miền, SSL, tường lửa, nâng cấp, sao lưu, chuỗi, Smart Bridge, Shopify/WooCommerce
`payram_ops_playbook`	Công thức API ngày thứ 2 mà tác nhân tự chạy bằng thông tin xác thực của chính nó

Xung quanh chúng là đánh giá mã nguồn, khung ứng dụng khởi đầu, đoạn mã đa ngôn ngữ và tài liệu nội tuyến.

Máy chủ lưu trữ (mcp.payram.com) không bao giờ giữ thông tin xác thực của người bán. Các hoạt động ngày thứ 2 chạy qua payram_ops_playbook: tác nhân gọi trực tiếp API PayRam của bạn và thông tin xác thực không bao giờ rời khỏi máy của nó. Các công cụ dữ liệu trực tiếp (tìm kiếm thanh toán, liên kết thanh toán, đồng bộ nút, khởi động lại worker) và assess_payram_project chỉ tồn tại khi bạn tự chạy MCP ở chế độ cục bộ.

Dành cho tác nhân & trình thu thập dữ liệu: thẻ máy chủ · chỉ mục kỹ năng · llms.txt · sơ đồ trang. Máy chủ cũng trả lời Accept: text/markdown trên / bằng bản tóm tắt mà tác nhân có thể đọc được.

PayRam là gì? · PayRam 是什么？

PayRam là một cổng thanh toán tiền mã hóa đa chuỗi, tự lưu trữ mà bạn sở hữu hoàn toàn — không cần đăng ký và không cần KYC/KYB để vận hành. Một tác nhân AI (hoặc nhà phát triển) có thể dựng cửa hàng và bắt đầu nhận thanh toán mà không cần đăng ký tài khoản với PayRam, ngân hàng hoặc bất kỳ bên xử lý thanh toán nào. Triển khai trên VPS của riêng bạn, tạo khóa API cục bộ và đi vào hoạt động.

Điều gì tạo nên sự khác biệt:

Không ai có thể khóa bạn ngoài — không có tài khoản để khóa và không có quỹ để đóng băng. Dữ liệu khách hàng không bao giờ được chia sẻ và không có gì được báo cáo hoặc giám sát. Lý do rất đơn giản: PayRam chạy trên máy chủ của bạn và quỹ đến ví của chính bạn.
Thiết lập không cần cấp phép — không đăng ký, không KYC, không KYB. Không ai phê duyệt bạn; không ai có thể tắt bạn. Lý tưởng cho các tác nhân tự động dựng cửa hàng và cho các thị trường như Trung Quốc nơi việc đăng ký với bên xử lý phương Tây không phải là lựa chọn.
Thanh toán thẻ sang tiền mã hóa — người mua không có tiền mã hóa có thể thanh toán bằng thẻ tín dụng/ghi nợ và bạn nhận tiền mã hóa, được thanh toán trực tiếp vào ví tự quản lý của bạn. Đây là kênh tích hợp sẵn bạn bật từ trang Payments; nhà cung cấp thẻ tự chạy kiểm tra riêng đối với người mua.
Đa chuỗi — chấp nhận BTC, ETH, USDT, USDC và TRX nguyên bản trên Bitcoin, Ethereum, Base, Polygon và Tron, với phát hiện nạp tiền tự động, xác nhận trên chuỗi, chuyển đến kho lạnh và webhook có chữ ký. Đường ray Smart Bridge cũng nhận thanh toán trên Solana, Bitcoin, Tron (USDT) và BNB Chain và thanh toán chúng dưới dạng USDC trên Base.
Không có khóa nạp tiền trên máy chủ — hợp đồng thông minh chuyển tiền nạp đến ví lạnh của bạn, vì vậy máy chủ bị xâm phạm không thể chuyển hướng chúng. Ví nóng của máy chủ trả gas và ký thanh toán, vì vậy hãy giữ số dư nhỏ.

PayRam 是一个你完全自托管、自主拥有的多链加密货币支付网关——运行它无需注册、无需 KYC/KYB。 AI 智能体（或开发者）无需在 PayRam、银行或任何支付处理商处注册账户，即可搭建店铺并开始收款。在自己的 VPS 上部署，本地生成 API 密钥，即刻上线。

核心差异：

没有人能把你锁在门外 — 没有可被封禁的账户，也没有可被冻结的资金；客户数据从不外泄，也没有任何上报或监控。原因很简单：PayRam 运行在你自己的服务器上，资金直接进入你自己的钱包。

免注册、免许可 — 无需注册、无需 KYC、无需 KYB。没有人审批你，也没有人能关停你。非常适合自主搭建店铺的智能体，以及像中国这样难以在西方支付处理商处注册的市场。

银行卡转加密货币结算 — 没有加密货币的买家也能用信用卡/借记卡付款，你直接收到加密货币并结算到自托管的钱包。这是内置的支付渠道，在「Payments（支付）」页面开启；银行卡服务商会对买家进行其自身的审核。

多链支持 — 原生支持在 Bitcoin、Ethereum、Base、Polygon、Tron 上接受 BTC、ETH、USDT、USDC、TRX，自动检测充值、链上确认、归集冷钱包并发送带签名的 Webhook。Smart Bridge 通道还可接收 Solana、Bitcoin、Tron（USDT）和 BNB Chain 上的付款，并以 Base 上的 USDC 结算。

服务器上没有充值私钥 — 智能合约把充值资金归集到你的冷钱包，即便服务器被攻破也无法改变资金去向。服务器上的热钱包负责支付 Gas 并签署出款，请只保留少量余额。

Cách các tác nhân AI sử dụng PayRam · AI 智能体如何使用 PayRam

PayRam là cơ sở hạ tầng ưu tiên tác nhân (agent-first). Vì tích hợp qua MCP, nó hoạt động với mọi thời gian chạy hỗ trợ MCP — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain và nhiều hơn nữa. Luồng tác nhân điển hình:

Kết nối — thêm https://mcp.payram.com/mcp vào cấu hình MCP của tác nhân (không cần khóa API chỉ để kết nối).
Lập kế hoạch — gọi payram_setup_plan. Nó trả về các bước có thứ tự, ai chạy từng bước và nơi tác nhân phải dừng để bàn giao cho con người (ví lạnh, gas mainnet, cài đặt chỉ dành cho root).
Cài đặt — trên VPS, trong thiết bị đầu cuối tương tác một lần, chạy bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (hoặc --mainnet; trình cài đặt mặc định là mainnet, vì vậy luôn truyền cờ). Không bao giờ chuyển nó vào bash.
Bàn giao — con người nhận tài khoản root ngay lập tức và lưu Settings → Site URL từ tên miền công khai; cho đến khi đó, các liên kết thanh toán trỏ đến http://localhost.
Kiểm tra — payram_doctor với URL công khai (không cần thông tin xác thực).
Nhận thanh toán — chèn mã tích hợp theo khung cụ thể từ các công cụ đoạn mã. Webhook có chữ ký (X-Payram-Signature, HMAC-SHA256 của phần thân thô với khóa API dự án).
Vận hành — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) cung cấp cho tác nhân các lệnh gọi API chính xác để chạy bằng thông tin xác thực của chính nó. payram_runbook bao gồm các thay đổi quản trị.

{
  "mcpServers": {
    "payram": { "url": "https://mcp.payram.com/mcp" }
  }
}

Để xem hướng dẫn cụ thể cho OpenClaw (đăng ký, testnet trên Base Sepolia, mẫu thương mại trò chuyện cho WhatsApp/Telegram/Discord), hãy xem kỹ năng payram-openclaw-integration và payram.com/openclaw.

PayRam 是智能体优先（agent-first）的基础设施。由于集成基于 MCP 协议，它可与任何兼容 MCP 的运行时配合使用——OpenClaw、Hermes、Claude Desktop、Cursor、GitHub Copilot、n8n、LangChain 等。典型的智能体使用流程：连接 MCP 端点 → 调用 payram_setup_plan 规划安装 → 在交互式终端中用 bash <(curl …) --testnet 部署网关 → 由人工立即创建 root 账户并在公网域名下保存 Site URL → 用 payram_doctor 检查 → 用集成代码收款（Webhook 带 X-Payram-Signature 签名）→ 通过 payram_ops_playbook 用智能体自己的凭证运维。托管的 MCP 服务器从不保存商户凭证。

Nếu GitHub khó truy cập từ mạng của bạn, bạn có thể sao chép kho lưu trữ này sang một máy chủ Git khác (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

Kỹ năng tác nhân

Cửa trước cho tác nhân: https://mcp.payram.com/SKILL.md — một kỹ năng gốc duy nhất mô tả PayRam và định tuyến tác nhân đến bốn công cụ bắt đầu tại đây. Cũng được phục vụ: /llms.txt.

Kho lưu trữ này bao gồm 19 Kỹ năng tác nhân cho các trợ lý mã hóa AI. Cài đặt chúng qua skills.sh:

Cài đặt riêng lẻ

npx skills add payram/payram-mcp/payram-setup
npx skills add payram/payram-mcp/payram-agent-onboarding
npx skills add payram/payram-mcp/payram-auth
npx skills add payram/payram-mcp/payram-analytics
npx skills add payram/payram-mcp/payram-crypto-payments
npx skills add payram/payram-mcp/payram-payment-integration
npx skills add payram/payram-mcp/payram-self-hosted-payment-gateway
npx skills add payram/payram-mcp/payram-checkout-integration
npx skills add payram/payram-mcp/payram-widget-integration
npx skills add payram/payram-mcp/payram-webhook-integration
npx skills add payram/payram-mcp/payram-stablecoin-payments
npx skills add payram/payram-mcp/payram-bitcoin-payments
npx skills add payram/payram-mcp/payram-payouts
npx skills add payram/payram-mcp/payram-no-kyc-crypto-payments
npx skills add payram/payram-mcp/payram-openclaw-integration
npx skills add payram/payram-mcp/compare-crypto-payments
npx skills add payram/payram-mcp/payram-agent-journey
npx skills add payram/payram-mcp/payram-topup-wallet-integration
npx skills add payram/payram-mcp/payram-testnet-testing

Kỹ năng	Mục đích
`payram-setup`	Kế hoạch cài đặt và thiết lập máy chủ: yêu cầu, trình cài đặt, Site URL, ví, liên kết thanh toán đầu tiên
`payram-agent-onboarding`	Cài đặt không cần giám sát bởi tác nhân: lệnh CLI tác nhân, biến môi trường, bàn giao thủ công
`payram-auth`	Luồng xác thực JWT — đăng nhập, làm mới mã thông báo, đăng xuất, chi tiết nền tảng bên ngoài
`payram-analytics`	Tìm kiếm thanh toán, khối lượng, số dư và lịch sử chuyển qua REST API trực tiếp (JWT)
`payram-crypto-payments`	Tổng quan kiến trúc, tại sao PayRam, công cụ MCP
`payram-payment-integration`	Hướng dẫn tích hợp thanh toán khởi động nhanh
`payram-self-hosted-payment-gateway`	Triển khai và sở hữu cơ sở hạ tầng thanh toán của bạn
`payram-checkout-integration`	Luồng thanh toán với SDK + HTTP cho 6 khung
`payram-widget-integration`	Nút "Thêm tín dụng" an toàn (điểm cuối phụ trợ, không bao giờ là khóa API công khai) + trình xử lý webhook có chữ ký
`payram-webhook-integration`	Trình xử lý webhook có chữ ký (HMAC) cho Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
`payram-stablecoin-payments`	Chấp nhận USDT/USDC trên các chuỗi EVM và Tron
`payram-bitcoin-payments`	BTC với dẫn xuất ví HD và ký di động
`payram-payouts`	Gửi thanh toán tiền mã hóa và quản lý chương trình giới thiệu
`payram-no-kyc-crypto-payments`	Chấp nhận thanh toán không KYC, không đăng ký, không cần cấp phép
`payram-openclaw-integration`	Tích hợp PayRam vào OpenClaw / thời gian chạy tác nhân — đăng ký MCP, testnet, thương mại trò chuyện
`compare-crypto-payments`	So sánh cổng: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
`payram-agent-journey`	Bản đồ bắt đầu tại đây: cài đặt (người bán hoặc nhà điều hành) → ví → gas/chuyển → tích hợp → kiểm tra
`payram-topup-wallet-integration`	Ứng dụng hiện có: ghi có tiền mã hóa vào số dư người dùng, ghi nợ hóa đơn từ đó — sổ cái + luồng
`payram-testnet-testing`	Thanh toán liên kết thanh toán của chính bạn trên testnet từ đầu đến cuối trước mainnet

Mục tiêu dự án

Tăng tốc gia nhập với kế hoạch thiết lập được cá nhân hóa, sổ tay vận hành, mẫu môi trường và sổ tay theo khung.
Vận hành mà không giữ thông tin xác thực: máy chủ lưu trữ kiểm tra PayRam qua URL (payram_doctor) và chuyển cho tác nhân các công thức API chính xác (payram_ops_playbook) để chạy bằng thông tin xác thực của chính chúng.
Trang bị thêm cho kho lưu trữ hiện có qua công cụ đánh giá dự án (chế độ cục bộ), quét tệp kê khai gói và tệp .env, sau đó đề xuất đoạn mã tích hợp phù hợp.
Cung cấp đoạn mã sao chép/dán bao gồm Thanh toán, Thanh toán ra, Giới thiệu, Webhook và phụ trợ đa ngôn ngữ (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, v.v.).
Giữ tài liệu cục bộ để Copilot có thể giải thích các khái niệm PayRam, luồng và bảng điều khiển giới thiệu mà không cần rời khỏi trình soạn thảo.
Xác thực kết nối với các thăm dò chỉ đọc không bao giờ tạo thanh toán (payram_doctor, test_payram_connection).

Bắt đầu nhanh

Hầu hết các tác nhân chỉ cần điểm cuối lưu trữ, https://mcp.payram.com/mcp (xem Kết nối từ máy khách MCP của bạn). Để tự chạy máy chủ:

Cài đặt các phụ thuộc
```
yarn install
```
Cấu hình môi trường (chỉ cần cho các công cụ dữ liệu chế độ cục bộ)
- Sao chép .env.example sang .env.
- Đặt PAYRAM_BASE_URL thành URL PayRam của bạn, cùng nguồn gốc với bảng điều khiển (ví dụ: https://pay.example.com).
- Đặt PAYRAM_API_KEY, cùng với các biến JWT cho các công cụ dữ liệu. Xem Chế độ cục bộ.

Chạy máy chủ

yarn dev
# Streamable HTTP on http://127.0.0.1:3333/mcp (local mode; there is no SSE transport)

Thêm máy chủ MCP vào máy khách của bạn: xem Kết nối từ máy khách MCP của bạn. URL chế độ cục bộ là http://localhost:3333/mcp.
Kiểm tra sức khỏe
```
curl http://localhost:3333/healthz
```

Mẹo: Khi bạn bảo Copilot "test payram", nó sẽ tự động chạy danh sách kiểm tra sẵn sàng, đảm bảo .env tồn tại, và chỉ sau đó gọi test_payram_connection với thông tin xác thực thực của bạn. Hành vi này được xác định bởi prompt tự động hóa Copilot—không cần nhắc thủ công.

Kết nối từ máy khách MCP của bạn

Điểm cuối: https://mcp.payram.com/mcp (Streamable HTTP, JSON-RPC qua POST). Không có điểm cuối SSE, và /mcp/sse trả về 410. Không có tiêu đề xác thực: máy chủ lưu trữ không bao giờ giữ thông tin xác thực của người bán, vì vậy thông tin của bạn vẫn nằm trên máy của bạn và không bao giờ đi vào cuộc trò chuyện.

Máy khách	Nơi	Cài đặt
VS Code (Copilot Chat)	Cài đặt → Copilot: Model Context Protocol → Thêm máy chủ HTTP	Tên `payram`, URL ở trên, tiêu đề trống
Cursor	Cài đặt → Máy chủ MCP → Thêm → HTTP	Tên `payram`, URL ở trên
Claude Desktop / Code	Cài đặt → Máy chủ MCP → Thêm máy chủ HTTP	Tên `payram`, URL ở trên
Bất kỳ máy khách MCP nào	Đăng ký một điểm cuối HTTP	URL ở trên, không có tiêu đề

Xác minh: danh sách công cụ sẽ bắt đầu với payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook và payram_ops_playbook, tiếp theo là scaffold_payram_app và các công cụ đoạn mã generate_*. Sau đó thử: "lên kế hoạch cài đặt PayRam trên pay.example.com", "kiểm tra https://pay.example.com", "tạo route tạo-thanh-toán FastAPI", "đưa cho tôi một trình xử lý webhook Next.js".

Prompts: setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops. Tài nguyên: payram://docs/setup-guide, payram://docs/api-reference, và các mẫu payram://ops/playbook/{task} và payram://runbooks/{task}.

Prompt tự động hóa Copilot

Dán cái này một lần vào một không gian làm việc mới để làm cho "test payram" chạy toàn bộ luồng sẵn sàng tự động:

You have access to the `payram` MCP server in this workspace.

Whenever I ask you to "test my Payram connection" (or I type "test payram"), follow this order:

1. Call `prepare_payram_test` (no inputs) and share the checklist verbatim.
2. Look for a `.env` in the workspace root; create one if missing.
3. Ensure `.env` defines `PAYRAM_BASE_URL` and `PAYRAM_API_KEY`. If either is
   missing, call `generate_env_template` and append it (with TODOs) to `.env`.
   Do NOT call `test_payram_connection` until real values are provided.
4. Once real values exist, call `test_payram_connection` with baseUrl/apiKey
   from `.env`, show the structured result, and explain whether the
   connection is healthy. If anything fails, run `payram_doctor` and follow
   its ranked fixes.

Chế độ cục bộ

Chạy MCP bên cạnh PayRam của riêng bạn để có được các công cụ dữ liệu trực tiếp:

list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients
create_payment_link, check_payment_readiness, check_node_sync, restart_payram_worker
assess_payram_project

PAYRAM_MCP_MODE=local yarn dev        # or: yarn build && PAYRAM_MCP_MODE=local yarn start

Chế độ: PAYRAM_MCP_MODE=local chọn chế độ cục bộ. Nó cũng là mặc định bất cứ khi nào máy chủ không chạy trên Vercel. PAYRAM_MCP_MODE=hosted không bao giờ đọc thông tin xác thực.
Ràng buộc: chế độ cục bộ ràng buộc với 127.0.0.1 theo mặc định (cổng PORT, mặc định 3333).
Ràng buộc không-loopback: đặt HOST (ví dụ: HOST=0.0.0.0), sau đó:
- Đặt MCP_ALLOWED_HOSTS (các tên máy chủ được phân tách bằng dấu phẩy được chấp nhận trong tiêu đề Host).
- Đặt MCP_SERVER_TOKEN; máy khách sau đó gửi Authorization: Bearer <token>.
- Nếu thông tin xác thực PAYRAM_* được đặt, máy chủ từ chối khởi động trên HOST không-loopback mà không có MCP_SERVER_TOKEN. Ưu tiên loopback cộng với một đường hầm SSH.
Thông tin xác thực: các công cụ dữ liệu đọc PAYRAM_* từ môi trường (hoặc .env):
- PAYRAM_BASE_URL
- PAYRAM_API_KEY (liên kết thanh toán)
- PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, công cụ dữ liệu)
- PAYRAM_EXTERNAL_PLATFORM_ID (dự án mặc định tùy chọn)

Ví dụ cấu hình máy khách cho máy chủ cục bộ (chỉ chế độ cục bộ):

{
  "mcpServers": {
    "payram-local": { "url": "http://localhost:3333/mcp" }
  }
}

Thông tin xác thực: khóa nào cho việc gì

PayRam có hai thông tin xác thực — các tác nhân bị kẹt khi chúng gộp chúng lại:

Thông tin xác thực	Trông giống như	Được sử dụng cho	Cách một tác nhân lấy nó (không cần bảng điều khiển)
Khóa API người bán (`PAYRAM_API_KEY`, tiêu đề `API-Key`)	khóa theo dự án	`POST /api/v1/payment` (liên kết thanh toán), thanh toán cho người bán, tất cả các cuộc gọi máy chủ-đến-máy chủ của người bán, và nó ký webhooks (`X-Payram-Signature`)	`bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key` — tái sử dụng hoặc tạo khóa dự án qua `POST /api/v1/external-platform/{id}/api-key` và lưu nó vào `~/.payraminfo/merchant-api-key.env`
JWT (`Authorization: Bearer`)	mã thông báo truy cập+làm mới từ đăng nhập	các API quản trị/thiết lập (dự án, ví, phân tích) — các công thức `payram_ops_playbook` và các công cụ dữ liệu chế độ cục bộ	`bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin` (env `PAYRAM_EMAIL`/`PAYRAM_PASSWORD`); được lưu vào `~/.payraminfo/headless-tokens.env`

Luồng thiết lập một bước (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) tạo ra cả hai tự động và in nơi chúng nằm. API cùng nguồn gốc với bảng điều khiển, trên cổng 80/443 (https://<your-domain>/api/v1/..., hoặc http://localhost trên máy chủ, không bao giờ :8080). Khóa API có thể tạo thanh toán, vì vậy hãy giữ nó ở phía máy chủ và không bao giờ đặt nó trong mã trình duyệt hoặc cuộc trò chuyện. Sử dụng tác vụ payram_ops_playbook connect để thiết lập cả hai cho các cuộc gọi API trực tiếp.

Danh mục công cụ

Danh mục	Công cụ	Mục đích
Bắt đầu tại đây – Cài đặt	`payram_setup_plan`	Kế hoạch cài đặt được cá nhân hóa, có thứ tự (chuẩn bị → cài đặt → xác nhận root + Site URL → ví + Smart Bridge → API key + liên kết đầu tiên → tăng cường bảo mật → tích hợp) với các bước thực hiện bởi agent và con người cùng các điểm dừng bắt buộc.
Bắt đầu tại đây – Chẩn đoán	`payram_doctor`, `payram_troubleshoot`	`payram_doctor`: kiểm tra theo giai đoạn công khai, không cần thông tin xác thực theo URL (khả năng truy cập → tình trạng hoạt động → TLS → phiên bản → worker) kèm nguyên nhân có khả năng xếp hạng + cách khắc phục chính xác. Kiểm tra tính hợp lệ của API key tùy chọn, không tạo ra gì. Chạy CÔNG CỤ NÀY ĐẦU TIÊN khi có bất kỳ lỗi nào. `payram_troubleshoot`: khớp triệu chứng hoặc lỗi đã dán với nguyên nhân và cách khắc phục đã biết.
Bắt đầu tại đây – Quản trị	`payram_runbook`	Các tác vụ quản trị từng bước có cổng chặn con người: `set_site_url`, `change_domain`, `ssl_setup`, `ssl_renewal_fix`, `firewall_ports`, `upgrade`, `backup`, `restore`, `add_chain`, `smart_bridge`, `mainnet_cutover`, `operator_setup`, `rotate_api_key`, `reset_test_install`, `shopify_connector`, `woocommerce_plugin`, `secure_analytics_mcp`.
Bắt đầu tại đây – Vận hành	`payram_ops_playbook`	Các công thức gọi API trực tiếp mà agent tự chạy: `connect`, `health`, `version_check`, `workers`, `restart_worker`, `node_sync`, `site_url`, `payment_options`, `unswept_funds`, `payments_today`, `payment_lookup`, `stuck_payment`, `create_payment_link`, `payouts`, `webhooks`, `logs`, `daily_check`.
Kết nối	`test_payram_connection`	Kiểm tra khả năng truy cập/tình trạng hoạt động chỉ đọc cùng xác thực API key tùy chọn. Không bao giờ tạo thanh toán.
Thiết lập	`generate_env_template`, `generate_setup_checklist`, `suggest_file_structure`, `get_agent_setup_flow`, `onboard_agent_setup`	Cung cấp boilerplate môi trường, danh sách kiểm tra cho merchant, bố cục dự án được khuyến nghị và hướng dẫn onboarding agent không giao diện.
Ngữ cảnh / Tài liệu	`explain_payram_basics`, `explain_payram_concepts`, `explain_payment_flow`, `explain_payram_security`, `get_payram_links`, `prepare_payram_test`, `get_payram_doc_by_id`, `list_payram_docs`, v.v.	Cung cấp kiến thức Markdown nội tuyến lấy từ `docs/` để Copilot có thể trả lời các câu hỏi khái niệm. Một số công cụ tự động thêm lời nhắc “nói `test payram`”.
Tích hợp – Thanh toán	`generate_payment_sdk_snippet`, `generate_payment_http_snippet`, `generate_payment_status_snippet`, `generate_payment_route_snippet`	Tạo mã SDK, HTTP thô hoặc route Express/Next.js cho luồng tạo + trạng thái.
Tích hợp – Thanh toán ra	`generate_payout_sdk_snippet`, `generate_payout_recipient_flow_snippet`, `generate_payout_status_snippet`	Thanh toán ra trực tiếp (không OTP), luồng người nhận đã lưu gồm 3 bước (tạo người nhận → xác thực OTP → thanh toán ra) và kiểm tra trạng thái.
Tích hợp – Giới thiệu	`generate_referral_sdk_snippet`, `generate_referral_validation_snippet`, `generate_referral_status_snippet`, `generate_referral_route_snippet`	Bao gồm xác thực giới thiệu, liên kết, xác thực, trạng thái và route express/next.
Tích hợp – Webhooks	`generate_webhook_handler`, `generate_webhook_event_router`, `generate_mock_webhook_event`	Tạo handler cho Express/Next/FastAPI/Gin/Laravel/Spring Boot, bộ định tuyến fan-out và trình kiểm tra webhook cURL/Python/Go/PHP/Java.
Tích hợp – Thanh toán đa ngôn ngữ	`snippet_*` family (`snippet_express_payment_route`, `snippet_nextjs_payment_route`, `snippet_fastapi_payment_route`, `snippet_laravel_payment_route`, `snippet_go_payment_handler`, `snippet_spring_payment_controller`)	Handler route dựng sẵn cho Express, Next.js App Router, FastAPI, Gin, Laravel và Spring Boot.
Tích hợp – Nạp ví	`generate_topup_integration_snippet`	Cho các ứng dụng HIỆN CÓ: schema sổ cái + webhook tín dụng tích lũy + thanh toán hóa đơn nguyên tử, để các khoản thanh toán crypto thừa/thiếu/trễ/trùng lặp trở thành trạng thái số dư thay vì ngoại lệ thanh toán. Kết hợp với kỹ năng `payram-topup-wallet-integration`.
Tích hợp – Đánh giá dự án (chế độ cục bộ)	`assess_payram_project`	Quét `package.json`, `requirements.txt`, `composer.json`, `go.mod`, `pom.xml`, `.env`, v.v. Báo cáo framework đã phát hiện, trạng thái môi trường, phụ thuộc PayRam và các bước tiếp theo ưu tiên kèm gợi ý công cụ.
Tạo khung ứng dụng	`scaffold_payram_app`	Tạo ứng dụng khởi đầu đầy đủ (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) với thanh toán, thanh toán ra, webhooks và bảng điều khiển trình duyệt. Đặt các endpoint thanh toán ra sau xác thực admin của riêng bạn trước khi triển khai.
Dữ liệu trực tiếp (chỉ đọc, chế độ cục bộ)	`list_platforms`, `search_payments`, `lookup_payment`, `get_payment_summary`, `get_daily_volume`, `get_unswept_balances`, `list_currencies`, `list_recipients`	Truy vấn dữ liệu PayRam trực tiếp. `list_currencies` là công khai (không cần khóa); phần còn lại dùng token JWT trong `.env`. `list_recipients` kết hợp với luồng người nhận thanh toán ra.
Vận hành trực tiếp (chế độ cục bộ)	`create_payment_link` (ghi), `check_payment_readiness`, `check_node_sync`, `restart_payram_worker` (ghi)	`create_payment_link` tạo liên kết thanh toán thực qua `API-Key`. `check_payment_readiness` báo cáo khoảng trống theo chuỗi (thiếu ví / tiền tệ / listener) để nhận thanh toán. `check_node_sync` báo cáo tình trạng listener-worker + nút RPC và độ trễ khối. Trên máy chủ lưu trữ, dùng các tác vụ `payram_ops_playbook` tương ứng.

Đăng ký công cụ nằm trong src/tools/index.ts; các triển khai riêng lẻ nằm trong src/tools/** với mẫu theo ngôn ngữ trong các thư mục templates/.

Quy trình hướng dẫn

0. Cài đặt PayRam

Yêu cầu: “Thiết lập PayRam trên pay.example.com” (hoặc dùng các lời nhắc setup-payram / setup-payram-agent).
Trợ lý gọi payram_setup_plan và thực hiện các giai đoạn, dừng ở mỗi bước con người (tài khoản root, Site URL, ví lạnh, gas mainnet).
Kết thúc bằng payram_doctor, sao lưu (payram_runbook backup) và kiểm tra hàng ngày (payram_ops_playbook daily_check).

1. Đánh giá và trang bị thêm cho dự án hiện có

Hỏi Copilot: "Bạn có thể tích hợp PayRam vào dự án này không?"
Trợ lý chạy assess_payram_project (chế độ cục bộ), xem xét các tệp khai báo phụ thuộc và .env.
Làm theo các bước được đề xuất (cài đặt payram, yêu cầu đoạn mã route Express/FastAPI/Spring, thêm webhooks, v.v.).
Sử dụng test_payram_connection khi thông tin xác thực là thật để đảm bảo backend có thể kết nối với máy chủ tự lưu trữ của bạn.

2. Tạo Mẫu Mới Từ Đầu

"Tạo bản demo PayRam Express" → scaffold_payram_app xây dựng một dự án Express với thanh toán, thanh toán tiền, webhooks và giao diện điều khiển UI.
Đưa các tệp đã tạo vào một kho lưu trữ trống hoặc so sánh với thư mục hiện có của bạn để tham khảo cách kết nối.

3. Chạy Luồng Kiểm Tra Sẵn Sàng "Test PayRam"

Nói "test payram". Trợ lý sẽ tự động:
- Gọi prepare_payram_test để chia sẻ danh sách kiểm tra sẵn sàng.
- Đảm bảo .env tồn tại (tạo nếu thiếu) bằng generate_env_template.
- Chờ thông tin xác thực thật trước khi gọi test_payram_connection.
Xem lại kết quả JSON có cấu trúc để xác nhận API PayRam có thể truy cập được.

4. Kết Nối Thanh Toán, Thanh Toán Tiền, Giới Thiệu và Webhooks

Thanh toán: generate_payment_sdk_snippet (JS SDK) hoặc generate_payment_http_snippet (Python/Go/PHP/Java).
Route đa ngôn ngữ: snippet_nextjs_payment_route, snippet_fastapi_payment_route, v.v.
Thanh toán tiền: generate_payout_sdk_snippet để tạo + generate_payout_status_snippet để kiểm tra trạng thái.
Giới thiệu: generate_referral_route_snippet, generate_referral_validation_snippet.
Webhooks: generate_webhook_handler cộng generate_webhook_event_router để phân phối + generate_mock_webhook_event để kiểm tra từng trạng thái.

Phát Triển

Lệnh	Mô tả
`yarn dev`	Chạy máy chủ MCP với tải lại nóng qua `tsx`.
`yarn build`	Biên dịch TypeScript sang `dist/`.
`yarn lint` / `yarn format`	ESLint + Prettier trên toàn bộ kho lưu trữ.
`yarn test`	Chạy bộ kiểm thử Vitest (`tests/`).
`make precommit-test`	Chạy tuần tự format → lint → test → build.

Dự án ưu tiên TypeScript (ESM). Cấu hình Prettier nằm trong .prettierrc.json; ESLint được cấu hình qua eslint.config.mjs. Đóng góp mượt mà theo trình trợ giúp commit trong Makefile → make commit.

Xử Lý Sự Cố

Bắt đầu với payram_doctor — một lệnh gọi chỉ đọc kiểm tra khả năng truy cập → sức khỏe → TLS → phiên bản → worker và trả về nguyên nhân được xếp hạng kèm cách khắc phục chính xác. Để kiểm tra sâu hơn, làm theo payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).

Copilot không gọi đúng công cụ: Kiểm tra prompt tự động hóa Copilot đã được cài đặt và máy khách MCP của bạn đã tải máy chủ. Chạy lại "test payram" hoặc "assess my project" để kích hoạt tự động hóa mong đợi.
test_payram_connection thất bại với 401: Xác nhận khóa là khóa API dự án đang hoạt động (được gửi dưới dạng tiêu đề API-Key, không phải Authorization).
Công cụ dữ liệu báo thông tin xác thực không khả dụng: máy chủ lưu trữ không bao giờ giữ thông tin xác thực của người bán. Sử dụng tác vụ payram_ops_playbook tương ứng, hoặc chạy MCP ở chế độ cục bộ.
Liên kết thanh toán hiển thị http://localhost: người dùng phải lưu Cài đặt → URL trang web từ tên miền công khai (tác vụ payram_runbook set_site_url).
Công cụ tài liệu báo thiếu tệp: Xác minh cây docs/payram-docs-live/ cục bộ của bạn chứa markdown được yêu cầu (get_payram_doc_by_id từ chối đường dẫn có ..).
Máy chủ không khởi động: Đảm bảo Node 20+ và chạy yarn install. Trong chế độ cục bộ với HOST không phải loopback và thông tin xác thực PAYRAM_* được đặt, máy chủ từ chối khởi động cho đến khi MCP_SERVER_TOKEN được đặt (xem Chế độ cục bộ).

Đối với bất kỳ vấn đề nào khác, kiểm tra nhật ký có cấu trúc phát ra từ src/utils/logger.ts (đặt LOG_LEVEL=debug) và mở issue/PR kèm chi tiết tái hiện.