การตั้งราคาแบบเงินตรา

ตั้งราคา invoice เป็นเงินตรา แล้วให้ DuckyPay คำนวณจำนวน stablecoin ตามเรทสด — ลูกค้าเห็น ฿350 เชน settle เป็นโทเคนที่แน่นอน

สกุลเงินที่รองรับ#

นี่คือรายการทั้งหมด — โค้ดสกุลเงินอื่นจะถูกปฏิเสธด้วย 400 ก่อน จะคำนวณเรทใด ๆ:

// fiat: { currency: "EUR", amount: "25" } →
{
  "success": false,
  "data": null,
  "error": "Invalid enum value. Expected 'THB' | 'USD', received 'EUR'"
}

อยากตั้งราคาเป็นสกุลอื่นตอนนี้? แปลงเป็น USD ฝั่งคุณเองแล้วส่ง fiat: { currency: 'USD', … } หรือตั้งราคาเป็นหน่วยโทเคนตรง ๆ ด้วย amount — ดู Amounts: token or fiat

ตั้งราคาแบบเงินตราอย่างไร#

ส่ง fiat แทน amount เมื่อสร้าง charge amount และ fiat ใช้ร่วมกันไม่ได้ — ต้องมีอย่างใดอย่างหนึ่งพอดี

const charge = await duckypay.charges.create({
  chainId: 137,
  fiat: { currency: 'THB', amount: '350' },  // ฿350 — a decimal string
  // no `amount` — you provide EITHER fiat OR a token amount, never both
});

response มี amount โทเคนที่ DuckyPay คำนวณ พร้อมรายละเอียดเรทเต็มใน data.fiat เพื่อให้ไม่มีอะไรเกี่ยวกับราคาเป็นกล่องดำ:

{
  "amount": "10120000",          // ← authoritative: what the buyer actually pays (token, smallest unit)
  "fiat": {
    "currency": "THB",
    "amount": "350",             // your original price
    "marketRate": 35.10,         // fiat per 1 whole token at quote time
    "buffer": 0.50,              // subtracted from the rate in YOUR favor
    "effectiveRate": 34.60,      // marketRate − buffer → used to size the payment
    "tokenAmount": "10120000",   // = ceil(350 / 34.60 × 10^6)
    "source": "bitkub",
    "asOf": 1789550000
  }
}

amount โทเคนคือค่าที่ถือเป็นหลัก — เป็นสิ่งที่ลูกค้าจ่าย สิ่งที่ สัญญาแบ่ง และสิ่งที่ invoice.paid รายงาน ส่วน fiat เป็น metadata สำหรับแสดงผล; หน้า hosted checkout ใช้มันแสดง “฿350” ควบคู่จำนวนโทเคนและเรทที่ แน่นอน

คำนวณจำนวนโทเคนอย่างไร#

1. ดึงเรทตลาดสดของโทเคนใน invoice ในสกุลเงินของคุณ (เงินตราต่อ 1 โทเคนเต็ม)
2. หัก buffer ต่อสกุลออกจากเรท (ค่าเริ่มต้น THB: ฿0.50): effectiveRate = marketRate − buffer buffer เข้าข้างคุณ — รองรับการขยับของเรทระหว่างตอนคำนวณกับตอนจ่าย
3. คำนวณยอด โดยปัดขึ้นสู่หน่วยย่อยที่สุดของโทเคน: tokenAmount = ceil(fiatAmount ÷ effectiveRate × 10^decimals)

ทั้ง buffer และการปัดขึ้นเอนไปทางเดียวกัน: เมื่อเรทคลาดเคลื่อนเล็กน้อย คุณจะได้รับ มากกว่า ราคาเงินตราเล็กน้อย — ไม่มีทางได้น้อยกว่า

เรทมาจากไหน#

• THB — ตลาด THB สาธารณะของ Bitkub ก่อน (ราคาอ้างอิงที่คนไทยเทรดจริง) แล้ว CoinGecko เป็น fallback
• USD — CoinGecko.
• หากแหล่งเรทเข้าไม่ถึงชั่วคราว จะใช้เรทดีล่าสุดซ้ำในช่วงสั้น ๆ หากไม่มีเรทที่เชื่อ ได้เลย การสร้าง charge จะล้มเหลวด้วย 503 — DuckyPay ไม่แต่งเรทขึ้นเองเพื่อให้ มินต์ invoice ต่อ

กฎและกรณีขอบ#

• stablecoin เท่านั้น การตั้งราคาแบบเงินตราต้องใช้โทเคน stablecoin แบบ ERC-20 — การใช้ fiat คู่กับ token: "NATIVE" จะถูกปฏิเสธ
• charge หลายสินทรัพย์คำนวณเรทต่อโทเคน บน charge แบบ both/transfer ที่รับหลายโทเคน แต่ละโทเคนได้ยอดที่ คำนวณจากเงินตราของตัวเอง ลูกค้าจึงจ่ายราคาเทียบเท่ากันไม่ว่าจะเลือกสินทรัพย์ใด
• เรทถูกล็อกตอนสร้าง จำนวนโทเคนของ charge ไม่เปลี่ยนหลังมินต์; invoice ที่ค้างไม่จ่ายจะหมดอายุ (expiry) แล้วคุณมินต์ ใหม่ที่เรทปัจจุบัน