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.

Hướng dẫn này sẽ đi sâu vào toàn bộ giao diện dành cho nhà phát triển: tạo tài khoản, môi trường thử nghiệm (sandbox) so với môi trường sản xuất (production), xác thực Bearer token, các điểm cuối thanh toán và chi trả, Ví Circle (Dịch vụ Web3), Giao thức chuyển chuỗi chéo (CCTP), mật mã bí mật thực thể cho Ví do nhà phát triển kiểm soát, webhook, tính bất biến (idempotency) và tuân thủ KYB. Bạn có thể mong đợi các đoạn mã curl và Node mà bạn có thể dán vào terminal của mình. Đọc thêm: hướng dẫn của chúng tôi về API chuyển đổi tiền pháp định sang tiền điện tử và ngược lại tốt nhất so sánh Circle với các đối thủ cạnh tranh gần nhất.

💡

Bạn cũng sẽ cần một API client có thể sử dụng cả REST và Web3 một cách trôi chảy khi bạn tạo mẫu. Apidog xử lý xác thực Bearer của Circle, chuyển đổi môi trường và phát lại webhook trong một không gian làm việc duy nhất, giúp bạn có thể kiểm tra môi trường thử nghiệm và sản xuất song song mà không cần viết lại bộ sưu tập của mình.

nút

TL;DR

API của Circle là một tập hợp các dịch vụ: Thanh toán Circle (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í có thể lập trình) và CCTP (ghi-và-đúc USDC trên các chuỗi chéo gốc).
Xác thực bằng Bearer token; khóa sandbox bắt đầu bằng TEST_API_KEY: và 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 một mật mã bí mật thực thể (mã hóa RSA, tạo lại theo mỗi yêu cầu) cho tất cả các thao tác ghi.
CCTP di chuyển USDC gốc qua Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana và nhiều blockchain khác thông qua quá trình ghi-và-đúc được chứng thực.
Cần có sự chấp thuận KYB cho môi trường sản xuất. Môi trường thử nghiệm (Sandbox) mở cho bất kỳ nhà phát triển nào.
Sử dụng khóa bất biến (idempotency keys) trên mọi yêu cầu thay đổi và xác minh chữ ký webhook bằng khóa công khai từ /notifications/publicKey/get.

API của Circle là gì?

Circle là một công ty thanh toán được quản lý chuyên phát hành USDC và vận hành các cơ sở hạ tầng giúp nó được neo giá với đồng đô la Mỹ. API của Circle cung cấp bốn dòng sản phẩm mà bạn có thể kết hợp:

API thanh toán Circle chấp nhận thẻ, ACH, SEPA và chuyển khoản ngân hàng, sau đó thanh toán kết quả dưới dạng USDC vào ví của người bán.
API Chi trả Circle gửi chuyển khoản ngân hàng hoặc ACH từ số dư USDC của bạn đến bất kỳ tài khoản ngân hàng nào bạn đã đăng ký làm người thụ hưởng.
Ví Circle (W3S) tạo các ví lưu ký hoặc ví do nhà phát triển kiểm soát trên nhiều chuỗi, ký giao dịch và xử lý phí gas.
CCTP đốt USDC trên chuỗi nguồn và đúc USDC tương đương trên chuỗi đích, vì vậy bạn nhận được tài sản gốc, không phải token được cầu nối.

Nếu bạn đang so sánh Circle với cơ sở hạ tầng Web3 đa năng, hãy đọc phân tích của chúng tôi về API ví tiền điện tử tốt nhất và hướng dẫn cách sử dụng API Alchemy để xem mỗi công cụ phù hợp ở đâu.

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

Tạo tài khoản tại console.circle.com. Bảng điều khiển cung cấp cho bạn hai môi trường: thử nghiệm (sandbox) và sản xuất (production). Sandbox miễn phí và tự phục vụ; môi trường sản xuất yêu cầu phê duyệt Xác minh doanh nghiệp (KYB), quá trình này mất vài ngày làm việc và cần các tài liệu thành lập, thông tin chủ sở hữu thực và một tài khoản cấp vốn.

Tạo khóa API trong mục Developers → API Keys. Định dạng khóa là TEST_API_KEY:<id>:<secret> trong môi trường thử nghiệm hoặc LIVE_API_KEY:<id>:<secret> trong môi trường sản xuất. Truyền nó dưới dạng Bearer token:

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

URL cơ sở:

Môi trường thử nghiệm: https://api-sandbox.circle.com
Môi trường sản xuất: https://api.circle.com

