Walse

Posted on Apr 23 • Originally published at apidog.com

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

Circle menerbitkan USDC, stablecoin terbesar kedua berdasarkan kapitalisasi pasar, dan menyediakan rangkaian API yang memungkinkan Anda memindahkan dolar on-chain tanpa membangun infrastruktur kustodian, kepatuhan, atau perbankan dari nol. Jika Anda ingin menyelesaikan pembayaran marketplace dalam hitungan menit, menerima deposit kartu lalu menarik sebagai USDC, atau memindahkan stablecoin di delapan blockchain hanya dengan satu panggilan, Circle API adalah jalur tercepat untuk implementasi. Dokumentasi tersedia di developers.circle.com dan panduan dasar USDC di circle.com/en/usdc sebaiknya dibaca sebelum integrasi.

Coba Apidog hari ini

Panduan ini langsung ke praktik: mulai dari pembuatan akun, perbedaan sandbox vs produksi, otentikasi Bearer, endpoint pembayaran dan pencairan, Circle Wallets (Web3 Service), Cross-Chain Transfer Protocol (CCTP), penggunaan ciphertext rahasia entitas untuk Developer-Controlled Wallets, webhook, idempotensi, hingga persyaratan KYB. Disertakan juga cuplikan curl dan Node.js siap tempel. Untuk perbandingan, baca juga panduan API on-ramp/off-ramp fiat terbaik.

💡Saat prototyping, gunakan klien API seperti Apidog yang mendukung REST dan Web3. Apidog menangani otentikasi Bearer Circle, peralihan environment, serta pemutaran ulang webhook dalam satu workspace—uji sandbox dan produksi tanpa rewrite koleksi.

Singkatnya

Circle API terdiri dari: Circle Payments (kartu, ACH, transfer kawat), Circle Mint (penerbitan USDC institusional), Circle Wallets/W3S (dompet programmable), dan CCTP (protokol burn-mint USDC lintas rantai).
Autentikasi via token Bearer; kunci sandbox: TEST_API_KEY:, kunci produksi: LIVE_API_KEY:.
Developer-Controlled Wallets wajib menyertakan ciphertext rahasia entitas (dienkripsi RSA, dirotasi tiap request) untuk setiap operasi tulis.
CCTP memindahkan USDC asli di banyak chain (Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana, dll) via mekanisme burn-mint.
KYB wajib untuk produksi. Sandbox terbuka untuk semua developer.
Gunakan header Idempotency-Key untuk setiap request yang mengubah data dan verifikasi signature webhook via public key dari /notifications/publicKey/get.

Apa Itu Circle API?

Circle adalah perusahaan pembayaran teregulasi yang menerbitkan USDC dan menjaga konektivitasnya ke dolar AS. Circle API menyediakan empat lini produk utama yang bisa Anda kombinasikan sesuai kebutuhan:

Circle Payments API: terima pembayaran via kartu, ACH, SEPA, dan transfer kawat, hasil langsung ke USDC wallet merchant Anda.
Circle Payouts API: kirim transfer kawat atau ACH dari saldo USDC ke rekening bank terdaftar penerima.
Circle Wallets (W3S): buat dompet kustodian atau developer-controlled di berbagai chain, tanda tangani transaksi, dan kelola biaya gas.
CCTP: burn USDC di chain asal, mint USDC asli di chain tujuan—tanpa wrapped token.

Untuk perbandingan dengan solusi Web3 lain, cek juga analisis API dompet kripto terbaik dan panduan Alchemy API.

Otentikasi dan Pengaturan

Daftar akun di console.circle.com.
- Sandbox: gratis, self-service.
- Produksi: wajib KYB (upload dokumen perusahaan, data beneficial owner, dan akun funding; proses 2-5 hari kerja).
Generate API key di Developers → API Keys.
- Format:
  - Sandbox: TEST_API_KEY:<id>:<secret>
  - Produksi: LIVE_API_KEY:<id>:<secret>
- Contoh penggunaan:
```
 curl https://api-sandbox.circle.com/v1/ping \
   -H "Authorization: Bearer TEST_API_KEY:abc123:xyz789"
```

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

Developer-Controlled Wallets (W3S):
- Generate entity secret (32-byte hex), daftarkan via dashboard.
- Setiap operasi tulis: sertakan entitySecretCiphertext (rahasia entitas dienkripsi public key RSA Circle, rotate setiap request).
- Node SDK mengelola enkripsi & rotasi otomatis.

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

Endpoint Utama

Buat Wallet Set & Wallet

Dompet pada W3S berada dalam wallet set (grup wallet dengan HD seed sama). Langkah:

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 wallet mengembalikan id, address, dan chain-nya. Danai via faucet USDC testnet Circle.

