PayRam Crypto Card Payment Gateway

Server MCP PayRam — Pembayaran Kripto Self-Hosted untuk Agen AI

Pembayaran kripto dan stablecoin self-hosted: tanpa penguncian akun, tanpa pembekuan dana, data pelanggan tidak pernah dibagikan. Agen AI Anda dapat merencanakan, menginstal, dan mengoperasikannya melalui MCP. Endpoint yang di-hosting: https://mcp.payram.com/mcp · Situs Web · Dokumentasi · Agentic · OpenClaw

Server MCP (Model Context Protocol) yang memungkinkan agen AI apa pun yang mendukung MCP — OpenClaw, Hermes, Claude, Cursor, GitHub Copilot, dan lainnya — untuk men-deploy, mengintegrasikan, dan mengoperasikan tumpukan pembayaran kripto PayRam yang di-host sendiri.

Mulai di sini: empat alat memimpin katalog:

Alat	Fungsinya
payram_setup_plan	Rencana instalasi yang dipersonalisasi, dengan setiap serah terima manusia ditandai
payram_doctor	Pemeriksaan publik tanpa kredensial terhadap server PayRam berdasarkan URL
payram_troubleshoot	Jelaskan masalah atau tempelkan error: penyebab yang diketahui, cara konfirmasi, perbaikan, dan alat berikutnya
payram_runbook	Tugas admin: URL Situs, domain, SSL, firewall, upgrade, backup, rantai, Smart Bridge, Shopify/WooCommerce
payram_ops_playbook	Resep API hari-2 yang dijalankan sendiri oleh agen dengan kredensialnya sendiri

Di sekitarnya terdapat penilaian codebase, kerangka aplikasi pemula, cuplikan multi-bahasa, dan dokumentasi inline.

Server yang di-hosting (mcp.payram.com) tidak pernah menyimpan kredensial merchant. Operasi hari-2 berjalan melalui payram_ops_playbook: agen memanggil API PayRam Anda secara langsung, dan kredensial tidak pernah meninggalkan mesinnya. Alat data langsung (pencarian pembayaran, tautan pembayaran, sinkronisasi node, restart worker) dan assess_payram_project hanya ada saat Anda menjalankan MCP sendiri dalam mode lokal.

Untuk agen & crawler: kartu server · indeks keterampilan · llms.txt · sitemap. Server juga menjawab Accept: text/markdown pada / dengan ringkasan yang dapat dibaca agen.

---

Apa itu PayRam? · PayRam 是什么？

PayRam adalah gateway pembayaran kripto multi-rantai yang di-host sendiri dan sepenuhnya Anda miliki — tanpa pendaftaran dan tanpa KYC/KYB untuk menjalankannya. Agen AI (atau pengembang) dapat mendirikan toko dan mulai menerima pembayaran tanpa mendaftarkan akun ke PayRam, bank, atau prosesor pembayaran mana pun. Deploy di VPS Anda sendiri, buat kunci API secara lokal, dan langsung beroperasi.

Apa yang membuatnya berbeda:

• Tidak ada yang bisa mengunci Anda — tidak ada akun yang bisa dikunci dan tidak ada dana yang bisa dibekukan. Data pelanggan tidak pernah dibagikan, dan tidak ada yang dilaporkan atau dipantau. Alasannya sederhana: PayRam berjalan di server Anda dan dana masuk ke dompet Anda sendiri.
• Pengaturan tanpa izin — tanpa pendaftaran, tanpa KYC, tanpa KYB. Tidak ada yang menyetujui Anda; tidak ada yang bisa mematikan Anda. Ideal untuk agen yang membuat toko secara otonom, dan untuk pasar seperti Tiongkok di mana mendaftar ke prosesor Barat bukanlah pilihan.
• Pembayaran kartu-ke-kripto — pembeli tanpa kripto dapat membayar dengan kartu kredit/debit dan Anda menerima kripto, diselesaikan langsung ke dompet yang Anda kendalikan sendiri. Ini adalah saluran bawaan yang Anda aktifkan dari halaman Payments; penyedia kartu menjalankan pemeriksaan sendiri pada pembeli.
• Multi-rantai — terima BTC, ETH, USDT, USDC, dan TRX secara native di Bitcoin, Ethereum, Base, Polygon, dan Tron, dengan deteksi setoran otomatis, konfirmasi on-chain, penyapuan ke penyimpanan dingin, dan webhook yang ditandatangani. Jalur Smart Bridge juga menerima pembayaran di Solana, Bitcoin, Tron (USDT) dan BNB Chain dan menyelesaikannya sebagai USDC di Base.
• Tanpa kunci setoran di server — kontrak pintar menyapu setoran ke dompet dingin Anda, sehingga server yang disusupi tidak dapat mengarahkannya ulang. Dompet panas server membayar gas dan menandatangani pembayaran keluar, jadi jaga saldonya tetap kecil.

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 并签署出款，请只保留少量余额。

