เข้าใจ P2P จากภาพและขั้นตอนสั้น ๆ

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

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

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

การเชื่อมต่อ API เดิมมี 2 แบบ (ไม่ใช่กติกาคำขอร้านค้าใหม่)

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

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

ส่ง x-sandbox: true ตอนสร้างรายการฝาก/ถอนทดสอบ แล้วใช้ ID ของรายการทดสอบนั้นต่อ header นี้ไม่ใช่โหมดปลอดภัยสำหรับทุก endpoint และห้ามใช้กับ ID ของรายการเงินจริง

# 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) เปิดในเบราว์เซอร์เพื่อดูบัญชีปลายทางและแนบสลิป
# {{BASE}}/payment.html?uuid=<uuid>
# API อ่านข้อมูล JSON: GET /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>" -H "X-API-Key: $API_KEY"

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

• คำขอร้านค้าใหม่บนเว็บ/LINE: สร้างฝากหรือถอนยังไม่พัก GAS เมื่อจับคู่จึงพักค่าธรรมเนียม และกรณีข้ามร้านพักยอดถอนพร้อมค่าธรรมเนียมของร้านผู้ถอน ต้องมี GAS ใช้ได้พอก่อนแสดงบัญชี
• เมื่อตรวจสลิปผ่าน: ลูกค้าร้าน A โอนให้ลูกค้าร้าน B → GAS ร้าน A เพิ่มตามยอดโอน และ GAS ร้าน B ลดเท่ากัน ค่าธรรมเนียมแยกตามยอดที่จับคู่สำเร็จ ร้านเดียวกันหักเฉพาะค่าธรรมเนียม
• ร้านรับหรือจ่ายเอง: ไม่คิดค่าธรรมเนียม P2P และไม่เปลี่ยน GAS จากยอดเงินต้น ส่วนถอนที่จับคู่ได้เพียงบางส่วนคิดค่าธรรมเนียมเฉพาะส่วนที่สำเร็จ
• ยกเลิกหรือหมดเวลายังไม่จ่าย: คืนยอดพักของคู่นั้นเต็มจำนวน ไม่หักค่าธรรมเนียม ฝากที่หมดเวลาก่อนมีบัญชีโอนจะปิดทันที รายการฝากใหม่จะลอง P2P ก่อน หากไม่มีคู่จะใช้บัญชีร้านทันทีเมื่อบัญชียังรับยอดได้
• รายการเดิมและ API เดิม: ใช้กติกาเดิมต่อจนจบ ได้แก่พัก GAS เท่ายอดฝาก และพักเครดิตเท่ายอดถอน ยอดเหล่านี้ไม่ใช่เงินของลูกค้าที่ถอนได้

เจ้าของเติมให้เอเยนต์ และเอเยนต์เติม Gas ให้ร้านค้า

1. เจ้าของ: เปิด เครือข่าย → เอเยนต์และเครือข่าย ที่หัวข้อ เติมเงินให้เอเยนต์ เลือกเอเยนต์ กรอกจำนวน PTS และหมายเหตุ ตรวจชื่อผู้รับกับยอดก่อน–หลัง แล้วกดยืนยันได้เลย ไม่ต้องรอเอเยนต์ส่งคำขอ
2. เอเยนต์: เปิด เครือข่าย → ร้านค้าของฉัน → เติม Gas เลือกร้านในสายและจำนวน ระบบหักกระเป๋าเอเยนต์เท่ากับ Gas ที่เพิ่มให้ร้าน ต้องมียอดกระเป๋าเพียงพอ
3. ถ้าหน้าเว็บยังไม่ได้รับคำตอบ ให้กด ตรวจรายการเติมเดิม / ลองอีกครั้ง ระบบใช้เลขรายการเดิมเพื่อไม่เพิ่มยอดซ้ำ แม้รีโหลดหน้าแล้ว อย่าสร้างรายการใหม่จากแท็บอื่นจนกว่าจะตรวจประวัติเดิม

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

ผู้ดูแลระบบจะเติม 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 "Authorization: Bearer $TOKEN" \
  -H "X-API-Key: $API_KEY" \
  -d '{ "expiresHours": 24 }'
