คู่มือใช้งาน
Payment CytechTeam Dev.

รู้จัก Payment CytechTeam Dev

ระบบสร้าง QR PromptPay และจับคู่รายการรับเงินอัตโนมัติจาก LINE Bank Alerts สำหรับร้านค้า เว็บไซต์ หรือระบบสมาชิกที่ต้องการเชื่อมต่อด้วย API

Payment CytechTeam Dev API สร้าง PromptPay checkout และคืนสถานะจาก LINE bank notification. ระบบภายนอกใช้ Merchant API Key ผ่าน Authorization: Bearer; หน้า Merchant Console ใช้ Session Cookie แบบ HttpOnly. การเข้าถึงข้อมูลร้านถูกจำกัดตามสิทธิ์ของ credential

เริ่มใช้งานใน 5 ขั้นตอน

ทำตามลำดับนี้ได้แม้ไม่เคยใช้ Payment API มาก่อน ถ้าต้องการเริ่มแบบสั้น ๆ อ่าน หน้า Quickstart เพิ่มเติมได้

ตั้งค่าร้านค้าและบัญชีรับเงิน

บัญชีร้านค้าคือพื้นที่จัดการ API keys, Projects, Checkout และ Webhook คุณต้องตั้งค่าฝั่ง Merchant ก่อน จึงจะสร้าง QR ที่ลูกค้าชำระเงินจริงได้

หากใช้หลายเว็บ: แยกเป็น Projects ภายใน Merchant เดียวกันเพื่อแยก API Key และรายงานได้ ดูหัวข้อ Projects & Workspaces

Authentication และการดูแล API Key

Server-to-server: เข้าสู่ Merchant Console เพื่อสร้างบัญชี ตั้งค่าร้านและ PromptPay แล้วสร้าง Merchant API Key ในหน้า API & Checkout. ส่ง Key ด้วย Authorization: Bearer cyt_next_... เท่านั้น อย่านำ Key ไปฝังใน JavaScript ที่ส่งให้เบราว์เซอร์

Merchant Console: เข้าสู่ระบบด้วย POST /v1/auth/login จากนั้นเบราว์เซอร์ใช้ __Host-cytech_console ซึ่งเป็น HttpOnly; Secure; SameSite=Strict Cookie อายุ 30 วัน จึงใช้งานข้ามแท็บหรือเปิดเบราว์เซอร์ใหม่ได้หากยังไม่หมดอายุ. ตรวจสถานะด้วย GET /v1/auth/session และออกจากระบบด้วย POST /v1/auth/logout. ไม่ต้องอ่านหรือเก็บ Session Token ใน JavaScript

ระบบยังรองรับ Authorization: Bearer cyt_sess_... สำหรับ API client ที่ต้องการใช้ Console Session โดยตรง. Session ใหม่มีอายุ 30 วัน และ Session เก่าที่ยังใช้ได้สามารถย้ายไปใช้ Cookie ได้. API Key และ Session ถูกเก็บเป็น Hash ฝั่ง Server; API Key ใหม่แสดงค่าเต็มเพียงครั้งเดียวตอนสร้าง

curl -sS -X POST "https://payment.cytechteam.dev/v1/checkouts" \
  -H "Authorization: Bearer cyt_next_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"merchant_ref":"order-1001","amount":"20.00","verification_method":"decimal"}'

แทน cyt_next_REPLACE_WITH_YOUR_KEY ด้วย Merchant API Key จริงของร้าน และเปลี่ยน merchant_ref ให้ไม่ซ้ำในแต่ละออเดอร์. ตัวอย่างใช้ URL เต็ม ไม่ต้องตั้งตัวแปร BASE หรือ KEY ใน Terminal. คำสั่งนี้สร้างบิลจริงบน Live environment

ออก Checkout แรกแบบเร็ว

ตัวอย่างด้านล่างใช้ URL เต็มของ Live API และใช้ cyt_next_REPLACE_WITH_YOUR_KEY แทนคีย์จริง โดยไม่ต้องตั้งตัวแปร Shell. ดู Quickstart แบบทีละขั้น เพื่อสร้างบิล เปิดหน้าจ่ายเงิน แล้วรับ webhook หรือ polling สถานะ. merchant_ref ต้องไม่ซ้ำสำหรับแต่ละออเดอร์

