Cara Menggunakan Circle API: Pembayaran, Dompet, dan Pencairan USDC

Circle menerbitkan USDC, stablecoin terbesar kedua berdasarkan kapitalisasi pasar, dan menyediakan serangkaian API yang memungkinkan Anda memindahkan dolar on-chain tanpa perlu membangun infrastruktur kustodian, kepatuhan, atau perbankan dari awal. Jika Anda pernah ingin menyelesaikan pembayaran marketplace dalam hitungan menit, membiarkan pengguna menyetor melalui kartu dan menarik sebagai USDC, atau memindahkan stablecoin di delapan blockchain hanya dengan satu panggilan, Circle API adalah jalur terpendek untuk mencapainya. Dokumen resmi tersedia di developers.circle.com, dan panduan dasar USDC di circle.com/en/usdc layak dibaca sebelum Anda mulai menggunakannya.

Panduan ini membahas seluruh area pengembangan: pembuatan akun, sandbox vs produksi, otentikasi token Bearer, endpoint pembayaran dan pencairan, Circle Wallets (Layanan Web3), Cross-Chain Transfer Protocol (CCTP), ciphertext rahasia entitas untuk Developer-Controlled Wallets, webhook, idempotensi, dan kepatuhan KYB. Harapkan cuplikan curl dan Node yang dapat Anda tempelkan ke terminal Anda. Bacaan terkait: panduan kami tentang API on-ramp off-ramp fiat terbaik membandingkan Circle dengan pesaing terdekatnya.

💡

Anda juga akan menginginkan klien API yang mahir dalam REST dan Web3 saat Anda membuat prototipe. Apidog menangani otentikasi Bearer Circle, peralihan lingkungan, dan pemutaran ulang webhook dalam satu ruang kerja, sehingga Anda dapat menguji sandbox dan produksi secara berdampingan tanpa menulis ulang koleksi Anda.

button

Singkatnya

Circle API adalah keluarga layanan: Circle Payments (kartu, ACH, transfer kawat), Circle Mint (penerbitan USDC institusional), Circle Wallets / W3S (dompet yang dapat diprogram), dan CCTP (pembakaran-dan-pencetakan USDC lintas rantai asli).
Otentikasi dengan token Bearer; kunci sandbox dimulai dengan TEST_API_KEY: dan kunci produksi dengan LIVE_API_KEY:.
Developer-Controlled Wallets memerlukan ciphertext rahasia entitas (dienkripsi RSA, dibuat ulang setiap permintaan) untuk semua operasi tulis.
CCTP memindahkan USDC asli di Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana, dan lainnya melalui pembakaran-pencetakan yang diakui.
Persetujuan KYB diperlukan untuk produksi. Sandbox terbuka untuk setiap pengembang.
Gunakan kunci idempotensi pada setiap permintaan yang mengubah data dan verifikasi tanda tangan webhook dengan kunci publik dari /notifications/publicKey/get.

Apa Itu Circle API?

Circle adalah perusahaan pembayaran yang diatur yang menerbitkan USDC dan mengoperasikan jalur yang menjaganya tetap terhubung dengan dolar AS. Circle API menyediakan empat lini produk yang dapat Anda campur dan cocokkan:

Circle Payments API menerima kartu, ACH, SEPA, dan transfer kawat, lalu menyelesaikan hasilnya sebagai USDC di dompet pedagang Anda.
Circle Payouts API mengirimkan transfer kawat atau ACH dari saldo USDC Anda ke rekening bank mana pun yang telah Anda daftarkan sebagai penerima.
Circle Wallets (W3S) membuat dompet kustodian atau yang dikontrol pengembang di berbagai rantai, menandatangani transaksi, dan menangani biaya gas.
CCTP membakar USDC di rantai sumber dan mencetak USDC yang setara di rantai tujuan, sehingga Anda mendapatkan aset asli, bukan wrapper yang dijembatani.

Jika Anda membandingkan Circle dengan infrastruktur Web3 tujuan umum, baca analisis kami tentang API dompet kripto terbaik dan panduan cara menggunakan Alchemy API untuk melihat di mana setiap alat cocok.

Otentikasi dan Pengaturan

Buat akun di console.circle.com. Konsol memberi Anda dua lingkungan: sandbox dan produksi. Sandbox gratis dan swalayan; produksi memerlukan persetujuan Know Your Business (KYB), yang memakan waktu beberapa hari kerja dan memerlukan dokumen pendirian perusahaan, informasi pemilik manfaat, dan akun pendanaan.

Hasilkan kunci API di Developers → API Keys. Format kunci adalah TEST_API_KEY:<id>:<secret> di sandbox atau LIVE_API_KEY:<id>:<secret> di produksi. Berikan sebagai token Bearer:

curl https://api-sandbox.circle.com/v1/ping \
  -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"

URL Dasar:

