Sebastian Petrus

Posted on Apr 23 • Originally published at apidog.com

Hướng Dẫn Sử Dụng Circle API: Thanh Toán USDC, Ví Điện Tử và Chi Trả

Circle phát hành USDC, stablecoin lớn thứ hai theo vốn hóa thị trường, và cung cấp một bộ API cho phép bạn chuyển đô la trên chuỗi mà không cần xây dựng cơ sở hạ tầng lưu ký, tuân thủ hoặc ngân hàng từ đầu. Nếu bạn từng muốn thanh toán một khoản chi trả trên thị trường trong vài phút, cho phép người dùng gửi tiền qua thẻ và rút tiền dưới dạng USDC, hoặc chuyển stablecoin qua tám blockchain chỉ với một lệnh gọi duy nhất, thì API của Circle là con đường ngắn nhất để thực hiện điều đó. Tài liệu chính thức có tại developers.circle.com, và tài liệu giới thiệu về USDC tại circle.com/en/usdc rất đáng đọc trước khi bạn bắt đầu thực hiện.

Thử Apidog ngay hôm nay

Hướng dẫn này tập trung vào các thao tác kỹ thuật cụ thể: tạo tài khoản, phân biệt môi trường thử nghiệm (sandbox) và sản xuất (production), xác thực Bearer token, điểm cuối thanh toán & chi trả, Ví Circle (Web3 Services), CCTP chuyển USDC đa chuỗi, quản lý entity secret cho ví do nhà phát triển kiểm soát, webhook, idempotency và quy trình tuân thủ KYB. Bạn sẽ tìm thấy các ví dụ curl và Node.js có thể sử dụng trực tiếp. Tham khảo thêm: bài so sánh API chuyển đổi tiền pháp định/tiền số tốt nhất để đối chiếu Circle với các nền tảng khác.

💡Bạn nên dùng một API client hỗ trợ cả REST và Web3 khi tạo mẫu. Apidog xử lý Bearer token, chuyển môi trường, phát lại webhook ngay trong một workspace duy nhất, giúp kiểm thử sandbox & production song song mà không cần chỉnh lại bộ sưu tập.

TL;DR

API của Circle gồm các dịch vụ: thanh toán (thẻ, ACH, chuyển khoản ngân hàng), Circle Mint (phát hành USDC cho tổ chức), Ví Circle/W3S (ví lập trình được), và CCTP (chuyển USDC đa chuỗi).
Xác thực bằng Bearer token; khóa sandbox bắt đầu bằng TEST_API_KEY:, khóa production bắt đầu bằng LIVE_API_KEY:.
Ví do nhà phát triển kiểm soát yêu cầu entity secret (chuỗi hex 32 byte, mã hóa RSA, tạo lại mỗi lần ghi).
CCTP chuyển USDC gốc qua Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana và các blockchain khác qua quy trình burn-mint.
Sản xuất yêu cầu duyệt KYB; sandbox mở cho mọi developer.
Luôn dùng Idempotency-Key với các request ghi; xác minh chữ ký webhook bằng public key lấy từ /notifications/publicKey/get.

API của Circle là gì?

Circle cung cấp các hạ tầng thanh toán, phát hành USDC và các sản phẩm API chính:

API thanh toán Circle: Nhận thẻ, ACH, SEPA, chuyển khoản ngân hàng; tiền về ví USDC của người bán.
API Chi trả Circle: Chuyển tiền từ số dư USDC về tài khoản ngân hàng/ACH đã đăng ký.
Ví Circle (W3S): Tạo ví lưu ký hoặc ví do developer kiểm soát trên nhiều chuỗi, ký giao dịch, xử lý gas.
CCTP: Đốt USDC trên chuỗi gốc, đúc USDC mới trên chuỗi đích, nhận đúng tài sản gốc.

Nếu bạn cần so sánh với các nền tảng Web3 khác, xem phân tích API ví tiền điện tử tốt nhất và hướng dẫn sử dụng Alchemy API.

Xác thực và Thiết lập

Đăng ký tài khoản tại console.circle.com.
Có hai môi trường: sandbox (thử nghiệm, miễn phí) và production (cần KYB, phê duyệt doanh nghiệp).
Tạo API Key trong mục Developers → API Keys.
- Định dạng:
  - Sandbox: TEST_API_KEY:<id>:<secret>
  - Production: LIVE_API_KEY:<id>:<secret>
Gửi Bearer token khi gọi API:

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

URL base API:

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

Ví do developer kiểm soát (W3S):

Cần tạo entity secret (chuỗi hex 32 byte), đăng ký qua dashboard.
Mỗi request ghi: cần entitySecretCiphertext, mã hóa entity secret bằng public key RSA của Circle.
Node SDK tự động xử lý mã hóa, hoặc tự làm thì phải tạo ciphertext mới mỗi lần (Circle sẽ từ chối nếu trùng).

Cài đặt Node SDK:

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

Điểm cuối cốt lõi

Tạo bộ ví và ví

Ví trong W3S thuộc về một "wallet set". Tạo wallet set trước, rồi sinh ví:

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);

Mỗi ví trả về id, address, blockchain. Nạp USDC testnet từ faucet Circle để dùng tiếp.