1. Create

curl -X POST "https://payment.cytechteam.dev/v1/checkouts" \
  -H "Authorization: Bearer cyt_next_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"merchant_ref":"order-1001","amount":"20.00","verification_method":"decimal"}'

2. Open

Response มี payment_path เช่น /pay/pay_... ให้เปิดหรือส่งให้ลูกค้า

3. Confirm

ฟัง payment.confirmed ที่ webhook หรือ poll GET /v1/checkouts/<id> จนสถานะเป็น PAID

เงินหนึ่งรายการ เดินทางอย่างไร?

ความเข้าใจวงจรของบิลสำคัญมาก โดยเฉพาะระบบเติมเครดิตหรือส่งสินค้าอัตโนมัติ

เลือกวิธีตรวจสอบยอดโอน

เลือกให้เหมาะกับข้อมูลที่คุณรู้เกี่ยวกับผู้โอน และตรวจให้แน่ใจว่าเงื่อนไขตรงตามธุรกรรมจริง

หนึ่งบิลเลือกได้หนึ่งวิธี และจะถูกจับคู่กับ LINE bank notification ที่ผ่านการตรวจผู้ส่งและเงื่อนไขอื่นของรายการ (บัญชีผู้รับ ยอดเงิน และเวลา) เท่านั้น

เลือกวิธีไหนให้เหมาะ?

decimal: เหมาะกับบิลทั่วไปเมื่อยืนยันด้วยเศษสตางค์ แต่ถ้าเปิดบิลยอดเดียวกันหลายใบพร้อมกัน แนะนำ amount_mode: "unique_cents" เพื่อให้ระบบจัดสรรเศษสตางค์ไม่ซ้ำ

name_exact: ใช้เมื่อทราบชื่อบัญชีผู้โอนที่จะแสดงในแจ้งเตือนอย่างแน่นอน · account_last4: ใช้เลขบัญชี ผู้โอน 4 หลักท้าย ไม่ใช่เลขบัญชีรับเงิน · bank: เหมาะเมื่อทราบธนาคารของผู้โอน

แยกบิลยอดเท่ากันด้วย Unique Cents

curl -sS -X POST "https://payment.cytechteam.dev/v1/checkouts" \
  -H "Authorization: Bearer cyt_next_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"merchant_ref":"order-1003","amount":"20.00","verification_method":"decimal","amount_mode":"unique_cents"}'

เชื่อมต่อกับเว็บไซต์ บอท และระบบสมาชิก

ไม่ว่าลูกค้าจะกดซื้อจากหน้าเว็บ Discord bot หรือเกม ขั้นตอนหลักเหมือนกัน: Server ของคุณสร้างออเดอร์ → ขอ Checkout → ส่งลิงก์ให้ลูกค้า → รอ PAID → ส่งมอบบริการ

ตัวอย่าง Node.js — สร้างบิลจาก Backend

const response = await fetch('https://payment.cytechteam.dev/v1/checkouts', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.CYTECH_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    merchant_ref: 'order-' + crypto.randomUUID(),
    amount: '20.00',
    verification_method: 'decimal'
  })
});
if (!response.ok) throw new Error('Checkout failed: ' + response.status);
const { checkout } = await response.json();
const paymentUrl = 'https://payment.cytechteam.dev' + checkout.payment_path;
console.log(paymentUrl, checkout.id);

ตัวอย่าง Python — สร้างบิลจาก Backend

import os
import requests

resp = requests.post(
    "https://payment.cytechteam.dev/v1/checkouts",
    headers={"Authorization": "Bearer " + os.environ["CYTECH_API_KEY"]},
    json={"merchant_ref": "order-1002", "amount": "20.00",
          "verification_method": "decimal"},
    timeout=15,
)
resp.raise_for_status()
checkout = resp.json()["checkout"]
print("https://payment.cytechteam.dev" + checkout["payment_path"])

ตรวจสถานะหากยังไม่มี Webhook

curl -sS "https://payment.cytechteam.dev/v1/checkouts/pay_REPLACE_WITH_REAL_ID" \
  -H "Authorization: Bearer cyt_next_REPLACE_WITH_YOUR_KEY"

