คู่มือเชื่อมต่อระบบสำหรับร้านค้า

1. ระบบนี้ทำอะไรให้ร้านค้า

ระบบจับคู่ "ลูกค้าที่กำลังฝาก" กับ "ลูกค้าที่กำลังถอน" ให้โอนเงินถึงกันโดยตรง (peer-to-peer) พร้อม escrow และตรวจสลิปอัตโนมัติ ผลคือ:

• บัญชีธนาคารของร้านถูกใช้น้อยที่สุด — เงินส่วนใหญ่วิ่งระหว่างลูกค้าด้วยกัน
• อัตโนมัติทั้งวงจร — จับคู่ ตรวจสลิป ปล่อยเครดิต แจ้งผลกลับ ไม่มีคนนั่งโอนมือ
• ปลอดภัยแบบ escrow — เครดิตถูกกันวงเงินไว้ก่อนเสมอ มีหน้าต่างโต้แย้ง (dispute)

เลือกรูปแบบการเชื่อมต่อได้ 2 แบบ (หรือผสมทั้งสอง)

2. สิ่งที่จะได้รับจากผู้ดูแลระบบ

3. เริ่มใช้ใน 5 นาที (โหมด sandbox — ไม่แตะเงินจริง)

ทุก endpoint รองรับ header x-sandbox: true สำหรับทดสอบ ไม่กระทบยอดเงินใด ๆ

# 1) สร้างรายการฝากทดสอบ
curl -X POST "{{BASE}}/api/deposit" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $API_KEY" \
  -H "x-sandbox: true" \
  -d '{
    "merchantUserId": "customer-001",
    "amount": "100.0000",
    "idempotencyKey": "test-dep-001"
  }'
# ตอบกลับ: { "id": 123, "uuid": "…", "status": "WAITING_PAYMENT", … }

# 2) เปิดหน้ารายการ (ลูกค้าเห็นบัญชีปลายทาง + ปุ่มแนบสลิป)
curl "{{BASE}}/api/checkout/<uuid>"

# 3) จำลองว่าลูกค้าโอนแล้ว (ต้องแนบ uuid เป็นหลักฐานการครอบครองรายการ)
curl -X POST "{{BASE}}/api/transaction/<id>/transferred" \
  -H "Content-Type: application/json" \
  -d '{ "uuid": "<uuid>" }'

# 4) เช็คสถานะ
curl "{{BASE}}/api/transaction/<id>"

4. เข้าใจ Gas และ Credit (สำคัญ — อ่านก่อนใช้เงินจริง)

• Gas = วงเงินค้ำสำหรับ "รับฝาก" — ทุก deposit ที่เปิดจะกันวง gas เท่ายอดไว้ก่อนจนกว่ารายการจบ
• Credit = ยอดเครดิตสะสมของร้าน ใช้รองรับ "การถอน" — ทุก withdraw จะกันวง credit เท่ายอดไว้ก่อน

ผู้ดูแลระบบจะเติม gas/credit เริ่มต้นให้ตามที่ตกลง — ถ้าเจอ Insufficient Gas Balance / Insufficient Credit Balance แปลว่าต้องเติมวงเงินก่อน

5. จัดการตั้งค่าเอง (รวมเปลี่ยนบัญชีธนาคารของร้าน)

5.1 login รับ session token

curl -X POST "{{BASE}}/api/auth/login" \
  -H "Content-Type: application/json" \
  -d '{ "username": "<ชื่อร้าน>", "password": "<API_KEY>" }'
# ตอบกลับ: { "token": "…", "role": "merchant", … }   (อายุ 24 ชม.)

5.2 แก้ไขตั้งค่า / เปลี่ยนบัญชีธนาคาร

ต้องส่งครบ 3 อย่าง: Bearer token (จาก 5.1) + X-API-Key + confirmApiKey (ยืนยัน key ซ้ำใน body — กันการแก้ค่าการเงินโดยไม่ตั้งใจ):

curl -X PATCH "{{BASE}}/api/merchant/settings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "webhookUrl": "https://your-system.example.com/webhooks/gateway",
    "bankName": "SCB",
    "bankAccountNo": "111-2-33333-4",
    "bankAccountName": "Your Shop Co., Ltd.",
    "confirmApiKey": "<API_KEY>"
  }'

ฟิลด์ที่ตั้งเองได้: webhookUrl, bankName, bankAccountNo (ระบบเข้ารหัสเก็บให้), bankAccountName, allowedIps, webhookEncryptionEnabled, autoVerifySlip, notificationEmail, webhookRetryInterval, checkoutLogoUrl, checkoutPrimaryColor

