LINE payment notification API

คู่มือใช้งาน Gupay API

ดึงรายการเงินเข้าจาก Krungthai Connext และ KBank Live พร้อมชื่อผู้โอนและสถานะการเชื่อมต่อ LINE ผ่าน REST API

REST + JSONBearer authentication120 requests / minute

เกี่ยวกับ API

เชื่อมระบบรับเงินของคุณกับ Gupay

Gupay อ่านการแจ้งเตือนเงินเข้าจากบัญชี LINE ที่คุณเชื่อมไว้ แล้วแปลงข้อมูลของแต่ละธนาคารให้เป็น JSON รูปแบบเดียวกันสำหรับนำไปตรวจคำสั่งซื้อในเว็บของคุณ

API ใช้ API key ของบัญชีคุณ ไม่ต้องใช้ record key และไม่ต้องส่งข้อมูลล็อกอิน LINE ไปยังระบบภายนอก

Gupay ไม่ใช่ธนาคารหรือ Payment Gateway

ระบบยืนยันจากข้อความแจ้งเตือน LINE ควรตรวจจำนวนเงิน ช่วงเวลา ธนาคาร และสถานะ CONFIRMED ร่วมกันก่อนส่งสินค้า

Base URL

https://gupay.system-easy.xyz/api/v1

01 · Quick start

เริ่มต้นเรียก API ภายใน 3 ขั้นตอน

1เชื่อม LINE ธนาคารให้สถานะเป็น Connected
2สร้าง API key และคัดลอกเก็บทันที
3เรียก API จาก backend พร้อม Bearer token

เก็บ API key ไว้ใน environment variable ฝั่ง server เท่านั้น ห้ามฝังใน JavaScript ของ browser, URL query string หรือ repository

02 · Payment matching

แนะนำให้ใช้ยอดทศนิยมเฉพาะแต่ละคำสั่งซื้อ

หากสินค้าราคา 100 บาท ให้ระบบจองเศษสตางค์ที่ยังไม่ถูกใช้ เช่น 100.24 บาท แล้วค้นหารายการที่ยอดตรงกันภายในช่วงเวลาที่กำหนด วิธีนี้ลดโอกาสจับคู่ผิดเมื่อมีลูกค้าหลายคนโอนยอดเต็มเท่ากัน

STEP 1

สร้าง order

กำหนดยอด 100.24

STEP 2

ให้ลูกค้าโอน

ผ่าน QR หรือเลขบัญชี

STEP 3

เรียก API

กรองช่วงเวลาด้วย from/to

STEP 4

ยืนยัน

ยอดตรง + CONFIRMED

ควรจองเศษสตางค์ต่อ order, ตั้งเวลาหมดอายุ และบันทึก transaction.id หลังจับคู่เพื่อป้องกันการใช้รายการเดิมซ้ำ

GET · transactions:read

/api/v1/transactions

ดึงรายการเงินเข้าเรียงจากใหม่ไปเก่า ระบบเลือกธนาคารให้อัตโนมัติตามที่ติ๊กไว้ในหน้า Connections จึงไม่ต้องส่งพารามิเตอร์ bank และรองรับ cursor pagination สูงสุด 100 รายการต่อ request

ค่า meta.enabledBanks บอกว่าคำขอนี้ใช้ธนาคารใดจาก Connections หากยังไม่ได้ติ๊กธนาคาร ระบบจะคืน data: []

Parameter	Type	Required	Description
limit	integer	No	1–100, ค่าเริ่มต้น 20
from	datetime	No	เวลาเริ่มต้น ISO 8601
to	datetime	No	เวลาสิ้นสุด ISO 8601
cursor	datetime	No	ค่าจาก meta.nextCursor เพื่ออ่านหน้าถัดไป

bashGupay

curl "https://gupay.system-easy.xyz/api/v1/transactions?limit=20" \
  -H "Accept: application/json" \
  -H "Authorization: Bearer gp_live_your_api_key"

ตัวอย่าง response

jsonGupay

{
  "data": [
    {
      "id": "81000000-0000-4000-8000-000000000001",
      "externalId": "line-message-id",
      "bankCode": "KRUNGTHAI",
      "amount": "100.24",
      "currency": "THB",
      "senderName": "สมชาย ใจดี",
      "senderAccountMasked": "xxx-x-4582-x",
      "description": "รับโอนเงินพร้อมเพย์",
      "status": "CONFIRMED",
      "receivedAt": "2026-08-10T08:30:00.000Z"
    }
  ],
  "meta": {
    "nextCursor": null,
    "limit": 20,
    "enabledBanks": ["KRUNGTHAI", "KBANK"]
  },
  "requestId": "3f6a86f5-9e77-4a37-a1e1-f7c28087db22"
}