Polling ควรทำจาก Backend ตามช่วงเวลาที่เหมาะสมและหยุดเมื่อ PAID, EXPIRED หรือ CANCELLED หากต้องการส่งมอบอัตโนมัติแนะนำใช้ Webhook เป็นช่องทางหลักและใช้ GET ตรวจสอบซ้ำได้

เชื่อมต่อ AI ด้วย MCP (Model Context Protocol)

Docs MCP สำหรับอ่านคู่มือสาธารณะผ่าน https://payment.cytechteam.dev/v1/mcp/docs โดยไม่ต้องล็อกอิน ใช้ค้นหัวข้อและอ่าน Markdown เท่านั้น

Manager MCP สำหรับอ่านข้อมูล Workspace โปรเจกต์ และ Checkout ผ่าน https://payment.cytechteam.dev/v1/mcp/manager รองรับ OAuth 2.1 ให้ล็อกอิน Payment แล้วเลือก Workspace และสิทธิ์บนหน้าขออนุญาต ไม่ต้องวาง Merchant API Key ลงในแอป AI

ดูตัวอย่างการเชื่อมต่อหลายแพลตฟอร์มได้ที่ ตั้งค่าบัญชี → MCP Integration

แยก Projects และจัดการ Workspaces

Workspace ใช้จัดการพื้นที่ร้านและสิทธิ์การเข้าถึงใน Merchant Console ส่วน Project ใช้แบ่งระบบย่อยของร้าน เช่น เว็บ A, Discord Bot, ร้านค้า B โดยใช้รหัส prj_... ของ Project ใน Checkout หรือ API Key ที่ผูก Project

เรียกรายการโปรเจกต์ที่สิทธิ์ปัจจุบันเข้าถึงได้ เลือก Project จาก Console เมื่อใช้งานหลายระบบ และใช้ project ใน request เฉพาะเมื่อทราบ ID จริงแล้ว

การตรวจเงินด้วย LINE ธนาคาร

Payment CytechTeam Dev ไม่ได้เชื่อมกับบัญชีธนาคารโดยตรง แต่รับข้อความแจ้งเตือนผ่าน LINE Worker แล้วตรวจสอบเงื่อนไข เช่น ผู้ส่งที่รู้จัก ยอดโอน ผู้รับ เวลาของรายการ และวิธีจับคู่ที่เลือกไว้

ใช้สำหรับตรวจรายการแจ้งเตือนจากธนาคารที่ระบบรับไว้ภายใต้สิทธิ์ของร้าน ควรเปรียบเทียบกับข้อมูลในธนาคารจริงเมื่อเกิดความคลาดเคลื่อน

ดูธนาคารที่ระบบระบุไว้ใน Bank coverage หรือเรียก GET /v1/banks เพื่อดูรายการที่ API ประกาศรองรับ

รับซองอั่งเป้า TrueMoney

รับซองอั่งเป้า TrueMoney เข้า wallet ของร้าน ยิงครั้งเดียวต่อซอง ไม่ retry อัตโนมัติ ผ่านได้เฉพาะ POST เท่านั้น

Request

curl -X POST "https://payment.cytechteam.dev/v1/merchant/truemoney/redeem" \
  -H "Authorization: Bearer cyt_next_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mobile":"0812345678","voucher":"https://gift.truemoney.com/campaign/?v=..."}'

States

• SUCCESS — เงินเข้าแล้ว ยอดส่งผ่านตรง ไม่ปัดเป็น 0.00
• FAILED — upstream ตอบปฏิเสธชัดเจน (code จาก TrueMoney)
• PENDING_RECONCILIATION — timeout/network ขาด ซองอาจถูกใช้ไปแล้ว ห้ามยิงซ้ำเอง ต้อง reconcile

ซองเดิมเรียกซ้ำคืนแถวเดิม (200 + duplicate:true) ซองเดิมแต่คนละเบอร์ได้ 409. ส่ง "retry":true เพื่อยิงซ้ำเฉพาะเคสชั่วคราว (edge block, rate limit, timeout, 5xx) — SUCCESS กับ code สุดท้ายปฏิเสธด้วย 409 ยกเว้น "retry":"force" ที่ยิงซ้ำได้ครั้งเดียวสำหรับแถวเก่าที่บันทึกด้วยโค้ดรุ่นก่อน (ไม่ใช่ SUCCESS). ประวัติรายการรับซองอยู่ที่ GET /v1/merchant/truemoney/redemptions และดูร่วมกับ Checkout ได้ที่หน้า ธุรกรรม หรือ GET /v1/merchant/transactions?channel=truemoney โดยกรอง channel=all|checkout|truemoney, status, limit, offset ได้ ประวัติรวมแสดงรหัสซองและเบอร์ผู้รับแบบปิดบางส่วน ไม่แสดงลิงก์ซองเต็ม