5.3 หมุน API key (แนะนำทำเป็นระยะ)

curl -X POST "{{BASE}}/api/merchant/rotate-api-key" \
  -H "X-API-Key: $API_KEY" \
  -d '{ "expiresHours": 24 }'
# ได้ key ใหม่ทันที; key เก่าใช้ต่อได้ตามชั่วโมงที่กำหนด (transition period)

6. Webhook — ระบบแจ้งผลกลับหาร้านแบบ real-time

ทุกครั้งที่รายการเปลี่ยนสถานะ เรา POST ไปที่ webhookUrl ของร้าน:

{
  "event": "transaction.completed",
  "data": {
    "id": 123, "type": "DEPOSIT", "amount": "100.0000",
    "status": "COMPLETED", "merchantId": 1, "userId": 45,
    "idempotencyKey": "…", "createdAt": "…"
  }
}

Event หลัก: transaction.waiting_payment, transaction.paid_unconfirmed, transaction.completed, transaction.cancelled, transaction.disputed, transaction.gas_settled, payout.required (ข้อ 8) และ confirmation.reminder — ระบบทักถามอัตโนมัติเมื่อฝั่งผู้ถอนยังไม่กดยืนยันเกิน 10 นาที (ตั้งค่าได้) ร้านใช้ event นี้เด้งถามลูกค้าว่า "ได้รับเงินแล้วหรือยัง?" โดย data.uuid พาลูกค้าไปหน้ารายการได้โดยตรง

6.1 ตรวจลายเซ็น (จำเป็น — ห้ามเชื่อ webhook ที่ไม่ผ่านการตรวจ)

Header X-Webhook-Signature = HMAC-SHA256 ของ raw body ด้วย WEBHOOK_SECRET:

import crypto from 'crypto';
import express from 'express';

const app = express();
app.post('/webhooks/gateway', express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}), (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.rawBody).digest('hex');
  const got = req.get('X-Webhook-Signature') || '';
  if (got.length !== expected.length ||
      !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.status(401).end();
  }
  res.status(200).end();          // ตอบ 200 ให้เร็ว แล้วค่อยประมวลผลต่อ
  handleEvent(req.body);          // ทำงานหนักแบบ async
});

• ตอบไม่ใช่ 2xx → ระบบ retry ให้อัตโนมัติ (สูงสุด 5 ครั้ง)
• endpoint ร้านล่มติดกันหลายครั้ง → circuit breaker หยุดยิงชั่วคราว + แจ้งเตือนร้าน
• ดู/สั่ง retry เองได้ที่ GET /api/merchant/webhook-logs และ POST /api/merchant/webhook-logs/:id/resend
• เปิด webhookEncryptionEnabled = payload เข้ารหัส AES-256-GCM อีกชั้น (ถอดด้วย key = SHA-256 ของ WEBHOOK_SECRET)

7. Mode B — เชื่อมเต็มรูปแบบ

7.1 ฝากเงิน (ลูกค้าเติมเครดิต)

POST /api/deposit   (X-API-Key)
body: { merchantUserId, amount, idempotencyKey, redirectUrl?, slipUrl? }

Flow: สร้างรายการ → ระบบจับคู่กับคนถอน (ปกติภายในวินาที) → ร้านพาลูกค้าไปหน้า GET /api/checkout/<uuid> (มีเลขบัญชีปลายทาง + ปุ่มแนบสลิป) → ลูกค้าโอน + กด "โอนแล้ว" → ระบบตรวจสลิป/รอผู้ถอนยืนยัน → webhook completed → ร้านเติมเครดิตให้ลูกค้าในระบบร้าน

• แนบ slipUrl (URL รูปหรือ data:base64) ตั้งแต่ตอนสร้าง → ตรวจผ่าน = settle ทันที (instant)
• ไม่มีคู่ภายในเวลาที่กำหนด → ระบบชี้ให้ลูกค้าโอนเข้า "บัญชีร้าน" แทนโดยอัตโนมัติ

7.2 ถอนเงิน (ลูกค้าเอาเงินออก)

POST /api/withdraw   (X-API-Key)
body: { merchantUserId, amount, idempotencyKey,
        bankName, bankAccountNo, bankAccountName }   ← บัญชีของลูกค้าผู้รับเงิน

Flow: ระบบจับคู่กับคนฝาก → คนฝากโอนเข้าบัญชีลูกค้าของร้านโดยตรง → สลิปผ่าน/ผู้ถอนกดยืนยัน/ครบหน้าต่างโต้แย้ง → webhook completed

7.3 การยืนยันรายการ (3 ชั้น อัตโนมัติทั้งหมด)

