Thanawat Wongchai

Posted on Apr 23 • Originally published at apidog.com

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

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

ทดลองใช้ Apidog วันนี้

คู่มือนี้จะอธิบายภาพรวมทั้งหมดสำหรับนักพัฒนา: การสร้างบัญชี, สภาพแวดล้อม 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

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

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

สร้างบัญชีที่ console.circle.com
สภาพแวดล้อมมีทั้ง Sandbox (ใช้ฟรี) และ Production (ต้องผ่าน KYB)
สร้าง API key ที่ Developers → API Keys
- Sandbox: TEST_API_KEY:<id>:<secret>
- Production: LIVE_API_KEY:<id>:<secret>

ตัวอย่างการส่ง 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 (hex string 32 bytes) ผ่านแดชบอร์ด
ทุกคำขอ write ต้องสร้าง entitySecretCiphertext ใหม่ (เข้ารหัสด้วย RSA public key ของ Circle)
SDK จะช่วยหมุนเวียน ciphertext อัตโนมัติ

ติดตั้ง Node SDK:

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

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

สร้าง Wallet Set และ Wallet

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, blockchain
เติม 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" } },
});

ติดตามสถานะธุรกรรมด้วย 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 ด้วย public key (ดึงจาก /v1/encryption/public)
เช็คสถานะ payment: 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 โดยขั้นตอนคือ:

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

ผลลัพธ์คือ USDC ดั้งเดิมบนเชนปลายทาง ไม่มีโทเค็น Wrapped หรือความเสี่ยง Bridge

Webhooks และ Idempotency

สมัครรับ Webhook endpoint ได้ที่ /v1/notifications/subscriptions
Webhook ทุกตัวมีลายเซ็น ECDSA (public key ที่ /v1/notifications/publicKey/get)
ตรวจสอบ header X-Circle-Signature ทุกครั้งก่อนเชื่อถือ payload
ทุก endpoint ที่เปลี่ยนแปลงข้อมูลต้องส่ง header Idempotency-Key (UUID v4)
การ retry ด้วย key เดิมจะได้ response เดิม ไม่สร้างรายการซ้ำ

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

401 Unauthorized: Bearer token ผิด/ขาด, environment ไม่ตรง
400 invalid_entity_secret_ciphertext: ciphertext ซ้ำหรือ public key ไม่อัปเดต สร้างใหม่เสมอ
429 Too Many Requests: Sandbox ~10 req/s/endpoint, Production scaling ตามใช้งาน ใช้ exponential backoff
insufficient_funds: กระเป๋า/บัตรไม่มีเงินพอ

อ่านเพิ่มเติม: API สำหรับการออกบัตรที่ดีที่สุด

ราคา Circle API

Sandbox ฟรี
Production:
- Circle Mint ฟรีสำหรับลูกค้าสถาบันที่ผ่านเกณฑ์
- Circle Payments: คิดค่าธรรมเนียมต่อธุรกรรม (โดยทั่วไป 2.9% + $0.30)
- Wire/ACH มีค่าธรรมเนียมไม่กี่ดอลลาร์
- W3S คิดเป็นรายกระเป๋าและธุรกรรม (สอบถามฝ่ายขาย)
- CCTP ฟรี (จ่ายเฉพาะ gas chain เท่านั้น)

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

เนื่องจาก Circle ครอบคลุม REST, Webhook, และ Smart Contract การใช้ Postman เพียงอย่างเดียวไม่ครอบคลุม Apidog ช่วยให้คุณ:

นำเข้า OpenAPI spec ของ Circle ได้โดยตรง
จัดเก็บ Bearer token สำหรับแต่ละ environment แยกกัน
เขียนสคริปต์ทดสอบที่เชื่อมโยง payment, payout, webhook ใน Run เดียว
ใช้งาน Mock Server เพื่อทดสอบ Webhook handler ก่อนเชื่อมจริง

ดาวน์โหลด Apidog แล้วโหลด Circle spec จากพอร์ทัล developer

ใช้ Mock Server ทดสอบ Webhook
สลับ environment ได้ทันที
สำหรับทีม สามารถแชร์ workspace และจัดการ entity secret ได้ปลอดภัย

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

ฉันจำเป็นต้องมี KYB เพื่อทดสอบ Circle API หรือไม่?

ไม่จำเป็น Sandbox ใช้ได้ฟรีสำหรับทุกอีเมล ต้องผ่าน KYB เฉพาะ Production เท่านั้น (Sandbox มี faucet สำหรับ USDC ทุกเชน)

Circle Mint กับ Circle Wallets แตกต่างกันอย่างไร?

Mint คือสำหรับสถาบัน รับ/แลก USDC ตรง Wallets คือโครงสร้างพื้นฐานสำหรับ end-user ส่วนใหญ่ใช้ Wallets, ฝั่งคลังใช้ Mint

วิธีใช้ MoonPay API สำหรับ merchant รายย่อย

CCTP หลีกเลี่ยงความเสี่ยงของ Bridge ได้อย่างไร?

USDC ดั้งเดิมถูกเผาบนต้นทางและสร้างใหม่บนปลายทาง มีการรับรองจาก Circle ไม่มี pool สภาพคล่องให้โจมตีแบบ bridge ปกติ

คุณต้องเชื่อถือ service attestation ของ Circle เท่านั้น

ฉันสามารถใช้ Circle Wallets โดยไม่ต้องเก็บ Private Key ได้หรือไม่?

ได้ W3S มี user-controlled wallets ใช้ MPC + PIN ผู้ใช้อนุมัติธุรกรรมเองผ่าน SDK Developer-controlled wallets ใช้ entity secret บน backend

Circle รองรับ Solana และเชนที่ไม่ใช่ EVM หรือไม่?

รองรับทั้ง Solana, Aptos, NEAR, และ EVM L2 หลายแห่ง CCTP v2 รองรับ Solana เต็มรูปแบบในปี 2024

ฉันจะหมุนเวียน entity secret อย่างปลอดภัยได้อย่างไร?

สร้าง secret ใหม่ และลงทะเบียนในแดชบอร์ด SDK รองรับการอ่าน secret หลายตัวจาก environment deploy แบบ rolling ได้

รัน ciphertext เก่า/ใหม่ควบคู่กันในช่วงสั้นๆ เพื่อความต่อเนื่อง

DEV Community