# ได้ key ใหม่ทันที; key เก่าใช้ต่อได้ตามชั่วโมงที่กำหนด (transition period)

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

สำหรับร้านที่ตั้ง webhookUrl เมื่อรายการเปลี่ยนสถานะ เรา POST ไปที่ URL นั้น ร้านที่เว้นว่างดูสถานะผ่านเว็บ หรือผ่าน LINE เมื่อเชื่อมต่อและเปิดใช้งานแล้ว:

{
  "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; },
}), async (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();
  }
  try {
    // interface ตัวอย่าง: ใช้ฐานข้อมูล/คิวถาวรของร้าน และ dedupe งานซ้ำ
    await durableInbox.accept(req.body);
    return res.status(200).end(); // ตอบหลัง commit งานแล้วเท่านั้น
  } catch {
    return res.status(503).end(); // ให้ gateway ส่งซ้ำเมื่อบันทึกไม่ได้
  }
});

durableInbox เป็น interface ที่ร้านต้องทำด้วยที่เก็บงานถาวรและ worker ของร้าน ห้ามใช้คิวในหน่วยความจำหรือสั่งงานแล้วตอบก่อนบันทึก การเติม/คืนเครดิตต้อง dedupe พร้อม ledger ใน transaction เดียวกัน และตรวจร้าน ลูกค้า ประเภท ยอดเงินและรหัสรายการให้ตรง

แนะนำตรวจ X-Webhook-Signature-V2 ด้วย HMAC-SHA256 ของ v1\n<timestamp>\n<eventId>\n<sequence>\n<rawBody> จาก headers X-Webhook-Timestamp (Unix seconds), X-Webhook-Event-Id และ X-Webhook-Sequence จำกัดอายุ timestamp และบันทึก event ID/sequence เพื่อกันซ้ำ

• ตอบไม่ใช่ 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: สร้างรายการ → ระบบจับคู่กับคนถอน (ปกติภายในวินาที) → ร้านพาลูกค้าไปหน้า /payment.html?uuid=<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 การยืนยันรายการและหลักฐานการโอน

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

8. จ่ายยอดที่เหลือ — ร้านโอนเองหรือใช้ระบบอัตโนมัติ

เมื่อครบเวลารอจับคู่ ระบบบันทึกยอดส่วนที่ร้านต้องจ่าย และส่ง webhook payout.required ไปยังช่องทางที่ร้านเชื่อมไว้ พร้อมบัญชีผู้รับและยอดส่วนนี้ ตัวอย่างถอน 1,000 บาท หาก P2P จ่ายยืนยันแล้ว 600 บาท ร้านจ่ายต่อ 400 บาท:

• ร้านโอนเอง: ตรวจบัญชีและยอดในรายละเอียด โอนจริงแล้วแนบสลิป กด “ส่งสลิปเพื่อตรวจ”
• ระบบโอนอัตโนมัติ: ต้องเชื่อมระบบโอนและเปิดโหมดอัตโนมัติในระบบร้านค้า ระบบนั้นจึงส่งคำสั่งจ่ายและรอผลสำเร็จ
• โหมดรออนุมัติ: ผู้ดูแลอนุมัติให้ระบบโอนดำเนินการก่อน แล้วรอผลสำเร็จ
• ระหว่างรอผล: ตรวจรายการเดิมก่อน อย่าโอนซ้ำเพราะยังไม่มีรูปสลิปหรือคำตอบยืนยัน

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

ก่อนเปิด auto-payout ต้องทดสอบการส่งผลตรวจสลิปที่ gateway อ่านตรวจซ้ำได้ให้ครบ เมื่อโอนแล้วต้องตรวจสลิปและส่ง signed proof กลับ:

curl --fail-with-body -X POST "{{BASE}}/api/transaction/456/payout-confirm" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "payoutRef": "b1f0-…", "bankRef": "<เลขอ้างอิงธนาคาร>",
        "verificationId": "<UUID ผลตรวจสลิป>",
        "verificationExpiresAt": 1790000000000,
        "verificationSignature": "<HMAC-SHA256 hex>" }'