Đối với Ví do nhà phát triển kiểm soát trong W3S, bạn cũng cần một entity secret (bí mật thực thể): một chuỗi hex 32 byte mà bạn tạo một lần và đăng ký qua bảng điều khiển. Mọi lệnh gọi ghi phải bao gồm một entitySecretCiphertext mới, đó là bí mật thực thể được mã hóa bằng khóa công khai RSA của Circle. Node SDK tự động tạo lại nó; nếu bạn tự tạo, hãy xoay vòng mật mã trong mỗi yêu cầu vì Circle sẽ từ chối các giá trị đã được sử dụng lại.

Cài đặt Node SDK:

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

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

Tạo một bộ ví và ví

Các ví trong W3S nằm trong một bộ ví (một nhóm chia sẻ một khóa gốc HD). Tạo bộ ví trước, sau đó tạo các ví bên trong nó.

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ề một id, một address và blockchain mà nó đang hoạt động. Nạp tiền USDC testnet từ vòi Circle để tiếp tục.

Chuyển USDC từ ví do nhà phát triển 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" } },
});

Phản hồi trả về một id giao dịch mà bạn có thể truy vấn qua GET /v1/w3s/transactions/{id} hoặc lắng nghe qua webhook.

Chấp nhận thanh toán bằng thẻ và thanh toán bằng 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 được mã hóa PGP bằng khóa công khai của Circle (lấy từ /v1/encryption/public). Phản hồi trả về một id thanh toán sẽ chuyển qua các trạng thái pending → confirmed → paid.

Gửi chi trả qua chuyển khoản ngân hàng hoặc 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à một giao thức hợp đồng thông minh, không phải điểm cuối REST, vì vậy bạn kết hợp việc đốt trên chuỗi với dịch vụ chứng thực của Circle:

Gọi depositForBurn trên hợp đồng TokenMessenger trên chuỗi nguồn.
Truy vấn https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} cho đến khi status: "complete" và bạn nhận được một chuỗi hex attestation.
Gọi receiveMessage trên hợp đồng MessageTransmitter trên chuỗi đích với các byte thông báo và chứng thực.

Bạn sẽ có được USDC gốc trên chuỗi đích, được đúc ra từ không khí dựa trên một giao dịch đốt có thể kiểm chứng. Không có token được gói, không có rủi ro thanh khoản cầu nối.

Webhooks và tính bất biến

Circle gửi các sự kiện POST (payments, payouts, transfers, chargebacks) đến bất kỳ điểm cuối HTTPS nào bạn đăng ký qua /v1/notifications/subscriptions. Mọi webhook đều được ký bằng khóa ECDSA; lấy khóa công khai từ /v1/notifications/publicKey/get và xác minh tiêu đề X-Circle-Signature trước khi tin cậy dữ liệu tải.

Mọi điểm cuối thay đổi đều yêu cầu tiêu đề Idempotency-Key (một UUID v4 là tiêu chuẩn). Việc thử lại một yêu cầu với cùng khóa sẽ trả về phản hồi gốc thay vì tạo ra một khoản thanh toán trùng lặp. Điều này rất quan trọng: thẻ và chuyển khoản ngân hàng không chấp nhận việc gửi hai lần.

Lỗi thường gặp và giới hạn tỷ lệ

401 Unauthorized: Bearer token bị thiếu, định dạng sai hoặc môi trường không chính xác.
400 invalid_entity_secret_ciphertext: bạn đã sử dụng lại một mật mã hoặc mã hóa bằng khóa công khai đã cũ. Hãy tạo lại và thử lại.
429 Too Many Requests: môi trường thử nghiệm bị giới hạn khoảng 10 yêu cầu mỗi giây cho mỗi điểm cuối; giới hạn sản xuất tăng theo khối lượng. Hãy giảm tần suất truy cập một cách lũy thừa.
insufficient_funds: ví nguồn không đủ USDC, hoặc thẻ nguồn không vượt qua kiểm tra AVS/CVV.

Để có cái nhìn tổng quan hơn về cơ sở hạ tầng thẻ, tổng hợp API phát hành thẻ tốt nhất của chúng tôi bao gồm các nhà phát hành thẻ hoạt động tốt với các khoản chi trả của Circle.

Giá API của Circle