Transfer USDC dari Developer-Controlled Wallet

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" } },
});

Response: id transaksi, polling via GET /v1/w3s/transactions/{id} atau dengarkan webhook.

Terima Pembayaran Kartu → 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 wajib di-enkripsi PGP dengan public key Circle (/v1/encryption/public). Payment id bergerak status: pending → confirmed → paid.

Kirim Payout via Wire/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" }
  }'

Transfer USDC Cross-chain via CCTP

CCTP berbasis kontrak smart contract, bukan endpoint REST:

Call depositForBurn di kontrak TokenMessenger chain asal.
Polling https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} sampai status: "complete" dan dapatkan blob hex attestation.
Call receiveMessage di kontrak MessageTransmitter chain tujuan dengan byte pesan & attestation.

USDC asli akan diterima di chain tujuan. Tidak ada wrapped token, tidak ada risiko jembatan.

Webhook & Idempotensi

Circle mengirim webhook (payments, payouts, transfers, chargebacks) ke endpoint HTTPS via /v1/notifications/subscriptions.
Tiap webhook ditandatangani ECDSA; ambil public key dari /v1/notifications/publicKey/get dan verifikasi header X-Circle-Signature sebelum proses payload.
Endpoint yang mengubah data wajib header Idempotency-Key (UUID v4). Ulangi dengan key sama → response sama, tanpa duplikasi pembayaran. Kritikal untuk pembayaran & wire transfer.

Error Umum & Rate Limit

401 Unauthorized: token Bearer hilang, format salah, atau environment keliru.
400 invalid_entity_secret_ciphertext: ciphertext reused/expired atau public key kadaluarsa. Buat baru.
429 Too Many Requests: sandbox ±10 req/detik/endpoint; produksi sesuai volume, gunakan exponential back-off.
insufficient_funds: saldo USDC tidak cukup, atau kartu gagal AVS/CVV.

Untuk referensi lain, lihat API penerbitan kartu terbaik.

Harga Circle API

Sandbox: gratis.
Produksi:
- Circle Mint: free mint & redeem USDC untuk institusi dengan volume eligible.
- Circle Payments: persentase + flat fee per transaksi kartu (umumnya 2.9% + $0.30, bisa negosiasi untuk volume besar).
- Payout wire transfer: fee beberapa dolar per transaksi.
- W3S: per-wallet & per-transaksi, minta penawaran ke sales.
- CCTP: gratis, hanya bayar gas chain asal & tujuan.

Uji Circle API dengan Apidog

Circle support REST, webhook bertanda tangan, dan smart contract. Koleksi Postman biasanya tak cukup. Apidog langsung mengimpor spesifikasi OpenAPI Circle, simpan token Bearer untuk sandbox/produksi sebagai environment terpisah, serta bisa chaining pembayaran, payout, dan testing webhook dalam satu eksekusi.

Unduh Apidog, lalu import spesifikasi Circle dari portal developer mereka. Gunakan mock server untuk simulasi webhook saat membangun verifikasi handler, lalu switch ke endpoint asli saat siap. Untuk tim, workspace bersama menjaga rahasia entitas dari kebocoran dan memudahkan versioning koleksi.

FAQ

Apakah perlu KYB untuk uji Circle API?

Tidak. Sandbox terbuka untuk siapa saja dengan email. KYB hanya untuk produksi (uang sungguhan). Sandbox tersedia faucet USDC di setiap chain.

Apa beda Circle Mint dan Circle Wallets?

Mint = on-ramp institusi: kirim USD, dapat USDC (dan sebaliknya). Wallets/W3S = infrastruktur dompet & transaksi end-user. App konsumen umumnya pakai Wallets; treasury/korporat pakai Mint. Alternatif retail-only: cek panduan MoonPay API.

Bagaimana CCTP menghindari risiko bridge?

USDC asli di-burn di chain asal & dicetak ulang di chain tujuan dengan attestation Circle (bukan kumpulan likuiditas). Tidak ada validator bridge pihak ketiga.

Bisa pakai Circle Wallets tanpa pegang kunci?

Bisa. User-Controlled Wallets (W3S) pakai otentikasi MPC+PIN, user authorize via SDK, Anda tidak pegang private key. Developer-Controlled Wallets: backend Anda yang pegang signing authority via entity secret.

Apakah Circle support Solana & non-EVM chain?

Ya. W3S support Solana, Aptos, NEAR, dan beberapa EVM L2. CCTP v2 (2024) memperluas Solana; USDC asli kini lintas Solana & EVM.

Bagaimana rotate entity secret dengan aman?

Lewat dashboard Circle: generate secret baru, daftarkan, jalankan ciphertext lama & baru paralel saat cutover singkat. SDK otomatis baca semua secret di environment variable, rolling deployment handled.

DEV Community