# Integrasi dengan AI · blockwallets

> Tambahkan pembayaran kripto blockwallets tanpa menulis kode sendiri: pilih situs dan alat AI Anda, salin prompt yang dihasilkan ke Claude Code, Codex, Cursor, atau ChatGPT, dan ia berintegrasi dari dokumentasi lalu memeriksa hasil kerjanya sendiri.
>
> HTML: https://blockwallets.io/docs/ai?lang=id · English: https://blockwallets.io/docs/ai.md?lang=en

## Prompt universal

```text
Bantu saya menerima pembayaran kripto di situs saya dengan blockwallets (pelanggan membayar dengan USDT, USDC, BTC, dan lainnya; saya dikreditkan dalam dolar AS).

1. Baca dokumentasi dulu, jangan menebak API: https://blockwallets.io/llms-full.txt (dokumentasi lengkap) dan https://blockwallets.io/agents.md (aturan integrasi, kesalahan umum, daftar periksa penerimaan). Beri tahu saya jika kamu tidak bisa membukanya.
2. Lihat proyek saya, beri tahu saya dibuat dengan apa dan bagaimana rencana integrasimu, lalu tunggu persetujuan saya.
3. Defaultnya “buat tagihan dan arahkan ke halaman pembayaran + webhook”. Selalu verifikasi tanda tangan webhook, dan hindari duplikat webhook karena webhook yang sama bisa datang dua kali.
4. Simpan merchant ID dan API key di variabel lingkungan, dan buat berfungsi dulu dengan kredensial Test di testnet.
5. Setelah selesai, jalankan daftar periksa penerimaan di agents.md butir demi butir dan beri tahu saya tiap hasilnya.

Saya bukan programmer: untuk setiap langkah, beri tahu saya apa yang kamu ubah dan apa yang perlu saya lakukan.
```

## Ceritakan tentang situs Anda.

Tidak yakin? Pilih “Lainnya / tidak yakin” dan AI akan melihat proyek Anda dulu.

- Situs Anda dibuat dengan: WordPress / WooCommerce · PHP · Node.js / Next.js · Python · Go · Java · Lainnya / tidak yakin
- Cara Anda ingin dibayar:
  - Arahkan ke halaman pembayaran: Buat tagihan saat checkout, kami memberi tahu server Anda saat lunas. Pesanan terkirim sendiri.
  - Alamat setoran tetap per pengguna: Setiap pengguna mendapat alamat permanen dan bisa top-up berapa pun, kapan pun.
  - Tautan pembayaran (tanpa kode): Buat tautan di dasbor dan bagikan. AI hanya menambahkan tombol.

Tautan pembayaran tidak perlu kode: dasbor → “Pembayaran › Tautan pembayaran” → isi jumlah → buat, lalu bagikan tautannya. AI hanya menaruh tombol di situs Anda.

## AI mana yang Anda pakai?

- **Claude Code / Codex**: AI yang mengedit kode Anda dan menjalankan perintah. Paling mudah.
  - Buka terminal di folder proyek situs Anda dan simpan aturan integrasi sebagai AGENTS.md:
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Codex membaca AGENTS.md sendiri. Untuk Claude Code, jalankan juga:
  - `echo '@AGENTS.md' >> CLAUDE.md`
  - Lalu tempel prompt dari langkah 3.
  - Anda juga bisa memasang server MCP blockwallets agar AI bisa mencari dokumentasi dan membuat tagihan uji secara langsung. https://blockwallets.io/docs/mcp?lang=id
- **Cursor / Windsurf / Copilot**: AI di dalam editor kode Anda.
  - Taruh AGENTS.md di root proyek juga (Cursor membacanya otomatis):
  - `curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md`
  - Beralih ke mode Agent dan tempel prompt.
  - Anda juga bisa memasang server MCP blockwallets agar AI bisa mencari dokumentasi dan membuat tagihan uji secara langsung. https://blockwallets.io/docs/mcp?lang=id
- **ChatGPT / Claude (web)**: Hanya obrolan. Anda sendiri yang menempelkan kode ke situs.
  - Tempel prompt ke obrolan baru, atau pakai “Buka di ChatGPT / Claude” di bawah.
  - Jika ia bilang tidak bisa membuka tautan, buka https://blockwallets.io/llms-full.txt, pilih semua, salin, lalu tempel juga.
  - Ia akan memberi kode lengkap dan tempat menaruhnya; ikuti langkah demi langkah. Alat yang mengedit kode untuk Anda (Claude Code, Codex, Cursor) menghemat banyak salin-tempel.
- **AI lain**: Gemini, Copilot chat, dan lainnya.
  - Tempel prompt. Jika ia tidak bisa membuka halaman web, tempel juga isi llms-full.txt.

## Salin promptnya.

Prompt ikut berubah sesuai pilihan Anda di atas dan memuat tautan dokumentasi, jebakan yang umum, dan daftar periksa penerimaan.

Contoh: Lainnya / tidak yakin + arahkan ke halaman pembayaran + Claude Code / Codex

