Payment API

Payment API ให้คุณสร้างเซสชันการชำระเงิน นำลูกค้าไปยังหน้า checkout ที่โฮสต์ไว้ และติดตามสถานะการชำระเงินได้

สร้างการชำระเงิน

{
  "state": 0,
  "result": {
    "uuid": "abc123-def456-...",
    "order_id": "ORDER-12345",
    "amount": "100.00",
    "currency": "USD",
    "amount_usd": "100.00",
    "exchange_rate": null,
    "url": "https://2328.io/pay/abc123-def456-...",
    "tg_deeplink": "https://t.me/my2328bot?start=pay_abc123-def456-...",
    "expires_at": "2026-01-11T21:00:00Z",
    "created_at": "2026-01-11T20:00:00Z",
    "payer_currency": "USDT",
    "payer_amount": "100.50",
    "network": "TRX-TRC20",
    "address": "TXYZabc123...",
    "payment_status": "check",
    "txid": null,
    "payment_amount": null,
    "qr": "data:image/png;base64,iVBORw0..."
  }
}

curl -X POST https://api.2328.io/api/v1/payment \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

การชำระเงินแบบโฮสต์, H2H, และจำนวนคริปโตที่แน่นอน

จุดเชื่อมต่อเดียวกันรองรับรูปแบบใบแจ้งหนี้สามแบบ เลือกแบบใดแบบหนึ่งอย่างตั้งใจ; อย่าผสมความหมายของจำนวนเงิน

การชำระเงินแบบโฮสต์ที่ผู้จ่ายเลือกได้

ส่ง amount, currency, order_id, และ url_callback แต่เว้น to_currency และ network การตอบกลับมี result.url; address, qr, และบางครั้งฟิลด์ของผู้จ่ายจะยังคง null จนกว่าผู้จ่ายจะเลือกทิศทางบนหน้าที่โฮสต์

{
  "amount": "125.00",
  "currency": "EUR",
  "order_id": "ORDER-2026-1042",
  "url_callback": "https://merchant.example/webhooks/2328",
  "url_return": "https://merchant.example/orders/ORDER-2026-1042"
}

ใบแจ้งหนี้ H2H แบบที่อยู่ตรง

ส่งทั้ง to_currency และ network 2328.io สร้างอินวอยซ์บนบล็อกเชนในระหว่างการเรียก API ดังนั้นการตอบสนองที่สำเร็จสามารถแสดงภายในหน้าเช็คเอาท์ของคุณโดยไม่ต้องเปลี่ยนเส้นทางลูกค้า

{
  "amount": "100.00",
  "currency": "USD",
  "to_currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1043",
  "url_callback": "https://merchant.example/webhooks/2328"
}

แสดงค่าต่าง ๆ เหล่านี้ตามที่ส่งกลับมาโดยตรง:

• payer_amount และ payer_currency — คำสั่งชำระเงิน;
• network และ address — จุดหมายปลายทางเดียวสำหรับอินวอยซ์นี้;
• qr — URI ของข้อมูลสำหรับที่อยู่เดียวกัน;
• expires_at — กำหนดเวลาสำหรับอินวอยซ์;
• url — สำรองที่โฮสต์ที่เป็นประโยชน์เมื่อตัวเช็คเอาท์แบบกำหนดเองไม่สามารถทำงานได้

ใบแจ้งหนี้สำหรับจำนวนคริปโตที่แน่นอน

วางสกุลเงินคริปโตใน currency เมื่อใบแจ้งหนี้นั้นเองมีหน่วยเป็นคริปโต:

{
  "amount": "25.000000",
  "currency": "USDT",
  "network": "TRX-TRC20",
  "order_id": "ORDER-2026-1044",
  "url_callback": "https://merchant.example/webhooks/2328"
}

มูลค่าคริปโตที่ร้องขอถูกเก็บไว้ใน payer_currency / payer_amount บริการยังสามารถรักษามูลค่าเป็น USD ภายในสำหรับการบัญชีและช่องอัตรา; อย่าแทนคำสั่งคริปโตที่แน่นอนด้วยมูลค่านั้น เก็บสตริงทศนิยมที่ส่งกลับ รวมถึงความแม่นยำปลายทศนิยม

สำหรับสกุลเงินดิจิทัลที่มีเครือข่ายรองรับเพียงหนึ่งเดียว เครือข่ายอาจถูกเลือกโดยอัตโนมัติ การระบุ network อย่างชัดเจนยังคงเป็นสิ่งที่แนะนำสำหรับการรวมแบบกำหนดได้ สำหรับสินทรัพย์หลายเครือข่าย เช่น สเตเบิลคอยน์ ให้ส่งมันเสมอ

Idempotency และการลองใหม่

order_id จะถูกจำกัดอยู่ที่โครงการพ่อค้า (merchant) ที่ผ่านการตรวจสอบสิทธิ์และทำหน้าที่เป็นคีย์ idempotency ของการสร้าง หากมีการชำระเงินอยู่แล้ว API จะส่งคืน session นั้นพร้อมกับ state: 0

อัลกอริทึมการสร้างที่แนะนำ:

1. แทรกความพยายามชำระเงินภายในท้องถิ่นและ order_id ที่ไม่ซ้ำกันของคุณในธุรกรรมฐานข้อมูลเดียว
2. ส่งคำขอ API ที่ลงนามแล้ว
3. บันทึก uuid ที่ส่งกลับและการตอบกลับทั้งหมด
4. หากผลลัพธ์ HTTP สูญหาย ให้ลองทำคำขอเดียวกันอีกครั้ง หรือสอบถาม /v1/payment/info ผ่าน order_id
5. อย่าสร้างคำสั่งซื้อท้องถิ่นที่สองเพียงเพราะคำขอข้างต้นหมดเวลา

กรณีขอบเขตการชำระเงิน

URL ที่ส่งกลับจากเบราว์เซอร์เป็นเพียงการนำทางเท่านั้น ลูกค้าสามารถเปิดมันโดยไม่ต้องจ่ายเงิน ปิดมันหลังจากชำระเงิน หรือเล่นซ้ำในภายหลัง ได้ก็ต่อเมื่อมีสถานะ API/webhook ที่ได้รับการยืนยันเท่านั้นที่จะสามารถชำระคำสั่งซื้อของร้านค้าได้

ข้อมูลการชำระเงิน

curl -X POST https://api.2328.io/api/v1/payment/info \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"

รายการการชำระเงิน

curl -X POST https://api.2328.io/api/v1/payment/list \
  -H "Content-Type: application/json" \
  -H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
  -H "project: YOUR_PROJECT_UUID" \
  -H "sign: YOUR_HMAC_SIGNATURE"