รายการ TrueMoney ที่สำเร็จแสดงจำนวนเงินจริงตามผลตอบกลับ หากยังยืนยันยอดไม่ได้ ระบบจะแสดงว่าไม่ทราบยอดแทน 0.00 และจะไม่รวมยอดซองเข้ากับสถิติ Checkout โดยอัตโนมัติ เพื่อไม่ให้นับยอดซ้ำ

สร้าง Checkout

Body

Response

{
  "checkout": {
    "id": "pay_...",
    "merchant_ref": "order-1001",
    "amount": "20.00",
    "status": "PENDING",
    "verification_method": "decimal",
    "payment_path": "/pay/pay_...",
    "expires_at": "2026-10-25T12:15:00+00:00"
  }
}

ดึงข้อมูล Checkout และรายการ

คืน checkout ของ merchant นี้เท่านั้น ถ้าไม่พบจะได้ 404 แบบไม่เปิดเผยว่ามีอยู่จริงหรือไม่

ยกเลิกบิลที่ยังเป็น PENDING โดยส่ง JSON {} พร้อม Merchant API Key หรือ Console session บนเซิร์ฟเวอร์ จะได้ผลลัพธ์ {"checkout":{"status":"CANCELLED",...}} การกดซ้ำปลอดภัย (idempotent) แต่บิล PAID หรือหมดเวลาแล้วตอบ 409, คนละ Workspace/Project ได้ 404 ไม่ใช่การคืนเงิน และควรใช้ merchant_ref ใหม่เมื่อสร้างบิลทดแทน

curl -X POST "https://payment.cytechteam.dev/v1/checkouts/pay_REPLACE_WITH_REAL_ID/cancel" \
  -H "Authorization: Bearer cyt_next_REPLACE_WITH_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

หน้าจ่ายเงินมีปุ่มยกเลิกสำหรับผู้ถือ URL ของบิลผ่าน POST /pay/<pay_id>/cancel (ต้องเป็น JSON และเรียกจาก Origin เดียวกัน) ระบบหยุดแสดง QR และแจ้ง payment.cancelled ผ่าน Webhook และ Custom Notification ที่สมัคร event นี้ไว้ หากโอนไปแล้วหรือโอนผิดหลังยกเลิก ต้องตรวจยอดและจัดการคืนเงินแยกต่างหาก

รายการล่าสุดสำหรับ Console และรายงาน. รองรับ status PENDING, PAID, EXPIRED, CANCELLED

ดูข้อมูล Merchant ปัจจุบัน ใช้ตรวจสอบ Key และรายละเอียดบัญชีรับเงินที่ตั้งค่าไว้

อ่านภาพรวมธุรกรรมของร้าน หรือระบุ Project เมื่อมีหลายโปรเจกต์

หน้าชำระเงินสาธารณะและ QR

หน้า public ไม่ต้องใช้ API key. QR จะถูกปฏิเสธเมื่อบิลไม่ใช่ PENDING. Status endpoint คืนเฉพาะสถานะที่ปลอดภัย

Webhook: รับสถานะชำระเงินอัตโนมัติ

ตั้งค่าจุดรับในเมนู API & Checkout หรือใช้ POST /v1/merchant/webhook จากบัญชีที่มีสิทธิ์ Merchant และระบุ HTTPS URL ที่เข้าถึงจากอินเทอร์เน็ตได้

เมื่อยืนยันสำเร็จ ระบบเขียน outbox ใน transaction เดียวกับ PAID แล้วส่ง POST ไปยัง URL ของร้าน

Headers

{
  "type": "payment.confirmed",
  "data": {
    "id": "pay_...",
    "merchant_ref": "order-1001",
    "amount": "20.00",
    "status": "PAID",
    "confirmation_basis": "BANK_LINE_NOTIFICATION",
    "funds_received": true
  }
}