1. ผู้ถอนกดยืนยันรับเงิน — จบทันที ไม่ต้องใช้สลิป (POST /api/transaction/:id/release)
2. สลิปตรวจผ่าน — ระบบปล่อยให้เองไม่ต้องรอใครกด
3. เงียบจนครบหน้าต่างโต้แย้ง (ค่าเริ่มต้น 30 นาที) — ปล่อยอัตโนมัติ ฝั่งที่เงียบโดนหักคะแนนความน่าเชื่อถือ · มีปัญหาจริง → POST /api/transaction/:id/dispute เครดิตถูกล็อกไว้ให้ตรวจสอบ

8. Auto-payout — ให้ระบบออโต้ของร้านจ่ายแทนเมื่อไม่มีคู่ (opt-in)

สำหรับร้านที่มีระบบโอนเงินอัตโนมัติ: เมื่อ withdraw ไม่มีคู่ (หรือเหลือเศษ) ระบบจะยิง webhook payout.required บอกร้านว่า "โอน X บาท ไปบัญชีนี้":

{
  "event": "payout.required",
  "data": {
    "id": 456, "payoutRef": "b1f0-…", "payoutAmount": "300.0000",
    "bankName": "KBank", "bankAccountNo": "123-4-56789-0",
    "bankAccountName": "Somchai J."
  }
}

ระบบร้านโอนเงินแล้วยืนยันกลับ:

curl -X POST "{{BASE}}/api/transaction/456/payout-confirm" \
  -H "X-API-Key: $API_KEY" \
  -d '{ "payoutRef": "b1f0-…", "bankRef": "<เลขอ้างอิงโอนจากธนาคารร้าน>" }'

• จ่ายตาม payoutAmount เสมอ (อาจเป็นแค่เศษที่เหลือ ไม่ใช่ยอดเต็ม)
• payoutRef = idempotency key — dedupe ฝั่งร้านด้วยค่านี้ ยืนยันซ้ำไม่มีผลข้างเคียง
• เปิดใช้โดยแจ้งผู้ดูแลระบบ (ค่าเริ่มต้น: ปิด)

9. Mode A — เสริมระบบเดิม (try-match)

ก่อนร้านจะประมวลผลด้วยระบบตัวเอง ถามเราหนึ่งครั้ง:

# ฝั่งถอน: มีคนฝากรออยู่พอดีไหม?
curl -X POST "{{BASE}}/api/withdraw/try" \
  -H "X-API-Key: $API_KEY" \
  -d '{ "merchantUserId": "c1", "amount": "500.0000",
        "idempotencyKey": "try-w-001",
        "bankName": "KBank", "bankAccountNo": "…", "bankAccountName": "…" }'

# matched:true  → เราจัดการ P2P ให้ทั้งรายการ (ติดตามผลทาง webhook)
# matched:false → "ไม่มีอะไรถูกสร้างเลย" ร้านโอนเองด้วยระบบเดิมได้ทันที

# ฝั่งฝาก: มีคนถอนรอรับพอดีไหม?
curl -X POST "{{BASE}}/api/deposit/try" -H "X-API-Key: $API_KEY" \
  -d '{ "merchantUserId": "c2", "amount": "500.0000", "idempotencyKey": "try-d-001" }'
# matched:true → ได้ bankDetails ของผู้รับ ให้ลูกค้าโอนตรง
# matched:false → ให้ลูกค้าโอนเข้าบัญชีร้านตามระบบเดิม

10. ตัวเลือกความปลอดภัยเพิ่มเติม (แนะนำเปิดเมื่อขึ้นจริง)

11. Checklist ก่อนเปิดใช้จริง

• ทดสอบ sandbox ครบ: deposit → checkout → transferred → completed
• webhook endpoint ตรวจ HMAC แล้วตอบ 200 ภายใน 5 วินาที
• ตั้งบัญชีธนาคารร้านผ่าน settings แล้ว (ข้อ 5.2)
• จัดการ idempotencyKey ฝั่งร้าน: หนึ่งรายการ = หนึ่ง key ไม่ใช้ซ้ำข้ามยอด
• เก็บ API key ใน secret manager + เปิด IP allowlist
• ตกลงวงเงิน gas/credit เริ่มต้นกับผู้ดูแลระบบ
• (Mode B + auto-payout) ทดสอบ payout.required → โอน → payout-confirm ครบวง
• (Mode A) ทดสอบ try ทั้งกรณี matched:true และ matched:false

12. อ้างอิงย่อ

สถานะรายการ (lifecycle)

Endpoint ทั้งหมดที่ร้านใช้

Error ที่พบบ่อย