```text
Kamu adalah developer saya. Bantu saya menerima pembayaran kripto di situs saya dengan blockwallets (pelanggan membayar dengan USDT, USDC, BTC, dan 14 koin lain; saya dikreditkan dalam dolar AS).

## Tentang saya
- Situs saya dibuat dengan: Saya tidak yakin. Lihat dulu proyek saya, beri tahu saya dibuat dengan apa, lalu mulai.
- Cara saya ingin dibayar: Buat tagihan saat checkout dan arahkan pelanggan ke halaman pembayaran blockwallets; saat dana masuk, blockwallets memanggil server saya dan saya menandai pesanan sebagai lunas lalu mengirimnya.
- Saya bukan programmer. Untuk setiap langkah, beri tahu saya file mana yang kamu ubah dan apa yang perlu saya lakukan (misalnya di mana menaruh variabel lingkungan). Jangan ubah terlalu banyak sekaligus.
- AGENTS.md di root proyek berisi aturan integrasi blockwallets; baca itu dulu, dan baca https://blockwallets.io/llms-full.txt untuk detailnya.

## Baca dokumentasi dulu; jangan menebak API dari ingatan
- Dokumentasi integrasi lengkap (Markdown): https://blockwallets.io/llms-full.txt
- Aturan integrasi dan kesalahan umum: https://blockwallets.io/agents.md
- Jika situs sudah memakai Cryptomus, NOWPayments, atau Coinbase Commerce, alihkan ke API kompatibel yang sesuai alih-alih menulis ulang: https://blockwallets.io/docs/migrate.md?lang=en
- Jika kamu tidak bisa membuka tautan, beri tahu saya dan saya akan menempelkan isinya.

## Poin penting (tempat integrasi biasanya salah)
1. Setiap endpoint adalah POST + JSON di https://blockwallets.io. Header: merchant = UUID merchant, sign = md5(base64(request body) + API key). Tandatangani string JSON persis seperti yang dikirim; jangan serialisasi ulang setelah menandatangani.
2. Buat tagihan dengan POST /v1/payment. Wajib: amount (string dengan maksimal dua desimal, mis. "42.00"), currency ("USD"), order_id (nomor pesanan saya: huruf, angka, - dan _, hingga 100 karakter). Sertakan juga url_callback (URL webhook) dan url_success (tujuan pelanggan setelah membayar). Arahkan pelanggan ke result.url.
3. Memanggil lagi dengan order_id yang sama mengembalikan tagihan yang sama, jadi mengulang itu aman dan tidak pernah membuat tagihan kedua.
4. Tanda tangan webhook wajib diverifikasi: parse JSON webhook, buang field sign, encode ulang sisanya seperti json_encode PHP (ringkas, non-ASCII dipertahankan, / di-escape menjadi \/), lalu md5(base64(encoded) + API key) harus sama dengan sign. Lupa meng-escape / adalah kesalahan yang paling sering terjadi.
5. Tandai pesanan lunas hanya jika status adalah paid atau paid_over, dengan payment_amount_usd. Webhook yang sama bisa datang lebih dari sekali: hindari duplikat berdasarkan uuid + status. Balas dengan status 2xx setelah selesai ditangani.
6. Simpan merchant ID dan API key di variabel lingkungan (misalnya BW_MERCHANT, BW_API_KEY); jangan pernah menulisnya langsung di kode atau meng-commit-nya. Tambahkan dulu domain URL webhook di “Domain situs web” pada halaman “Developer › Integrasi & kunci” di dasbor.
7. Buat semuanya berfungsi dengan kredensial Test dulu (testnet, tanpa uang sungguhan); beralih ke Live hanya setelah saya konfirmasi.

## Setelah selesai, periksa tiap butir dan beri tahu saya hasilnya
- [ ] Buat tagihan uji dengan kredensial Test dan dapatkan tautan halaman pembayaran (result.url)
- [ ] Buka halaman pembayaran dan klik “Simulasikan pembayaran” → jumlah penuh
- [ ] Server saya menerima webhook dengan status paid dan tanda tangannya terverifikasi
- [ ] Pesanan yang sesuai ditandai lunas
- [ ] Webhook yang sama yang datang lagi (kirim ulang dari “Developer › Log webhook” di dasbor, atau POST /v1/payment/resend) tidak mengirim barang dua kali

Jika ada butir yang gagal, beri tahu saya di mana macetnya dan pesan error persisnya sebelum mengubah hal lain.
```

### Setelah AI selesai, periksa ini

**Arahkan ke halaman pembayaran**

1. Buat tagihan uji dengan kredensial Test dan dapatkan tautan halaman pembayaran (result.url)
2. Buka halaman pembayaran dan klik “Simulasikan pembayaran” → jumlah penuh
3. Server saya menerima webhook dengan status paid dan tanda tangannya terverifikasi
4. Pesanan yang sesuai ditandai lunas
5. Webhook yang sama yang datang lagi (kirim ulang dari “Developer › Log webhook” di dasbor, atau POST /v1/payment/resend) tidak mengirim barang dua kali

**Alamat setoran tetap per pengguna**