---

Bagaimana agen AI menggunakan PayRam · AI 智能体如何使用 PayRam

PayRam adalah infrastruktur yang mengutamakan agen (agent-first). Karena integrasi melalui MCP, ia bekerja dengan runtime apa pun yang mendukung MCP — OpenClaw, Hermes, Claude Desktop, Cursor, GitHub Copilot, n8n, LangChain, dan lainnya. Alur agen yang umum:

1. Hubungkan — tambahkan https://mcp.payram.com/mcp ke konfigurasi MCP agen (tanpa kunci API hanya untuk terhubung).
2. Rencanakan — panggil payram_setup_plan. Ini mengembalikan langkah-langkah yang berurutan, siapa yang menjalankan masing-masing, dan di mana agen harus berhenti untuk manusia (dompet dingin, gas mainnet, pengaturan khusus root).
3. Instal — di VPS, di terminal interaktif sekali, jalankan bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet (atau --mainnet; default penginstal adalah mainnet, jadi selalu berikan flag). Jangan pernah menyalurkannya ke bash.
4. Serah terima — manusia segera mengklaim akun root dan menyimpan Settings → Site URL dari domain publik; sampai saat itu, tautan pembayaran mengarah ke http://localhost.
5. Periksa — payram_doctor dengan URL publik (tanpa kredensial).
6. Terima pembayaran — masukkan kode integrasi khusus kerangka kerja dari alat cuplikan. Webhook ditandatangani (X-Payram-Signature, HMAC-SHA256 dari body mentah dengan kunci API proyek).
7. Operasikan — payram_ops_playbook (daily_check, payment_options, node_sync, unswept_funds, create_payment_link, …) memberi agen panggilan API yang tepat untuk dijalankan dengan kredensialnya sendiri. payram_runbook mencakup perubahan admin.

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

Untuk panduan khusus OpenClaw (pendaftaran, testnet di Base Sepolia, pola chat-commerce untuk WhatsApp/Telegram/Discord) lihat keterampilan payram-openclaw-integration dan 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 服务器从不保存商户凭证。