Sandbox: https://api-sandbox.circle.com
Produksi: https://api.circle.com

Untuk Developer-Controlled Wallets di W3S, Anda juga memerlukan rahasia entitas: string heksadesimal 32-byte yang Anda hasilkan sekali dan daftarkan melalui dasbor. Setiap panggilan tulis harus menyertakan entitySecretCiphertext baru, yaitu rahasia entitas yang dienkripsi dengan kunci publik RSA Circle. Node SDK meregenerasinya secara otomatis; jika Anda membuatnya sendiri, rotasi ciphertext pada setiap permintaan karena Circle menolak nilai yang digunakan kembali.

Instal Node SDK:

npm install @circle-fin/developer-controlled-wallets

Endpoint Utama

Buat set dompet dan dompet

Dompet di W3S berada di dalam set dompet (grup yang berbagi satu HD seed). Buat set terlebih dahulu, lalu buat dompet di dalamnya.

import { initiateDeveloperControlledWalletsClient } from "@circle-fin/developer-controlled-wallets";

const client = initiateDeveloperControlledWalletsClient({
  apiKey: process.env.CIRCLE_API_KEY,
  entitySecret: process.env.CIRCLE_ENTITY_SECRET,
});

const walletSet = await client.createWalletSet({ name: "payout-set-prod" });

const wallets = await client.createWallets({
  walletSetId: walletSet.data.walletSet.id,
  blockchains: ["ETH-SEPOLIA", "MATIC-AMOY"],
  count: 2,
});

console.log(wallets.data.wallets);

Setiap dompet mengembalikan id, address, dan blockchain tempat ia berada. Danai dengan USDC testnet dari faucet Circle untuk melanjutkannya.

Transfer USDC dari dompet yang dikendalikan pengembang

const transfer = await client.createTransaction({
  walletId: wallets.data.wallets[0].id,
  tokenId: "5797fbd6-3795-519d-84ca-ec4c5f80c3b1", // USDC di ETH-SEPOLIA
  destinationAddress: "0xRecipient...",
  amount: ["10.00"],
  fee: { type: "level", config: { feeLevel: "MEDIUM" } },
});

Respons mengembalikan id transaksi yang Anda polling melalui GET /v1/w3s/transactions/{id} atau dengarkan melalui webhook.

Terima pembayaran kartu dan selesaikan sebagai USDC

curl -X POST https://api-sandbox.circle.com/v1/payments \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "source": { "id": "card_4f1c...", "type": "card" },
    "amount": { "amount": "50.00", "currency": "USD" },
    "verification": "cvv",
    "description": "Order 1093",
    "encryptedData": "<PGP-encrypted card data>",
    "metadata": { "email": "buyer@example.com", "sessionId": "..." }
  }'

Data kartu harus dienkripsi PGP dengan kunci publik Circle (ambil dari /v1/encryption/public). Respons mengembalikan id pembayaran yang bergerak melalui pending → confirmed → paid.

Kirim pencairan melalui transfer kawat atau ACH

curl -X POST https://api-sandbox.circle.com/v1/payouts \
  -H "Authorization: Bearer $CIRCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "destination": { "type": "wire", "id": "beneficiary_abc" },
    "amount": { "amount": "500.00", "currency": "USD" },
    "metadata": { "beneficiaryEmail": "vendor@example.com" }
  }'

Pindahkan USDC lintas rantai dengan CCTP

CCTP adalah protokol smart-contract, bukan endpoint REST, jadi Anda menggabungkan pembakaran on-chain dengan layanan atestasi Circle:

Panggil depositForBurn pada kontrak TokenMessenger di rantai sumber.
Polling https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} sampai status: "complete" dan Anda menerima blob heksa attestation.
Panggil receiveMessage pada kontrak MessageTransmitter di rantai tujuan dengan byte pesan dan atestasi.

Anda akan mendapatkan USDC asli di rantai tujuan, dicetak dari udara tipis terhadap pembakaran yang dapat diverifikasi. Tidak ada token terbungkus, tidak ada risiko likuiditas jembatan.

Webhook dan Idempotensi

Circle POST peristiwa (payments, payouts, transfers, chargebacks) ke endpoint HTTPS mana pun yang Anda langganan melalui /v1/notifications/subscriptions. Setiap webhook ditandatangani dengan kunci ECDSA; ambil kunci publik dari /v1/notifications/publicKey/get dan verifikasi header X-Circle-Signature sebelum mempercayai payload.

Setiap endpoint yang mengubah data memerlukan header Idempotency-Key (UUID v4 adalah standar). Mengulang permintaan dengan kunci yang sama mengembalikan respons asli alih-alih membuat pembayaran duplikat. Ini penting: kartu dan transfer kawat tidak memaafkan pengiriman ganda.

Kesalahan Umum dan Batasan Tingkat Permintaan