1. Buka alamat untuk pengguna uji dengan kredensial Test dan dapatkan alamat serta tautan halaman setoran
2. Kirim contoh webhook dengan POST /v1/test-webhook/wallet
3. Server saya menerima webhook dengan type wallet dan tanda tangannya terverifikasi
4. Saldo pengguna itu bertambah sebesar payment_amount_usd
5. Webhook yang sama yang datang lagi tidak mengkredit saldo dua kali

**Tautan pembayaran (tanpa kode)**

1. Tombol tampil benar di desktop dan di ponsel
2. Tombol membuka tautan pembayaran saya (pakai tautan yang dibuat di mode Test dulu)
3. Mengklik “Simulasikan pembayaran” di halaman pembayaran menampilkan pembayaran itu di “Pembayaran › Pembayaran masuk” pada dasbor

## Saat AI mentok.

- **Tanda tangan tidak pernah terverifikasi**: Tempel body webhook mentah ke [pemeriksa tanda tangan](https://blockwallets.io/docs/sign?lang=id). Ia menampilkan setiap langkah antara dan menandai perbedaan pertama; beri tahu AI Anda persis apa yang berbeda.
- **Sebuah endpoint mengembalikan error**: Tempel permintaan dan respons persis (termasuk message) kembali ke AI Anda. Saat tanda tangan salah, debug.body_base64 di respons 401 adalah teks yang kami tandatangani; minta AI membandingkannya dengan miliknya.
- **Tidak yakin di mana macetnya**: Minta AI menjalankan daftar periksa penerimaan dari butir pertama, satu per satu, dan melaporkan tiap hasilnya. “Developer › Log webhook” di dasbor menampilkan setiap permintaan webhook dan respons server Anda.

### Empat hal yang Anda awasi.

- **Beri AI hanya kredensial Test**: Merchant ID dan API key Test berjalan di testnet; walau bocor, tidak ada dana yang bisa dipindahkan.
- **Jauhkan API key Live dari obrolan**: Masukkan API key Live ke variabel lingkungan server Anda sendiri. Jangan pernah menempelkannya ke obrolan atau meng-commit-nya ke repositori.
- **Cadangkan sebelum AI mengedit**: Commit (git commit) atau salin file situs Anda sebelum AI mulai, agar bisa dikembalikan.
- **Bayar sendiri sekali sebelum live**: Setelah beralih ke Live, bayar sejumlah kecil uang sungguhan lewat “Coba satu pembayaran” di beranda dasbor dan periksa pesanan berstatus lunas serta saldo masuk.

## Satu file aturan untuk agen coding.

AGENTS.md berisi inti integrasi, kesalahan umum, dan daftar periksa penerimaan. Taruh di root proyek Anda: Codex dan Cursor membacanya otomatis, Claude Code mengimpornya dengan @AGENTS.md.

```sh
curl -fsSL https://blockwallets.io/agents.md -o AGENTS.md
echo '@AGENTS.md' >> CLAUDE.md
```

- [Aturan integrasi (AGENTS.md)](https://blockwallets.io/agents.md)
- [Ringkasan satu halaman](https://blockwallets.io/llms.txt)
- [Dokumentasi lengkap](https://blockwallets.io/llms-full.txt)
- [Halaman ini dalam Markdown](https://blockwallets.io/docs/ai.md?lang=id)
- [Dokumentasi dalam Markdown](https://blockwallets.io/docs.md?lang=id)
- [Server MCP](https://blockwallets.io/docs/mcp?lang=id)

## Pertanyaan, terjawab.

### Bisakah saya benar-benar berintegrasi dengan AI jika tidak bisa coding?

Untuk kebanyakan situs, bisa. AI menulis kode pembuatan tagihan dan tanda tangan dari dokumentasi; Anda memasukkan kredensial ke variabel lingkungan dan menjalankan daftar periksa penerimaan di mode uji. Jika Anda tidak mau kode sama sekali, pakai tautan pembayaran.

### Alat AI mana yang sebaiknya saya pakai?

Alat yang mengedit proyek Anda dan menjalankan perintah paling mudah: Claude Code, Codex, atau Cursor. ChatGPT atau Claude di web juga bisa, tetapi Anda sendiri yang menempelkan kode ke situs.

### Haruskah saya memberi API key saya ke AI?

Hanya kredensial Test, dan di file lingkungan, bukan di obrolan. Taruh API key Live di server Anda sendiri.

### Tanda tangan webhook tidak pernah terverifikasi. Lalu bagaimana?

Buang sign, encode ulang sisanya seperti json_encode PHP dan escape / menjadi \/. Tempel body webhook mentah ke /docs/sign untuk membandingkan tiap langkah, lalu beri tahu AI apa yang berbeda.

### AI bilang sudah selesai. Bagaimana memeriksanya?

Jalankan daftar periksa penerimaan: buat tagihan uji, simulasikan pembayaran, lihat webhook terverifikasi, lihat pesanan ditandai lunas, dan kirim ulang webhook yang sama untuk memastikan tidak ada yang terkirim dua kali. Bayar sejumlah kecil di Live sebelum benar-benar live.