Môi trường thử nghiệm miễn phí. Trong môi trường sản xuất, Circle Mint không tính phí đúc hoặc đổi USDC cho các khách hàng tổ chức được phê duyệt với khối lượng đủ điều kiện. Circle Payments thu một tỷ lệ phần trăm cộng với phí cố định cho mỗi giao dịch thẻ (thường là 2.9% + 30 cent, được đàm phán theo quy mô). Các khoản chi trả qua chuyển khoản ngân hàng tại Hoa Kỳ có giá vài đô la mỗi giao dịch. Ví W3S được định giá theo từng ví và từng giao dịch; liên hệ bộ phận bán hàng để nhận báo giá sản xuất. Bản thân CCTP là miễn phí; bạn chỉ phải trả phí gas cho chuỗi nguồn và chuỗi đích.

Kiểm tra API của Circle với Apidog

Bề mặt API của Circle bao gồm REST, webhook được ký và các hợp đồng trên chuỗi, vì vậy một bộ sưu tập Postman duy nhất hiếm khi nắm bắt được toàn bộ quy trình. Apidog nhập trực tiếp đặc tả OpenAPI của Circle, lưu trữ Bearer token của môi trường thử nghiệm và sản xuất dưới dạng các môi trường riêng biệt, và cho phép bạn viết một tập lệnh kiểm thử liên kết thanh toán bằng thẻ, chi trả và xác minh webhook thành một lần chạy duy nhất.

Tải Apidog và tải đặc tả Circle từ cổng thông tin nhà phát triển của họ. Sử dụng máy chủ giả lập để mô phỏng việc gửi webhook trong khi bạn xây dựng trình xử lý xác minh, sau đó chuyển sang một điểm cuối thực khi bạn đã sẵn sàng. Đối với các nhóm, không gian làm việc chia sẻ giữ bí mật thực thể của bạn khỏi cuộc trò chuyện và quản lý phiên bản bộ sưu tập của bạn cùng với mã backend của bạn.

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

Tôi có cần KYB để kiểm tra API của Circle không?Không. Tài khoản sandbox mở cho bất kỳ ai có địa chỉ email. Bạn chỉ cần KYB để chuyển đô la thật trong môi trường sản xuất. Môi trường thử nghiệm đi kèm với các vòi (faucets) cung cấp USDC trên mọi chuỗi được hỗ trợ.

Sự khác biệt giữa Circle Mint và Ví Circle là gì?Circle Mint là nơi chuyển đổi tiền pháp định sang tiền điện tử dành cho tổ chức: bạn chuyển USD vào, bạn nhận được USDC ra (và ngược lại). Ví Circle / W3S là cơ sở hạ tầng lưu ký và giao dịch cho người dùng cuối của bạn. Hầu hết các ứng dụng tiêu dùng sử dụng Ví; các ứng dụng kho bạc sử dụng Mint trực tiếp. Hướng dẫn cách sử dụng API MoonPay của chúng tôi bao gồm một giải pháp thay thế chỉ dành cho bán lẻ nếu bạn không cần phát hành ở cấp độ Mint.

CCTP tránh rủi ro cầu nối như thế nào?USDC gốc được đốt trên chuỗi nguồn và được đúc mới trên chuỗi đích dựa trên một chứng thực đã ký từ Circle. Không có nhóm thanh khoản bị khóa mà một cuộc tấn công cầu nối có thể rút cạn. Bạn vẫn tin tưởng dịch vụ chứng thực của Circle, nhưng bạn không tin tưởng một tập hợp trình xác thực cầu nối của bên thứ ba.

Tôi có thể sử dụng Ví Circle mà không cần giữ khóa không?Có. Ví do người dùng kiểm soát trong W3S sử dụng MPC và xác thực dựa trên mã PIN, vì vậy người dùng cuối ủy quyền giao dịch qua SDK của Circle và bạn không bao giờ chạm vào khóa riêng. Ví do nhà phát triển kiểm soát đặt quyền ký vào backend của bạn thông qua entity secret.

Circle có hỗ trợ Solana và các chuỗi không phải EVM không?Có. W3S hỗ trợ Solana, Aptos, NEAR và một số EVM L2. CCTP v2 đã mở rộng hỗ trợ Solana vào năm 2024, vì vậy USDC gốc hiện di chuyển tự do giữa Solana và hệ sinh thái EVM.

Làm cách nào để xoay vòng entity secret một cách an toàn?Circle hỗ trợ xoay vòng entity secret thông qua bảng điều khiển. Tạo một bí mật mới, đăng ký nó và chạy song song cả mật mã cũ và mới trong một khoảng thời gian chuyển đổi ngắn. SDK đọc bất kỳ bí mật nào có trong biến môi trường của bạn, vì vậy việc triển khai cuốn chiếu sẽ xử lý nó một cách sạch sẽ.