Retries: bounded exponential backoff, สูงสุด 7 ครั้ง. ฝั่งร้านควรตอบ 2xx และ dedup ด้วย event ID

ตรวจสอบลายเซ็น Webhook ด้วย Node.js

บน Backend ติดตั้ง npm install express ใช้ Node.js แบบ ES Modules และกำหนด CYTECH_WEBHOOK_SECRET จาก Console (Secret แสดงครั้งเดียวเมื่อสร้างหรือ Rotate)

คำนวณ HMAC จาก timestamp + "." + raw_body ด้วย Webhook Secret ที่ตั้งค่าของร้าน ตรวจ timestamp เพื่อป้องกัน replay และใช้การเปรียบเทียบแบบ timing-safe ก่อนอ่านข้อมูลคำสั่งซื้อ

import express from 'express';
import { createHmac, timingSafeEqual } from 'node:crypto';

const app = express();
app.post('/payments', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Cytech-Timestamp') || '';
  const sent = req.get('X-Cytech-Signature') || '';
  if (!/^\d+$/.test(ts) || Math.abs(Date.now()/1000 - Number(ts)) > 300)
    return res.sendStatus(401);
  const expected = createHmac('sha256', process.env.CYTECH_WEBHOOK_SECRET)
    .update(ts + '.').update(req.body).digest('hex');
  const received = sent.replace(/^sha256=/i, '');
  if (!/^[a-f0-9]{64}$/i.test(received) ||
      !timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(received, 'hex')))
    return res.sendStatus(401);
  const event = JSON.parse(req.body.toString('utf8'));
  const eventId = req.get('X-Cytech-Event-ID');
  // Queue a transaction: persist eventId uniquely, then fulfill PAID order once.
  // Acknowledge 2xx after durable processing or queuing.
  return res.sendStatus(204);
});
app.listen(Number(process.env.PORT || 3000));

Idempotency และการป้องกันซ้ำ

(merchant_id, merchant_ref) ไม่ซ้ำ. การเรียก create ซ้ำด้วย ref และข้อมูลเดิมจะคืน checkout เดิม. ถ้า ref เดิมแต่ยอด/วิธีตรวจสอบต่าง จะได้ 409

LINE message ID ซ้ำจะไม่สร้าง event ใหม่และไม่จ่ายบิลซ้ำ

รหัส HTTP Error

ขีดจำกัดและข้อกำหนด

• Checkout expiry: 15 minutes
• Amount: positive, max 9,999,999.99 THB
• merchant_ref: 1–128 token chars
• API key limit: 10 active keys per merchant
• Webhook body/outbox: bounded retries, สูงสุด 7 attempts
• Console session: 30 days, ยกเลิกได้ด้วย Logout หรือ Password Reset

แก้ปัญหาที่พบบ่อย

ตรวจจากขั้นตอนที่เกี่ยวข้องก่อนแก้ไขในระบบร้าน อย่าสร้าง Checkout หรือส่งมอบสินค้าซ้ำโดยไม่ได้ตรวจสถานะเดิม

แนวทางใช้งานจริงที่แนะนำ

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

ความปลอดภัยและขอบเขตบริการ

• Live LINE Worker ปัจจุบันตั้ง CYTECH_LINE_SENDER_POLICY=name ตรวจชื่อ LINE Official Account ที่ normalize แล้วแบบตรงตัวกับชื่อธนาคารที่รู้จัก โดยบันทึก MID เพื่อ audit แต่ไม่ได้ยืนยัน MID allowlist หรือ Verified/Premium badge ในโหมดนี้. โค้ดยังรองรับโหมด mid, badge_name และ mid_or_badge_name เมื่อกำหนดค่าต่างออกไป
• Internal LINE bridge ใช้ HMAC signature และกรอบเวลา ±90 วินาที; การยืนยันแบบ BANK_LINE_NOTIFICATION ไม่ใช่ Bank Settlement โดยตรง
• API keys และ Console sessions ถูกเก็บเป็น hash; Browser Console ใช้ Secure HttpOnly SameSite=Strict Cookie อายุ 30 วัน
• Webhook URLs ต้องเป็น public HTTPS และห้าม resolve ไปยัง private/literal host
• จำนวนเงินเก็บเป็นจำนวนเต็มหน่วยสตางค์