Jika GitHub sulit dijangkau dari jaringan Anda, Anda dapat memirror repositori ini ke host Git lain (git clone --mirror https://github.com/PayRam/payram-mcp.git). 如果你的网络难以访问 GitHub，可以把本仓库镜像到其他 Git 托管平台（git clone --mirror https://github.com/PayRam/payram-mcp.git）。

---

Daftar Isi

• Apa itu PayRam?
• Bagaimana agen AI menggunakan PayRam
• Keterampilan Agen
• Tujuan Proyek
• Memulai Cepat
• Hubungkan dari klien MCP Anda
• Mode lokal
• Kredensial
• Katalog Alat
• Alur Kerja Terpandu
• Pengembangan
• Pemecahan Masalah

---

Keterampilan Agen

Pintu depan agen: https://mcp.payram.com/SKILL.md — satu keterampilan root yang menjelaskan PayRam dan mengarahkan agen ke empat alat mulai-di-sini. Juga disajikan: /llms.txt.

Repositori ini mencakup 19 Keterampilan Agen untuk asisten pengkodean AI. Instal melalui skills.sh:

Instal secara individual

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

Keterampilan	Tujuan
payram-setup	Rencana instalasi dan pengaturan server: persyaratan, penginstal, URL Situs, dompet, tautan pembayaran pertama
payram-agent-onboarding	Instalasi tanpa kepala oleh agen: perintah CLI agen, variabel env, serah terima manusia
payram-auth	Alur auth JWT — masuk, refresh token, keluar, detail platform eksternal
payram-analytics	Pencarian pembayaran, volume, saldo, dan riwayat penyapuan melalui REST API langsung (JWT)
payram-crypto-payments	Ringkasan arsitektur, mengapa PayRam, alat MCP
payram-payment-integration	Panduan integrasi pembayaran mulai cepat
payram-self-hosted-payment-gateway	Deploy dan miliki infrastruktur pembayaran Anda
payram-checkout-integration	Alur checkout dengan SDK + HTTP untuk 6 kerangka kerja
payram-widget-integration	Tombol "Tambah Kredit" yang aman (endpoint backend, tidak pernah kunci API publik) + penangan webhook yang ditandatangani
payram-webhook-integration	Penangan webhook yang ditandatangani (HMAC) untuk Express, Next.js, FastAPI, Gin, Laravel, Spring Boot
payram-stablecoin-payments	Penerimaan USDT/USDC di seluruh rantai EVM dan Tron
payram-bitcoin-payments	BTC dengan derivasi dompet HD dan penandatanganan seluler
payram-payouts	Kirim pembayaran keluar kripto dan kelola program rujukan
payram-no-kyc-crypto-payments	Penerimaan pembayaran tanpa KYC, tanpa pendaftaran, tanpa izin
payram-openclaw-integration	Integrasikan PayRam ke OpenClaw / runtime agen — daftar MCP, testnet, chat commerce
compare-crypto-payments	Bandingkan gateway: Stripe, BitPay, Coinbase, NOWPayments, BTCPay, PayRam, x402
payram-agent-journey	Peta mulai-di-sini: instal (merchant atau operator) → dompet → gas/sapu → integrasikan → uji
payram-topup-wallet-integration	Aplikasi yang ada: kredit kripto ke saldo pengguna, debit faktur darinya — buku besar + alur
payram-testnet-testing	Bayar tautan pembayaran Anda sendiri di testnet dari ujung ke ujung sebelum mainnet

---

Tujuan Proyek

• Percepat orientasi dengan rencana pengaturan yang dipersonalisasi, runbook, template env, dan playbook per kerangka kerja.
• Beroperasi tanpa menyimpan kredensial: server yang di-hosting memeriksa PayRam berdasarkan URL (payram_doctor) dan memberikan resep API yang tepat kepada agen (payram_ops_playbook) untuk dijalankan dengan kredensial mereka sendiri.
• Retrofit repositori yang ada melalui alat penilaian proyek (mode lokal), yang memindai manifes paket dan file .env, lalu merekomendasikan cuplikan integrasi yang tepat.
• Sediakan cuplikan salin/tempel yang mencakup Pembayaran, Pembayaran Keluar, Rujukan, Webhook, dan backend multi-bahasa (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot, dll.).
• Jaga dokumentasi tetap lokal sehingga Copilot dapat menjelaskan konsep, alur, dan dasbor rujukan PayRam tanpa meninggalkan editor.
• Validasi konektivitas dengan probe hanya-baca yang tidak pernah membuat pembayaran (payram_doctor, test_payram_connection).

---

Memulai Cepat

Sebagian besar agen hanya memerlukan endpoint yang di-hosting, https://mcp.payram.com/mcp (lihat Hubungkan dari klien MCP Anda). Untuk menjalankan server sendiri:

1. Instal dependensi

   yarn install
   

2. Konfigurasi lingkungan (hanya diperlukan untuk alat data mode lokal)
   • Salin .env.example ke .env.
   • Atur PAYRAM_BASE_URL ke URL PayRam Anda, asal yang sama dengan dasbor (misalnya https://pay.example.com).
   • Atur PAYRAM_API_KEY, beserta variabel JWT untuk alat data. Lihat Mode lokal.
3. Jalankan server

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

4. Tambahkan server MCP ke klien Anda: lihat Hubungkan dari klien MCP Anda. URL mode lokal adalah http://localhost:3333/mcp.
5. Pemeriksaan kesehatan

   curl http://localhost:3333/healthz
   

Tips: Saat Anda memberi tahu Copilot "test payram", ia akan otomatis menjalankan daftar periksa kesiapan, memastikan .env ada, dan hanya kemudian memanggil test_payram_connection dengan kredensial asli Anda. Perilaku ini didefinisikan oleh prompt otomatisasi Copilot—tidak perlu prompt manual.

---

Hubungkan dari klien MCP Anda

Endpoint: https://mcp.payram.com/mcp (Streamable HTTP, JSON-RPC melalui POST). Tidak ada endpoint SSE, dan /mcp/sse mengembalikan 410. Tanpa header auth: server yang dihosting tidak pernah menyimpan kredensial merchant, jadi kredensial Anda tetap di mesin Anda dan tidak pernah masuk ke chat.

Klien	Tempat	Pengaturan
VS Code (Copilot Chat)	Settings → Copilot: Model Context Protocol → Add HTTP server	Nama payram, URL di atas, header kosong
Cursor	Settings → MCP Servers → Add → HTTP	Nama payram, URL di atas
Claude Desktop / Code	Settings → MCP Servers → Add HTTP server	Nama payram, URL di atas
Klien MCP apa pun	Daftarkan endpoint HTTP	URL di atas, tanpa header

Verifikasi: daftar alat harus dimulai dengan payram_setup_plan, payram_doctor, payram_troubleshoot, payram_runbook dan payram_ops_playbook, diikuti oleh scaffold_payram_app dan alat cuplikan generate_*. Kemudian coba: "rencanakan instalasi PayRam di pay.example.com", "periksa https://pay.example.com", "buat rute create-payment FastAPI", "beri saya handler webhook Next.js".

Prompt: setup-payram, setup-payram-agent, integrate-payment, troubleshoot-payment, daily-ops. Sumber daya: payram://docs/setup-guide, payram://docs/api-reference, dan templat payram://ops/playbook/{task} dan payram://runbooks/{task}.

Prompt otomatisasi Copilot

Tempel ini sekali ke ruang kerja baru untuk membuat "test payram" menjalankan alur kesiapan penuh secara otomatis:

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.

---

Mode lokal

Jalankan MCP di samping PayRam Anda sendiri untuk mendapatkan alat data langsung:

• 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

• Mode: PAYRAM_MCP_MODE=local memilih mode lokal. Ini juga merupakan default setiap kali server tidak berjalan di Vercel. PAYRAM_MCP_MODE=hosted tidak pernah membaca kredensial.
• Binding: mode lokal terikat ke 127.0.0.1 secara default (port PORT, default 3333).
• Bind non-loopback: atur HOST (misalnya HOST=0.0.0.0), lalu:
  • Atur MCP_ALLOWED_HOSTS (nama host yang dipisahkan koma diterima di header Host).
  • Atur MCP_SERVER_TOKEN; klien kemudian mengirim Authorization: Bearer <token>.
  • Jika kredensial PAYRAM_* diatur, server menolak untuk memulai pada HOST non-loopback tanpa MCP_SERVER_TOKEN. Lebih suka loopback plus tunnel SSH.
• Kredensial: alat data membaca PAYRAM_* dari lingkungan (atau .env):
  • PAYRAM_BASE_URL
  • PAYRAM_API_KEY (tautan pembayaran)
  • PAYRAM_ACCESS_TOKEN / PAYRAM_REFRESH_TOKEN (JWT, alat data)
  • PAYRAM_EXTERNAL_PLATFORM_ID (proyek default opsional)

Contoh konfigurasi klien untuk server lokal (hanya mode lokal):

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

---

Kredensial: kunci mana untuk apa

PayRam memiliki dua kredensial — agen akan macet ketika mereka mencampuradukkan keduanya:

Kredensial	Terlihat seperti	Digunakan untuk	Cara agen mendapatkannya (tanpa dasbor)
Kunci API merchant (PAYRAM_API_KEY, header API-Key)	kunci per-proyek	POST /api/v1/payment (tautan pembayaran), pembayaran merchant, semua panggilan server-ke-server merchant, dan menandatangani webhook (X-Payram-Signature)	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) ensure-api-key — menggunakan kembali atau mencetak kunci proyek melalui POST /api/v1/external-platform/{id}/api-key dan menyimpannya ke ~/.payraminfo/merchant-api-key.env
JWT (Authorization: Bearer)	token akses+refresh dari signin	API admin/setup (proyek, dompet, analitik) — resep payram_ops_playbook dan alat data mode lokal	bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) signin (env PAYRAM_EMAIL/PAYRAM_PASSWORD); disimpan ke ~/.payraminfo/headless-tokens.env