ตารางข้อมูลธุรกรรม

Field	Type	Description
id	UUID	รหัสรายการของ Gupay
externalId	string	รหัสข้อความต้นทางจาก LINE ใช้ตรวจรายการซ้ำ
bankCode	enum	KRUNGTHAI หรือ KBANK
amount	string	จำนวนเงินทศนิยม 2 ตำแหน่ง เช่น 100.24
currency	string	สกุลเงิน ปัจจุบันเป็น THB
senderName	string \| null	ชื่อผู้โอนเมื่อข้อความธนาคารระบุมา
senderAccountMasked	string \| null	เลขบัญชีผู้โอนแบบปิดบังบางส่วน
description	string \| null	รายละเอียดรายการจากข้อความธนาคาร
status	enum	CONFIRMED หรือ REVERSED
receivedAt	ISO 8601	เวลารับรายการใน UTC

GET /api/v1/transactions/:id

ดึงรายการเดียวด้วย UUID ใช้ scope transactions:read และจะตอบ 404 TRANSACTION_NOT_FOUND หากรายการไม่อยู่ในบัญชีของ API key หรือธนาคารของรายการไม่ได้ถูกติ๊กไว้ใน Connections

GET · connections:read

/api/v1/connections

ตรวจ LINE หลัก ธนาคารที่ติ๊กเลือก และเวลาซิงก์ล่าสุด หนึ่งบัญชีผู้ใช้มี LINE connection ได้หนึ่งรายการ ระบบจะไม่เปิดเผย QR, PIN, session token หรือข้อความ error ภายในผ่าน public API

jsonGupay

{
  "data": [
    {
      "id": "67607803-3abe-48d3-ac00-180b037e47df",
      "label": "บัญชีรับเงินหลัก",
      "bankCodes": ["KRUNGTHAI", "KBANK"],
      "status": "CONNECTED",
      "lineDisplayName": "Gupay Store",
      "lastSyncAt": "2026-08-10T08:30:05.000Z",
      "createdAt": "2026-08-09T14:10:00.000Z"
    }
  ],
  "requestId": "5d17d032-6f41-4ea4-883a-729ae563c53a"
}

ก่อนตรวจยอด ควรยืนยันว่า connection ที่ต้องการมีสถานะ CONNECTED และ lastSyncAt ไม่เก่าเกินเวลาที่ระบบของคุณกำหนด

03 · Receiving money

วิธีรับเงินที่ใช้ร่วมกับ Gupay

พร้อมเพย์ QR Code

สร้าง QR ที่ล็อกยอดตาม order เช่น 100.24 บาท ลูกค้าสแกนแล้วโอนเข้าบัญชีที่เชื่อม LINE ไว้ จากนั้น backend ตรวจรายการผ่าน API

เลขบัญชีธนาคาร

ให้ลูกค้าโอนเข้าบัญชี Krungthai หรือ KBank ปกติได้ เมื่อ LINE ธนาคารแจ้งเตือน Gupay จะเพิ่มรายการเงินเข้าให้เรียกผ่าน API

04 · Troubleshooting

ข้อผิดพลาดที่ API ส่งกลับ

Error response มี code คงที่สำหรับใช้ในโปรแกรมและ requestId สำหรับติดตาม เช่น { "error": { "code": "INVALID_API_KEY", "message": "..." }, "requestId": "..." }

401	INVALID_API_KEY	ไม่ได้ส่ง key, key ไม่ถูกต้อง, ถูก revoke, หมดอายุ หรือ scope ไม่พอ
404	TRANSACTION_NOT_FOUND	ไม่พบรายการ หรือรายการไม่ใช่ของบัญชี API key นี้
422	VALIDATION_ERROR	พารามิเตอร์ไม่ถูกต้อง เช่น limit ไม่อยู่ระหว่าง 1–100
429	RATE_LIMITED	เกิน 120 requests ต่อนาทีต่อ API key
500	INTERNAL_ERROR	ระบบภายในขัดข้อง ให้เก็บ requestId ไว้ตรวจสอบ

สร้าง API key ดาวน์โหลด OpenAPI JSON