Chuyển USDC từ ví do developer kiểm soát

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

Kết quả trả về id giao dịch (truy vấn bằng GET /v1/w3s/transactions/{id} hoặc lắng nghe webhook).

Nhận thanh toán thẻ, chi trả 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": "..." }
  }'

Dữ liệu thẻ phải mã hóa PGP bằng public key của Circle (/v1/encryption/public).
Phản hồi trả về id payment; trạng thái chuyển từ pending → confirmed → paid.

Chi trả qua ngân hàng/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" }
  }'

Chuyển USDC đa chuỗi với CCTP

CCTP là giao thức smart contract, không phải REST endpoint.

Quy trình:

Gọi depositForBurn trên smart contract TokenMessenger ở chuỗi nguồn.
Poll https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} cho đến khi nhận status: "complete" và lấy chuỗi hex attestation.
Gọi receiveMessage trên smart contract MessageTransmitter ở chuỗi đích với message bytes & attestation.

Kết quả: USDC gốc được đúc mới trên chain đích, không phải wrapped token.

Webhooks & Idempotency

Circle gửi các sự kiện POST (payments, payouts, transfers, chargebacks) tới endpoint HTTPS bạn đăng ký qua /v1/notifications/subscriptions.
Webhook được ký ECDSA; lấy public key từ /v1/notifications/publicKey/get, xác minh header X-Circle-Signature.
Tất cả request thay đổi (POST, PATCH,...) phải có header Idempotency-Key (UUID v4). Gửi lại cùng key sẽ trả về kết quả cũ, không sinh giao dịch trùng.

Lỗi thường gặp & giới hạn rate

401 Unauthorized: Bearer token thiếu/sai/sai môi trường.
400 invalid_entity_secret_ciphertext: Ciphertext entity secret trùng hoặc mã hóa bằng public key cũ. Hãy tạo mới.
429 Too Many Requests: Sandbox giới hạn khoảng 10 request/giây/endpoint; production tăng theo volume. Giảm tần suất truy cập.
insufficient_funds: Không đủ USDC, hoặc thẻ không qua kiểm tra AVS/CVV.

Tổng hợp API phát hành thẻ tốt nhất nếu bạn cần tích hợp phát hành thẻ cùng Circle.

Giá API của Circle

Sandbox miễn phí.
Production: Circle Mint miễn phí đúc/đổi USDC cho tổ chức đủ điều kiện.
Circle Payments: tính phí theo phần trăm + phí cố định mỗi giao dịch thẻ (thường 2.9% + $0.30, có thể deal theo volume).
Chi trả qua chuyển khoản ngân hàng Mỹ: vài USD/giao dịch.
Ví W3S: tính phí theo số lượng ví và giao dịch.
CCTP miễn phí, chỉ chịu phí gas chuỗi.

Kiểm thử API Circle với Apidog

API Circle gồm REST, webhook ký, smart contract. Một workspace Postman đơn lẻ thường không đủ.

Apidog nhập OpenAPI của Circle, lưu Bearer token cho từng môi trường, cho phép bạn viết test script liên kết thanh toán, chi trả và xác minh webhook trong một lần chạy.

Tải Apidog và import đặc tả Circle từ portal developer. Sử dụng mock server mô phỏng webhook khi build handler, chuyển sang endpoint thật khi sẵn sàng. Với team, workspace chia sẻ giúp giữ entity secret an toàn và quản lý version cùng backend code.

Câu hỏi thường gặp

Tôi có cần KYB để kiểm thử API Circle?

Không. Sandbox mở cho bất cứ ai có email. Chỉ cần KYB khi chuyển USD thật ở production. Sandbox có faucet USDC mọi chain.

Khác biệt giữa Circle Mint và Ví Circle?

Circle Mint dành cho tổ chức nạp/rút USD ↔ USDC. Ví Circle/W3S là hạ tầng ví và giao dịch cho end-user. Consumer app dùng Ví, treasury app dùng Mint. Xem thêm hướng dẫn API MoonPay nếu bạn chỉ cần on-ramp bán lẻ.

CCTP tránh rủi ro cầu nối thế nào?

USDC gốc bị đốt trên chain nguồn và đúc mới trên chain đích dựa trên attestation ký bởi Circle. Không có pool locked, không lo bị hack bridge. Bạn chỉ tin attestation service của Circle, không phụ thuộc validator thứ ba.

Tôi dùng Ví Circle mà không giữ khóa được không?

Được. Ví do người dùng kiểm soát dùng MPC, xác thực bằng PIN, user tự duyệt giao dịch qua SDK Circle – backend không chạm private key. Ví do developer kiểm soát thì backend ký bằng entity secret.

Circle hỗ trợ Solana và chain không phải EVM không?

Có. W3S hỗ trợ Solana, Aptos, NEAR, một số EVM L2. CCTP v2 đã hỗ trợ Solana từ 2024, USDC gốc chuyển qua lại Solana/EVM dễ dàng.

Làm sao xoay vòng entity secret an toàn?

Circle hỗ trợ rotate entity secret qua dashboard. Tạo secret mới, đăng ký, chạy song song cả cũ và mới một thời gian. SDK đọc biến môi trường, nên triển khai rolling update là đủ.

DEV Community