• จ่ายตาม payoutAmount เสมอ (อาจเป็นแค่เศษที่เหลือ ไม่ใช่ยอดเต็ม)
• payoutRef = idempotency key — dedupe ฝั่งร้านด้วยค่านี้ ยืนยันซ้ำไม่มีผลข้างเคียง
• ส่งเพียง bankRef ไม่ได้: API ร้านค้าจะตอบ 400 หากไม่มีหลักฐานตรวจสลิป
• verificationExpiresAt ใช้ Unix milliseconds ที่ยังไม่หมดอายุและไม่เกิน 5 นาทีข้างหน้า
• ตรวจ HTTP status และ payoutStatus: CONFIRMED หากยืนยันไม่ผ่านให้ใช้หลักฐานเดิม ลงลายเซ็นใหม่แล้ว retry การยืนยัน ห้ามโอนเงินจริงซ้ำเพราะคำตอบหาย
• การแจ้งยอดที่ต้องจ่ายไม่ขึ้นกับค่าเดิม autoPayoutEnabled การโอนอัตโนมัติขึ้นกับระบบที่ร้านเชื่อมต่อและเปิดใช้

เพย์เมนต์ไม่มีรูปสลิป: API ร้านค้าข้างต้นยังต้องมีผลตรวจสลิปที่ตรวจสอบได้ การใช้ผลจ่ายสำเร็จจากเพย์เมนต์ต้องเป็นเส้นทางเชื่อมต่อที่ระบบรองรับโดยเฉพาะ เช่น One2Pays ผ่านระบบร้านค้า Lottery Hub ไม่ได้เปิดให้อัตโนมัติสำหรับร้าน WEB/LINE ทุกแห่ง หากหน้าจอขึ้น “บันทึกยืนยันแล้ว” แต่หลักฐานยังไม่ครบ ให้ผู้ดูแลตรวจรายการเดิมและผลจากระบบที่โอน อย่าโอนซ้ำ

สร้าง verificationSignature ฝั่งเซิร์ฟเวอร์ด้วย HMAC-SHA256 และ webhook secret ของร้าน บนข้อความที่คั่นด้วย newline ตามลำดับด้านล่าง จำนวนเงินต้องใช้ decimal ทศนิยม 4 ตำแหน่ง gateway จะตรวจลายเซ็น ดึงผลตรวจจากผู้ให้บริการ และตรวจยอด/ผู้รับ/การใช้สลิปซ้ำอีกครั้ง:

payout-proof-v1
<verificationId.trim()>
<merchantId>
<transactionId>
<payoutRef>
<payoutAmount เช่น 300.0000>
<verificationExpiresAt>

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 ใน HTTP 2xx ที่ถูกต้อง → ไม่มีรายการถูกสร้าง ร้านใช้ระบบเดิมได้

ห้ามเปลี่ยนช่องทางเมื่อผลยังไม่แน่นอน: timeout, error, คำตอบว่าง/ไม่ครบ หรือ HTTP 409 ไม่ได้แปลว่าไม่มีคู่ ให้เก็บรายการเดิมและ retry ด้วย key/ข้อมูลเดิม รหัส TRY_MATCH_ALREADY_ACCEPTED หมายถึงเคยรับรายการแล้ว ใช้ transactionId อ่าน GET /api/transaction/:id ด้วย API key ร้านเจ้าของรายการและตรวจสถานะก่อนดำเนินการต่อ

ร้านต้องล็อกและบันทึกช่องทางจ่ายของแต่ละรายการแบบถาวร เมื่อเลือกจ่ายเองแล้วให้หยุดเรียก try-match ของรายการนั้น ใช้ bank idempotency key เดิมเมื่อกู้รายการ ห้ามจับคู่พร้อมกับโอนเอง เพราะคำขอที่ได้ no-match ไม่ได้ห้ามคำขอซ้ำจับคู่ได้ในภายหลัง

# ฝั่งฝาก: มีคนถอนรอรับพอดีไหม?
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 และ commit งานถาวรพร้อม dedupe ก่อนตอบ 2xx
• ตั้งบัญชีธนาคารร้านผ่าน 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 ที่พบบ่อย