API kompatibel Coinbase Commerce

Endpoint charge, header X-CC-Api-Key, objek charge, dan webhook yang ditandatangani dengan X-CC-Webhook-Signature mengikuti dokumentasi Coinbase Commerce, sehingga SDK resminya berfungsi setelah mengubah satu baris. Coinbase Commerce berhenti melayani merchant di luar AS dan Singapura pada 2026-03-31. Datang dari tempat lain? Lihat ringkasan migrasi.

Di baliknya adalah tagihan blockwallets biasa: alamat penerima milik Anda, halaman pembayaran adalah kasir yang kami host, dan pembayaran baru dihitung setelah terkonfirmasi di chain dan diperiksa silang dengan node kedua. Di bawah ini: tiga langkah, lalu apa yang didukung setiap API dan apa bedanya dengan aslinya — parameter yang tidak kami implementasikan mengembalikan error, bukan diabaikan diam-diam.

Tiga langkah

1. Dapatkan akun merchant (ajukan di beranda) dan tambahkan domain Anda di “Domain situs web” pada “Developer › Integrasi & kunci” di dasbor. URL callback (ipn_callback_url) dan URL pengalihan (success_url / cancel_url / redirect_url) harus berada di domain itu atau di domain URL callback Anda — kunci yang bocor tidak bisa mengarahkan webhook ke tempat lain.
2. Buat kredensial kompatibel di dasbor merchant pada “Developer › Integrasi & kunci”, satu set untuk live dan satu untuk uji: NOWPayments mendapat API key + IPN secret, Coinbase Commerce mendapat API key + webhook shared secret. Semuanya ditampilkan sekali; kami hanya menyimpan hash / ciphertext.
3. Arahkan kode Anda ke base URL di bawah dan pakai kunci baru. Jalankan dulu di testnet dengan kredensial uji, lalu beralih ke live.

Coinbase Commerce

Semua SDK resmi menerima base URL — ubah satu baris (perhatikan / di akhir):

// Node(coinbase-commerce-node)
const { Client } = require("coinbase-commerce-node");
- Client.init(process.env.COINBASE_COMMERCE_API_KEY);
+ Client.init(process.env.COINBASE_COMMERCE_API_KEY, "https://blockwallets.io/coinbase/");

# Python(coinbase-commerce)
- client = Client(api_key=API_KEY)
+ client = Client(api_key=API_KEY, base_api_uri="https://blockwallets.io/coinbase/")

// PHP(coinbase/coinbase-commerce)
- ApiClient::init($apiKey);
+ ApiClient::init($apiKey, 'https://blockwallets.io/coinbase/');

curl -X POST https://blockwallets.io/coinbase/charges \
  -H "X-CC-Api-Key: $COINBASE_COMMERCE_API_KEY" -H "X-CC-Version: 2018-03-22" \
  -H "content-type: application/json" \
  -d '{"name":"Order #12345","description":"Pro plan","pricing_type":"fixed_price",
       "local_price":{"amount":"100.00","currency":"USD"},
       "redirect_url":"https://shop.example/success","cancel_url":"https://shop.example/cancel",
       "metadata":{"order_id":"12345"}}'
# → 201 {"data": {"id": "…", "code": "7C7V5ECK", "hosted_url": "https://blockwallets.io/pay/inv_…", "timeline": [{"status": "NEW", …}], …}}

Endpoint yang didukung

Tidak tersedia: /charges/:code/resolve (400 — tangani charge yang kurang bayar di dasbor), /checkouts, /events, /invoices (404).

Webhook

Webhook Coinbase berlaku di tingkat akun, begitu juga milik kami: dikirim ke URL callback yang diatur di dasbor Anda (charge yang dibuat dengan kredensial uji dikirim ke URL callback uji). Body-nya adalah {id, scheduled_for, attempt_number, event: {id, type, api_version, created_at, data}} milik Coinbase dengan charge lengkap di data; X-CC-Webhook-Signature = HMAC-SHA256(shared secret, body mentah), sehingga Webhook.verifyEventBody milik SDK berfungsi apa adanya. Pada percobaan ulang event.id tetap sama dan attempt_number naik — hindari duplikat berdasarkan event.id.

import crypto from "node:crypto";

// Same as the SDK's Webhook.verifySigHeader: HMAC-SHA256(shared secret, raw body)
function verifyWebhook(rawBody, sig, sharedSecret) {
  const hmac = crypto.createHmac("sha256", sharedSecret).update(rawBody, "utf8").digest("hex");
  return crypto.timingSafeEqual(Buffer.from(hmac), Buffer.from(sig || ""));
}
// verifyWebhook(rawBody, req.headers["x-cc-webhook-signature"], process.env.COINBASE_WEBHOOK_SECRET)
// or with the official SDK:Webhook.verifyEventBody(rawBody, signature, sharedSecret)

Saat melakukan kueri Anda juga akan melihat NEW (menunggu pembayaran) dan PENDING (pembayaran terlihat di chain, sedang dikonfirmasi). Penuhi pesanan pada charge:confirmed: kami tidak mengirim charge:created, charge:pending, charge:delayed, atau charge:resolved.

Perbedaan dari Coinbase Commerce

• pricing_type harus fixed_price; local_price.currency harus USD (USDC / USDT pada 1:1). no_price dan fiat lain mengembalikan 400.
• Alamat muncul setelah pelanggan memilih koin dan jaringan di kasir: addresses hanya berisi jaringan itu, pricing hanya local plus settlement setelah dipilih; tidak ada field exchange_rates, checkout, atau branding.
• metadata disimpan dan dikembalikan apa adanya (hingga 4 KB).
• Refund tidak muncul di timeline; lihat di dasbor.

Mode uji

Charge dan pembayaran yang dibuat dengan kredensial uji berjalan di testnet tiap chain dan webhook-nya ditandatangani dengan IPN secret / shared secret uji — sepenuhnya terpisah dari live: kunci uji tidak bisa melihat pembayaran live.

Sisanya (kasir, konfirmasi, jaringan dan minimum, refund) bekerja seperti di dokumentasi utama.