วิธีใช้ Circle API: ชำระเงิน USDC, กระเป๋าเงินดิจิทัล และการจ่ายเงิน

Circle ออก USDC ซึ่งเป็น Stablecoin ที่ใหญ่เป็นอันดับสองตามมูลค่าตลาด และนำเสนอชุด API ที่ช่วยให้คุณสามารถโอนเงินดอลลาร์บนบล็อกเชนได้โดยไม่ต้องสร้างโครงสร้างพื้นฐานด้านการดูแลสินทรัพย์, การปฏิบัติตามกฎระเบียบ หรือธนาคารขึ้นมาใหม่ หากคุณเคยต้องการชำระเงินคืนจากการซื้อขายในตลาดในไม่กี่นาที, ให้ผู้ใช้ฝากเงินผ่านบัตรและถอนเป็น USDC, หรือย้าย Stablecoin ข้ามแปดบล็อกเชนด้วยการเรียกใช้เพียงครั้งเดียว Circle API คือเส้นทางที่สั้นที่สุด เอกสารอย่างเป็นทางการอยู่ที่ developers.circle.com และข้อมูลเบื้องต้นเกี่ยวกับ USDC ที่ circle.com/en/usdc ก็คุ้มค่าที่จะอ่านก่อนที่คุณจะเริ่มใช้งานจริง

คู่มือนี้จะอธิบายภาพรวมทั้งหมดสำหรับนักพัฒนา: การสร้างบัญชี, สภาพแวดล้อม Sandbox vs Production, การยืนยันตัวตนด้วย Bearer token, ปลายทางสำหรับชำระเงินและจ่ายเงิน, Circle Wallets (บริการ Web3), Cross-Chain Transfer Protocol (CCTP), entity secret ciphertext สำหรับ Developer-Controlled Wallets, Webhooks, Idempotency และการปฏิบัติตามข้อกำหนด KYB คุณจะได้พบกับตัวอย่างโค้ด curl และ Node ที่สามารถคัดลอกและวางลงในเทอร์มินัลของคุณได้ การอ่านเพิ่มเติม: คู่มือของเราเกี่ยวกับ API สำหรับการแปลง Fiat เป็น Crypto และ Crypto เป็น Fiat ที่ดีที่สุด ซึ่งเปรียบเทียบ Circle กับคู่แข่งที่ใกล้เคียงที่สุด

💡

คุณยังต้องการ API client ที่สามารถสื่อสารได้ทั้ง REST และ Web3 ได้อย่างคล่องแคล่วในขณะที่คุณสร้างต้นแบบ Apidog จัดการการยืนยันตัวตนด้วย Bearer auth ของ Circle, การสลับสภาพแวดล้อม และการเล่น Webhook ซ้ำในพื้นที่ทำงานเดียว คุณจึงสามารถทดสอบทั้ง Sandbox และ Production ควบคู่กันไปได้โดยไม่ต้องเขียน Collection ใหม่

ปุ่ม

สรุปโดยย่อ (TL;DR)

Circle API คือชุดบริการ: Circle Payments (บัตร, ACH, โอนเงิน), Circle Mint (การออก USDC สำหรับสถาบัน), Circle Wallets / W3S (กระเป๋าเงินที่ตั้งโปรแกรมได้) และ CCTP (การเผาและสร้าง USDC ข้ามเชนโดยตรง)
ยืนยันตัวตนด้วย Bearer token; คีย์ Sandbox ขึ้นต้นด้วย TEST_API_KEY: และคีย์ Production ขึ้นต้นด้วย LIVE_API_KEY:
Developer-Controlled Wallets ต้องการ entity secret ciphertext (เข้ารหัสด้วย RSA, สร้างใหม่ทุกครั้งที่เรียกใช้) สำหรับการดำเนินการเขียนทั้งหมด
CCTP โอน USDC ดั้งเดิมข้ามเครือข่าย Ethereum, Arbitrum, Base, Optimism, Polygon PoS, Avalanche, Solana และอื่นๆ ผ่านกระบวนการ burn-mint ที่ได้รับการรับรอง
การอนุมัติ KYB จำเป็นสำหรับ Production ส่วน Sandbox เปิดให้สำหรับนักพัฒนาทุกคน
ใช้คีย์ idempotency ในทุกคำขอที่เปลี่ยนแปลงข้อมูล และตรวจสอบลายเซ็น Webhook ด้วยคีย์สาธารณะจาก /notifications/publicKey/get

Circle API คืออะไร?

Circle เป็นบริษัทชำระเงินที่ได้รับการควบคุม ซึ่งออก USDC และดูแลระบบที่ทำให้ USDC ตรึงอยู่กับเงินดอลลาร์สหรัฐฯ Circle API นำเสนอผลิตภัณฑ์สี่กลุ่มที่คุณสามารถนำมาผสมผสานกันได้:

Circle Payments API รองรับบัตร, ACH, SEPA และการโอนเงิน แล้วจะทำการชำระยอดเป็น USDC ในกระเป๋าเงินร้านค้าของคุณ
Circle Payouts API ส่งการโอนเงินหรือ ACH จากยอด USDC ของคุณไปยังบัญชีธนาคารใดๆ ที่คุณได้เพิ่มเป็นผู้รับผลประโยชน์
Circle Wallets (W3S) สร้างกระเป๋าเงินแบบ Custodial หรือ Developer-controlled บนหลายบล็อกเชน, ลงนามธุรกรรม และจัดการค่าธรรมเนียม Gas
CCTP เผา USDC บนบล็อกเชนต้นทาง และสร้าง USDC ที่เทียบเท่ากันบนบล็อกเชนปลายทาง คุณจึงได้สินทรัพย์ดั้งเดิม ไม่ใช่โทเค็นที่ถูก Bridge

หากคุณกำลังเปรียบเทียบ Circle กับโครงสร้างพื้นฐาน Web3 ทั่วไป โปรดอ่านบทวิเคราะห์ของเราเกี่ยวกับ API กระเป๋าเงินคริปโตที่ดีที่สุด และคู่มือ วิธีใช้ Alchemy API เพื่อดูว่าแต่ละเครื่องมือเหมาะสมกับส่วนใด

การยืนยันตัวตนและการตั้งค่า

สร้างบัญชีที่ console.circle.com คอนโซลจะมอบสภาพแวดล้อมให้คุณสองแบบ: Sandbox และ Production โดย Sandbox นั้นฟรีและบริการตนเองได้ ส่วน Production ต้องการการอนุมัติ Know Your Business (KYB) ซึ่งใช้เวลาสองสามวันทำการและต้องใช้เอกสารการจดทะเบียน, ข้อมูลเจ้าของผลประโยชน์ และบัญชีสำหรับการระดมทุน

สร้าง API key ใต้ Developers → API Keys รูปแบบคีย์คือ TEST_API_KEY:<id>:<secret> ในสภาพแวดล้อม Sandbox หรือ LIVE_API_KEY:<id>:<secret> ในสภาพแวดล้อม Production ส่งเป็น Bearer token ดังนี้:

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

Base URL:

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

สำหรับ Developer-Controlled Wallets ใน W3S คุณยังต้องการ entity secret: ซึ่งเป็นสตริงเลขฐานสิบหกขนาด 32 ไบต์ที่คุณสร้างเพียงครั้งเดียวและลงทะเบียนผ่านแดชบอร์ด การเรียกใช้การเขียนทุกครั้งจะต้องมี entitySecretCiphertext ใหม่ ซึ่งเป็น entity secret ที่เข้ารหัสด้วยคีย์สาธารณะ RSA ของ Circle Node SDK จะสร้างใหม่โดยอัตโนมัติ หากคุณสร้างเอง ให้หมุนเวียน ciphertext ในทุกคำขอเนื่องจาก Circle จะปฏิเสธค่าที่นำกลับมาใช้ซ้ำ

ติดตั้ง Node SDK:

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

ปลายทางหลัก (Core Endpoints)

สร้าง Wallet Set และ Wallet

Wallets ใน W3S จะอยู่ใน wallet set (กลุ่มที่ใช้ HD seed เดียวกัน) สร้าง set ก่อน จากนั้นจึงสร้าง wallets ภายในนั้น

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

Wallet แต่ละอันจะส่งคืน id, address และบล็อกเชนที่ใช้งานอยู่ เติมเงินด้วย testnet USDC จาก Circle faucet เพื่อดำเนินการต่อ

โอน USDC จาก Developer-Controlled Wallet

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

การตอบกลับจะส่งคืน id ของธุรกรรมที่คุณสามารถตรวจสอบผ่าน GET /v1/w3s/transactions/{id} หรือรอรับผ่าน Webhook

รับชำระเงินด้วยบัตรและชำระเป็น 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": "..." }
  }'

ข้อมูลบัตรจะต้องถูกเข้ารหัสแบบ PGP ด้วยคีย์สาธารณะของ Circle (ดึงได้จาก /v1/encryption/public) การตอบกลับจะส่งคืน id การชำระเงินที่จะเปลี่ยนสถานะจาก pending → confirmed → paid

ส่งการจ่ายเงินผ่านการโอนเงิน (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" }
  }'

โอน USDC ข้ามเชนด้วย CCTP

CCTP เป็นโปรโตคอล Smart Contract ไม่ใช่ REST endpoint ดังนั้นคุณจึงต้องรวมการ burn บนเชนเข้ากับบริการรับรองของ Circle:

เรียกใช้ depositForBurn บนสัญญา TokenMessenger บนเชนต้นทาง
ตรวจสอบ https://iris-api-sandbox.circle.com/v1/messages/{sourceDomain}/{txHash} จนกระทั่ง status: "complete" และคุณได้รับ attestation ในรูปแบบ hex blob
เรียกใช้ receiveMessage บนสัญญา MessageTransmitter บนเชนปลายทางด้วย message bytes และ attestation

คุณจะได้รับ USDC ดั้งเดิมบนเชนปลายทาง ซึ่งถูกสร้างขึ้นมาใหม่จากกระบวนการเผาที่ตรวจสอบได้ ไม่มีโทเค็น Wrapped และไม่มีความเสี่ยงด้านสภาพคล่องของ Bridge

Webhooks และ Idempotency

Circle จะ POST เหตุการณ์ต่างๆ (payments, payouts, transfers, chargebacks) ไปยัง HTTPS endpoint ใดๆ ที่คุณสมัครสมาชิกผ่าน /v1/notifications/subscriptions Webhook ทุกรายการจะถูกลงนามด้วยคีย์ ECDSA; ดึงคีย์สาธารณะจาก /v1/notifications/publicKey/get และตรวจสอบเฮดเดอร์ X-Circle-Signature ก่อนที่จะเชื่อถือข้อมูล Payload

ทุกปลายทางที่มีการเปลี่ยนแปลงข้อมูล (mutating endpoint) ต้องการเฮดเดอร์ Idempotency-Key (โดยปกติใช้ UUID v4) การลองส่งคำขอซ้ำด้วยคีย์เดิมจะส่งคืนการตอบกลับเดิมแทนที่จะสร้างการชำระเงินซ้ำ นี่เป็นสิ่งสำคัญ: การชำระเงินด้วยบัตรและการโอนเงินไม่ยอมรับการส่งซ้ำ

ข้อผิดพลาดทั่วไปและขีดจำกัดการเรียกใช้ (Rate Limits)

401 Unauthorized: Bearer token หายไป, รูปแบบไม่ถูกต้อง หรือสภาพแวดล้อมไม่ตรงกัน
400 invalid_entity_secret_ciphertext: คุณใช้ ciphertext ซ้ำ หรือเข้ารหัสด้วยคีย์สาธารณะที่ล้าสมัย สร้างใหม่แล้วลองอีกครั้ง
429 Too Many Requests: Sandbox มีขีดจำกัดประมาณ 10 คำขอต่อวินาทีต่อปลายทาง; ขีดจำกัดของ Production จะปรับตามปริมาณงาน ลองถอยหลังและลองใหม่แบบทวีคูณ
insufficient_funds: กระเป๋าเงินต้นทางมี USDC ไม่เพียงพอ หรือบัตรต้นทางไม่ผ่านการตรวจสอบ AVS/CVV

สำหรับมุมมองที่กว้างขึ้นเกี่ยวกับโครงสร้างพื้นฐานบัตร คู่มือ API สำหรับการออกบัตรที่ดีที่สุด ของเราครอบคลุมผู้ให้บริการออกบัตรที่ทำงานร่วมกับการจ่ายเงินของ Circle ได้เป็นอย่างดี

ราคา Circle API

Sandbox ฟรี ใน Production, Circle Mint ไม่คิดค่าใช้จ่ายในการสร้างหรือแลก USDC สำหรับลูกค้าสถาบันที่ได้รับการอนุมัติและมีปริมาณการทำธุรกรรมที่เข้าเกณฑ์ Circle Payments คิดเป็นเปอร์เซ็นต์บวกค่าธรรมเนียมคงที่ต่อธุรกรรมบัตร (โดยทั่วไป 2.9% + 30 เซนต์ สามารถต่อรองได้เมื่อปริมาณเพิ่มขึ้น) การจ่ายเงินผ่านการโอนเงินในสหรัฐอเมริกาจะมีค่าใช้จ่ายไม่กี่ดอลลาร์ต่อธุรกรรม กระเป๋าเงิน W3S คิดราคาต่อกระเป๋าและต่อธุรกรรม; ติดต่อฝ่ายขายเพื่อขอใบเสนอราคาสำหรับ Production CCTP ฟรี; คุณจ่ายค่าธรรมเนียม Gas ของเชนต้นทางและปลายทาง

การทดสอบ Circle API ด้วย Apidog