401 Unauthorized: Token Bearer hilang, salah format, atau lingkungan salah.
400 invalid_entity_secret_ciphertext: Anda menggunakan kembali ciphertext atau mengenkripsi terhadap kunci publik yang usang. Buat ulang dan coba lagi.
429 Too Many Requests: sandbox dibatasi sekitar 10 permintaan per detik per endpoint; batas produksi disesuaikan dengan volume. Lakukan back off secara eksponensial.
insufficient_funds: dompet sumber tidak memiliki cukup USDC, atau kartu sumber gagal dalam pemeriksaan AVS/CVV.

Untuk pandangan yang lebih luas tentang infrastruktur kartu, rangkuman API penerbitan kartu terbaik kami mencakup penerbit yang cocok dengan pencairan Circle.

Harga Circle API

Sandbox gratis. Dalam produksi, Circle Mint tidak membebankan biaya untuk mencetak atau menukarkan USDC bagi pelanggan institusional yang disetujui dengan volume yang memenuhi syarat. Circle Payments mengambil persentase ditambah biaya tetap per transaksi kartu (biasanya 2.9% + 30 sen, dinegosiasikan dalam skala besar). Pencairan ke transfer kawat AS memerlukan beberapa dolar per transaksi. Dompet W3S dihargai per-dompet dan per-transaksi; hubungi bagian penjualan untuk penawaran produksi. CCTP itu sendiri gratis; Anda membayar biaya gas rantai sumber dan tujuan.

Menguji Circle API dengan Apidog

Cakupan Circle mencakup REST, webhook bertanda tangan, dan kontrak on-chain, sehingga satu koleksi Postman jarang menangkap seluruh alur. Apidog mengimpor spesifikasi OpenAPI Circle secara langsung, menyimpan token Bearer sandbox dan produksi sebagai lingkungan terpisah, dan memungkinkan Anda menulis skrip pengujian yang merangkai pembayaran kartu, pencairan, dan verifikasi webhook menjadi satu eksekusi.

Unduh Apidog dan muat spesifikasi Circle dari portal pengembang mereka. Gunakan server mock untuk mensimulasikan pengiriman webhook saat Anda membangun penangan verifikasi, lalu beralih ke endpoint nyata setelah Anda siap. Untuk tim, ruang kerja bersama menjaga rahasia entitas Anda dari obrolan dan membuat versi koleksi Anda bersama dengan kode backend Anda.

FAQ

Apakah saya memerlukan KYB untuk menguji Circle API?Tidak. Akun Sandbox terbuka untuk siapa saja dengan alamat email. Anda hanya memerlukan KYB untuk memindahkan uang sungguhan dalam produksi. Sandbox dilengkapi dengan faucet untuk USDC di setiap rantai yang didukung.

Apa perbedaan antara Circle Mint dan Circle Wallets?Circle Mint adalah on-ramp institusional: Anda mengirimkan USD, Anda mendapatkan USDC (dan sebaliknya). Circle Wallets / W3S adalah infrastruktur kustodi dan transaksi untuk pengguna akhir Anda. Sebagian besar aplikasi konsumen menggunakan Wallets di atasnya; aplikasi treasury menggunakan Mint secara langsung. Panduan cara menggunakan MoonPay API kami mencakup alternatif ritel-saja jika Anda tidak memerlukan penerbitan tingkat Mint.

Bagaimana CCTP menghindari risiko jembatan?USDC asli dibakar di rantai sumber dan dicetak ulang di rantai tujuan terhadap atestasi yang ditandatangani dari Circle. Tidak ada kumpulan likuiditas terkunci yang dapat dikuras oleh eksploitasi jembatan. Anda masih mempercayai layanan atestasi Circle, tetapi Anda tidak mempercayai set validator jembatan pihak ketiga.

Dapatkah saya menggunakan Circle Wallets tanpa memegang kunci?Ya. User-Controlled Wallets di W3S menggunakan otentikasi berbasis MPC dan PIN, sehingga pengguna akhir mengotorisasi transaksi melalui SDK Circle dan Anda tidak pernah menyentuh kunci privat. Developer-Controlled Wallets menempatkan otoritas penandatanganan di backend Anda melalui rahasia entitas.

Apakah Circle mendukung Solana dan rantai non-EVM?Ya. W3S mencakup Solana, Aptos, NEAR, dan beberapa EVM L2. CCTP v2 memperluas dukungan Solana pada tahun 2024, sehingga USDC asli sekarang bergerak bebas antara Solana dan ekosistem EVM.

Bagaimana cara merotasi rahasia entitas dengan aman?Circle mendukung rotasi rahasia entitas melalui dasbor. Hasilkan rahasia baru, daftarkan, dan jalankan ciphertext lama dan baru secara paralel untuk jendela cutover singkat. SDK membaca rahasia mana pun yang ada di variabel lingkungan Anda, sehingga deployment bergulir menanganinya dengan bersih.