Alur setup satu langkah (bash <(curl -fsSL https://payram.com/setup_payram_agents.sh) --testnet) menghasilkan keduanya secara otomatis dan mencetak di mana mereka berada. API sama-asal dengan dasbor, di port 80/443 (https://<your-domain>/api/v1/..., atau http://localhost di server, tidak pernah :8080). Kunci API dapat membuat pembayaran, jadi simpan di sisi server dan jangan pernah menaruhnya di kode browser atau chat. Gunakan tugas payram_ops_playbook connect untuk mengatur keduanya untuk panggilan API langsung.

---

Katalog Alat

Kategori	Alat	Tujuan
Mulai di sini – Instalasi	payram_setup_plan	Rencana instalasi yang dipersonalisasi dan berurutan (persiapan → instalasi → klaim root + URL Situs → dompet + Smart Bridge → kunci API + tautan pertama → perkuat → integrasikan) dengan langkah agen vs manusia dan penghentian keras.
Mulai di sini – Diagnostik	payram_doctor, payram_troubleshoot	payram_doctor: pemeriksaan bertahap publik tanpa kredensial berdasarkan URL (keterjangkauan → kesehatan → TLS → versi → pekerja) dengan penyebab yang paling mungkin diperingkat + perbaikan yang tepat. Pemeriksaan validitas kunci API opsional yang tidak membuat apa pun. Jalankan ini PERTAMA saat ada yang gagal. payram_troubleshoot: cocokkan gejala atau kesalahan yang ditempel dengan penyebab dan perbaikan yang diketahui.
Mulai di sini – Admin	payram_runbook	Tugas admin langkah demi langkah dengan gerbang manusia: 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.
Mulai di sini – Operasi	payram_ops_playbook	Resep API langsung yang dijalankan agen sendiri: 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.
Konektivitas	test_payram_connection	Pemeriksaan keterjangkauan/kesehatan hanya-baca plus validasi kunci API opsional. Tidak pernah membuat pembayaran.
Pengaturan	generate_env_template, generate_setup_checklist, suggest_file_structure, get_agent_setup_flow, onboard_agent_setup	Mengirim boilerplate env, daftar periksa merchant, tata letak proyek yang direkomendasikan, dan panduan on-boarding agen tanpa kepala.
Konteks / Dokumen	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, dll.	Menyediakan pengetahuan Markdown inline yang bersumber dari docs/ sehingga Copilot dapat menjawab pertanyaan konseptual. Beberapa alat menambahkan pengingat "katakan test payram" secara otomatis.
Integrasi – Pembayaran	generate_payment_sdk_snippet, generate_payment_http_snippet, generate_payment_status_snippet, generate_payment_route_snippet	Menghasilkan kode SDK, HTTP mentah, atau rute Express/Next.js untuk alur buat + status.
Integrasi – Pembayaran Keluar	generate_payout_sdk_snippet, generate_payout_recipient_flow_snippet, generate_payout_status_snippet	Pembayaran keluar langsung (tanpa OTP), alur penerima tersimpan 3 langkah (buat penerima → validasi OTP → bayar), dan pemantauan status.
Integrasi – Referral	generate_referral_sdk_snippet, generate_referral_validation_snippet, generate_referral_status_snippet, generate_referral_route_snippet	Mencakup autentikasi referral, penautan, validasi, status, dan rute express/next.
Integrasi – Webhook	generate_webhook_handler, generate_webhook_event_router, generate_mock_webhook_event	Menghasilkan handler untuk Express/Next/FastAPI/Gin/Laravel/Spring Boot, router fan-out, dan penguji webhook cURL/Python/Go/PHP/Java.
Integrasi – Pembayaran Multi-bahasa	snippet_* keluarga (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 rute yang sudah dibuat untuk Express, Next.js App Router, FastAPI, Gin, Laravel, dan Spring Boot.
Integrasi – Isi Ulang Dompet	generate_topup_integration_snippet	Untuk aplikasi YANG SUDAH ADA: skema buku besar + webhook kredit kumulatif + penyelesaian faktur atomik, sehingga pembayaran kripto berlebih/kurang/terlambat/duplikat menjadi status saldo alih-alih pengecualian pembayaran. Berpasangan dengan keterampilan payram-topup-wallet-integration.
Integrasi – Penilaian Proyek (mode lokal)	assess_payram_project	Memindai package.json, requirements.txt, composer.json, go.mod, pom.xml, .env, dll. Melaporkan framework yang terdeteksi, status env, dependensi PayRam, dan langkah berikutnya yang diprioritaskan dengan saran alat.
Scaffolding	scaffold_payram_app	Menghasilkan aplikasi starter lengkap (Express, Next.js, FastAPI, Laravel, Gin, Spring Boot) dengan pembayaran, pembayaran keluar, webhook, dan konsol browser. Letakkan endpoint pembayaran keluar di belakang autentikasi admin Anda sendiri sebelum men-deploy.
Data Langsung (hanya-baca, mode lokal)	list_platforms, search_payments, lookup_payment, get_payment_summary, get_daily_volume, get_unswept_balances, list_currencies, list_recipients	Kueri data PayRam langsung. list_currencies bersifat publik (tanpa kunci); sisanya menggunakan token JWT di .env. list_recipients berpasangan dengan alur penerima pembayaran keluar.
Operasi Langsung (mode lokal)	create_payment_link (tulis), check_payment_readiness, check_node_sync, restart_payram_worker (tulis)	create_payment_link membuat tautan checkout nyata melalui API-Key. check_payment_readiness melaporkan kesenjangan per-rantai (dompet / mata uang / pendengar yang hilang) untuk menerima pembayaran. check_node_sync melaporkan kesehatan pendengar-pekerja + node RPC dan staleness blok. Di server yang di-hosting, gunakan tugas payram_ops_playbook yang sesuai.

Registrasi alat berada di src/tools/index.ts; implementasi individual berada di src/tools/** dengan template khusus bahasa di bawah folder templates/.

---

Alur Kerja Terpandu

0. Instal PayRam

1. Minta: "Siapkan PayRam di pay.example.com" (atau gunakan prompt setup-payram / setup-payram-agent).
2. Asisten memanggil payram_setup_plan dan menjalani fase-fase, berhenti di setiap langkah manusia (akun root, URL Situs, dompet dingin, gas mainnet).
3. Diakhiri dengan payram_doctor, cadangan (payram_runbook backup) dan pemeriksaan harian (payram_ops_playbook daily_check).

1. Menilai dan Merombak Proyek yang Ada

1. Tanyakan kepada Copilot: "Bisakah Anda mengintegrasikan PayRam ke dalam proyek ini?"
2. Asisten menjalankan assess_payram_project (mode lokal), meninjau manifes dependensi dan .env.
3. Ikuti langkah-langkah yang direkomendasikan (instal payram, minta snippet rute Express/FastAPI/Spring, tambahkan webhooks, dll.).
4. Gunakan test_payram_connection setelah kredensial asli tersedia untuk memastikan backend Anda dapat menjangkau server self-hosted Anda.

2. Membuat Contoh Baru dari Awal

1. "Buat demo PayRam Express" → scaffold_payram_app membangun proyek Express dengan pembayaran, pembayaran keluar, webhooks, dan konsol UI.
2. Letakkan file yang dihasilkan ke dalam repositori kosong atau bandingkan dengan direktori yang ada untuk referensi wiring.

3. Jalankan Alur Kesiapan "Test PayRam"

1. Ucapkan "test payram". Asisten secara otomatis:
   • Memanggil prepare_payram_test untuk membagikan daftar periksa kesiapan.
   • Memastikan .env ada (membuatnya jika tidak ada) menggunakan generate_env_template.
   • Menunggu kredensial asli sebelum memanggil test_payram_connection.
2. Tinjau hasil JSON terstruktur untuk mengonfirmasi bahwa API PayRam dapat dijangkau.

4. Hubungkan Pembayaran, Pembayaran Keluar, Referral, dan Webhooks

• Pembayaran: generate_payment_sdk_snippet (SDK JS) atau generate_payment_http_snippet (Python/Go/PHP/Java).
• Rute multi-bahasa: snippet_nextjs_payment_route, snippet_fastapi_payment_route, dll.
• Pembayaran keluar: generate_payout_sdk_snippet untuk membuat + generate_payout_status_snippet untuk polling.
• Referral: generate_referral_route_snippet, generate_referral_validation_snippet.
• Webhooks: generate_webhook_handler plus generate_webhook_event_router untuk fan-out + generate_mock_webhook_event untuk menguji setiap status.

---

Pengembangan

Perintah	Deskripsi
yarn dev	Jalankan server MCP dengan hot reload melalui tsx.
yarn build	Kompilasi TypeScript ke dist/.
yarn lint / yarn format	ESLint + Prettier di seluruh repositori.
yarn test	Menjalankan suite Vitest (tests/).
make precommit-test	Menjalankan format → lint → test → build secara berurutan.

Proyek ini berbasis TypeScript (ESM). Konfigurasi Prettier ada di .prettierrc.json; ESLint dikonfigurasi melalui eslint.config.mjs. Kontribusi yang lancar mengikuti helper commit di Makefile → make commit.

---

Pemecahan Masalah

Mulai dengan payram_doctor — satu panggilan read-only yang memeriksa keterjangkauan → kesehatan → TLS → versi → pekerja dan mengembalikan penyebab yang diurutkan dengan perbaikan yang tepat. Untuk pemeriksaan lebih dalam, ikuti payram_ops_playbook (stuck_payment, node_sync, webhooks, logs).

• Copilot tidak memanggil alat yang tepat: Periksa apakah prompt otomatisasi Copilot terinstal dan klien MCP Anda memuat server. Jalankan ulang "test payram" atau "assess my project" untuk memicu otomatisasi yang diharapkan.
• test_payram_connection gagal dengan 401: Konfirmasi bahwa kunci tersebut adalah kunci API proyek yang aktif (dikirim sebagai header API-Key, bukan Authorization).
• Alat data mengatakan kredensial tidak tersedia: server yang di-host tidak pernah menyimpan kredensial merchant. Gunakan tugas payram_ops_playbook yang sesuai, atau jalankan MCP dalam mode lokal.
• Tautan pembayaran menunjukkan http://localhost: manusia harus menyimpan Pengaturan → URL Situs dari domain publik (tugas payram_runbook set_site_url).
• Alat dokumen mengatakan file tidak ada: Verifikasi bahwa pohon docs/payram-docs-live/ lokal Anda berisi markdown yang diminta (get_payram_doc_by_id menolak jalur dengan ..).
• Server tidak mau mulai: Pastikan Node 20+ dan jalankan yarn install. Dalam mode lokal dengan HOST non-loopback dan kredensial PAYRAM_* disetel, server menolak untuk mulai sampai MCP_SERVER_TOKEN disetel (lihat Mode lokal).

Untuk hal lain, periksa log terstruktur yang dipancarkan dari src/utils/logger.ts (setel LOG_LEVEL=debug) dan buka issue/PR dengan detail reproduksi.