บริการของ Circle ครอบคลุมทั้ง REST, Webhooks ที่ลงนาม และ Smart Contract บนบล็อกเชน ดังนั้น Collection ของ Postman เพียงชุดเดียวจึงไม่สามารถครอบคลุมการทำงานทั้งหมดได้ Apidog สามารถนำเข้า OpenAPI spec ของ Circle ได้โดยตรง, จัดเก็บ Bearer token สำหรับ Sandbox และ Production ในสภาพแวดล้อมที่แยกกัน และให้คุณเขียนสคริปต์ทดสอบที่เชื่อมโยงการชำระเงินด้วยบัตร, การจ่ายเงิน และการตรวจสอบ Webhook เข้าด้วยกันในการรันครั้งเดียว

ดาวน์โหลด Apidog และโหลด Circle spec จากพอร์ทัลนักพัฒนา ใช้ Mock Server เพื่อจำลองการส่ง Webhook ในขณะที่คุณสร้าง Verification Handler จากนั้นจึงเปลี่ยนไปใช้ Endpoint จริงเมื่อคุณพร้อม สำหรับทีม, พื้นที่ทำงานที่ใช้ร่วมกันจะช่วยให้ entity secret ของคุณปลอดภัยจากการสนทนา และจัดการเวอร์ชัน Collection ของคุณควบคู่ไปกับโค้ด Backend

คำถามที่พบบ่อย (FAQ)

ฉันจำเป็นต้องมี KYB เพื่อทดสอบ Circle API หรือไม่?ไม่จำเป็น บัญชี Sandbox เปิดให้ทุกคนที่มีอีเมล คุณต้องการ KYB เพียงเพื่อโอนเงินจริงใน Production Sandbox มาพร้อมกับ Faucets สำหรับ USDC บนทุกเชนที่รองรับ

Circle Mint กับ Circle Wallets แตกต่างกันอย่างไร?Circle Mint คือช่องทางสำหรับสถาบัน: คุณโอน USD เข้ามา คุณก็ได้ USDC ออกไป (และในทางกลับกัน) Circle Wallets / W3S คือโครงสร้างพื้นฐานสำหรับการดูแลสินทรัพย์และการทำธุรกรรมสำหรับผู้ใช้ปลายทางของคุณ แอปพลิเคชันสำหรับผู้บริโภคส่วนใหญ่ใช้ Wallets ส่วนแอปพลิเคชันด้านคลังใช้ Mint โดยตรง คู่มือ วิธีใช้ MoonPay API ของเราครอบคลุมทางเลือกสำหรับผู้ค้ารายย่อยเท่านั้น หากคุณไม่ต้องการการออกโทเค็นระดับ Mint

CCTP หลีกเลี่ยงความเสี่ยงของ Bridge ได้อย่างไร?USDC ดั้งเดิมจะถูกเผาบนเชนต้นทาง และสร้างขึ้นมาใหม่บนเชนปลายทางโดยมีการรับรองที่ลงนามจาก Circle ไม่มีกลุ่มสภาพคล่องที่ถูกล็อกซึ่งการโจมตี Bridge สามารถระบายออกไปได้ คุณยังคงต้องเชื่อถือบริการรับรองของ Circle แต่คุณไม่จำเป็นต้องเชื่อถือชุดผู้ตรวจสอบ Bridge ของบุคคลที่สาม

ฉันสามารถใช้ Circle Wallets โดยไม่ต้องเก็บ Private Key ได้หรือไม่?ได้ User-Controlled Wallets ใน W3S ใช้ MPC และการยืนยันตัวตนด้วย PIN ดังนั้นผู้ใช้ปลายทางจึงสามารถอนุมัติธุรกรรมผ่าน Circle SDK ได้และคุณก็ไม่ต้องยุ่งเกี่ยวกับ Private Key เลย Developer-Controlled Wallets จะมอบอำนาจการลงนามให้กับ Backend ของคุณผ่าน entity secret

Circle รองรับ Solana และเชนที่ไม่ใช่ EVM หรือไม่?ใช่ W3S ครอบคลุม Solana, Aptos, NEAR และ EVM L2 หลายแห่ง CCTP v2 ได้ขยายการรองรับ Solana ในปี 2024 ดังนั้น USDC ดั้งเดิมจึงสามารถโอนย้ายได้อย่างอิสระระหว่าง Solana และระบบนิเวศ EVM

ฉันจะหมุนเวียน entity secret อย่างปลอดภัยได้อย่างไร?Circle รองรับการหมุนเวียน entity secret ผ่านแดชบอร์ด สร้าง secret ใหม่, ลงทะเบียน และรัน ciphertext ทั้งเก่าและใหม่ควบคู่กันในช่วงเวลาสั้นๆ SDK จะอ่าน secret ใดก็ตามที่อยู่ในตัวแปรสภาพแวดล้อมของคุณ ดังนั้นการ Deploy แบบ Rolling จึงจัดการได้ง่าย