SDK

SDK เหล่านี้ช่วยให้เซิร์ฟเวอร์ของคุณตรวจสลิปโอนเงินของธนาคารไทยและสลิป TrueMoney Wallet กับธนาคารได้ และเช็กในคำขอเดียวกันว่าเงินเข้าบัญชีของคุณ ยอดเงินถูกต้อง และไม่ใช่สลิปซ้ำ เผยแพร่ภายใต้ชื่อ EasySlip (@easyslip/sdk, easyslip-sdk, easyslip/sdk และ github.com/EASYSLIP-CO-LTD/sdk-go) และใช้กับ Thunder API v2 และ v1 ได้เมื่อตั้งที่อยู่ให้ชี้ไป Thunder ตามที่อธิบายด้านล่าง มีให้ใช้กับ JavaScript และ TypeScript, Python, Go และ PHP ทุกภาษาเรียก API v2 และ API v1 ได้ครบ ทั้งการตรวจสลิป งานเบื้องหลัง บัญชีรับเงิน คิวอาร์รับเงิน และการตรวจลายเซ็นของเว็บฮุค

SDK ทุกภาษาใส่ API key ให้ทุกคำขอ ตรวจไฟล์รูปก่อนอัปโหลด คืน error แยกตามชนิดของปัญหา และลองส่งคำขอที่ล้มเหลวใหม่ให้โดยไม่ทำให้การตรวจสลิปใบเดียวกันถูกหักโควต้าซ้ำ

เลือกภาษา

ภาษา	ต้องใช้
JavaScript และ TypeScript	Node.js 22+
Python	Python 3.11 ถึง 3.15
Go	Go 1.26+
PHP	PHP 8.2+

SDK ภาษา JavaScript ใช้กับ Bun 1.4, Deno 2.9 และ Cloudflare Workers ได้ด้วย ส่วน SDK ภาษา PHP ต้องใช้คู่กับ Guzzle 7.16 ขึ้นไป หรือ Guzzle 8.3 ขึ้นไป ซอร์สโค้ดของแต่ละ SDK อยู่ที่ซอร์สโค้ดและสัญญาอนุญาต

คู่มือของแต่ละภาษาอธิบายทุกฟีเจอร์พร้อมโปรแกรมที่รันได้จริง ส่วน README ใน repository ของแต่ละภาษาเป็นฉบับสรุปของ SDK ตัวเดียวกัน

การติดตั้ง

JavaScriptPythonGoPHP

npm install @easyslip/sdk

python -m pip install easyslip-sdk

go get github.com/EASYSLIP-CO-LTD/sdk-go

composer require easyslip/sdk

ใช้ SDK กับ Thunder

SDK เรียกที่อยู่ของ EasySlip เป็นค่าเริ่มต้น และ API key ของ Thunder ใช้ที่นั่นไม่ได้ ก่อนรันตัวอย่างใดๆ ให้ตั้งที่อยู่ทั้งสองไปที่ Thunder

export EASYSLIP_V2_BASE_URL="https://api.thunder.in.th/v2"
export EASYSLIP_V1_BASE_URL="https://api.thunder.in.th/v1"

จะส่งที่อยู่เดียวกันตอนสร้าง client แทนก็ได้ คือ v2BaseUrl และ v1BaseUrl ใน JavaScript และ PHP, v2_base_url และ v1_base_url ใน Python, WithBaseURLs(v2, v1) ใน Go เมื่อตั้งแล้วทุกคำขอ response และ error จะตรงกับเอกสารนี้ และ endpoint คือที่อยู่ใน API v2 และ API v1

เว็บฮุคของ Thunder ใช้ชื่อ header ต่างออกไป

Thunder ลงลายเซ็นเว็บฮุคใน header X-Thunder-Signature ส่วน SDK ระบุ X-EasySlip-Signature ในค่าคงที่ WEBHOOK_SIGNATURE_HEADER และ SIGNATURE_HEADER ให้อ่าน X-Thunder-Signature เองแล้วส่งค่าให้ SDK ตามตัวอย่างเว็บฮุคในคู่มือแต่ละภาษา วิธีตรวจลายเซ็นเหมือนกัน คือ sha256= ตามด้วย HMAC-SHA256 ของ body ดิบ

ตั้งค่า API key

เข้าสู่ระบบที่ Thunder developer portal แล้วคัดลอก API key ของแอปพลิเคชันมาใช้ ดูเรื่อง key และสาขาได้ที่การยืนยันตัวตน จากนั้นส่ง key ให้ SDK ด้วยวิธีใดวิธีหนึ่งต่อไปนี้

ส่ง key ตอนสร้าง client
ตั้งตัวแปร environment EASYSLIP_API_KEY ชื่อตัวแปรเป็นชื่อของ SDK แต่ค่าที่ใส่คือ API key ของ Thunder
เก็บ key ไว้ในไฟล์ แล้วตั้ง EASYSLIP_API_KEY_FILE เป็น path ของไฟล์นั้น เช่น Docker secret หรือ Kubernetes secret

SDK ใช้ค่าแรกที่ตั้งไว้ตามลำดับนี้

export EASYSLIP_API_KEY="your-api-key"

# หรือเก็บ key ไว้ในไฟล์ที่อ่านได้เฉพาะ user ที่รันแอปของคุณ
export EASYSLIP_API_KEY_FILE="/run/secrets/easyslip-api-key"

เก็บ API key ไว้ที่เซิร์ฟเวอร์เท่านั้น

ใครได้ key ของคุณไปก็ใช้โควต้าของคุณได้ ใช้ SDK เฉพาะในโค้ดที่รันบนเซิร์ฟเวอร์ของคุณ อย่าใส่ key ในหน้าเว็บหรือแอปมือถือ และอย่า commit key หรือไฟล์ key ลง repository

SDK ส่ง key ไปใน header Authorization เท่านั้น ถ้า response มี key ติดมา SDK จะลบ key ออกจากข้อความ error และ header ที่ส่งคืนให้คุณ จึงเก็บ log ของ error จาก SDK ได้

SDK อ่านตัวแปรเหล่านี้ด้วย

ตัวแปร	ค่าเริ่มต้น	ใช้เปลี่ยนอะไร
`EASYSLIP_V2_BASE_URL`	`https://api.easyslip.com/v2`	ที่อยู่ของ API v2 ตั้งเป็น `https://api.thunder.in.th/v2` สำหรับ Thunder
`EASYSLIP_V1_BASE_URL`	`https://api.easyslip.com/v1`	ที่อยู่ของ API v1 ตั้งเป็น `https://api.thunder.in.th/v1` สำหรับ Thunder
`EASYSLIP_WEBHOOK_SECRET`	ไม่มี	Webhook Secret ของสาขา มีแค่ SDK ภาษา JavaScript ที่อ่านค่านี้ให้เอง ภาษาอื่นให้ส่ง secret เข้าฟังก์ชันตรวจเว็บฮุค

ตรวจสลิปใบแรก

โปรแกรมนี้ตรวจสลิปที่ลูกค้าส่งมาจ่ายออเดอร์ยอด 1,500 บาท โดยถาม API ว่าเงินเข้าบัญชีรับเงินที่ลงทะเบียนไว้หรือไม่ ยอดเงินถูกต้องหรือไม่ และสลิปเคยถูกใช้แล้วหรือไม่ แล้วรับยอดเฉพาะเมื่อผ่านครบทั้งสามเงื่อนไข

JavaScriptPythonGoPHP

import { EasySlip } from '@easyslip/sdk'

const easyslip = new EasySlip() // อ่าน API key จาก EASYSLIP_API_KEY

const result = await easyslip.verify.bankByImage('./slip.jpg', {
    matchAccount: true, // เงินเข้าบัญชีรับเงินของเราไหม
    matchAmount: 1500, // ยอดเงินถูกไหม
    checkDuplicate: true, // เป็นสลิปซ้ำไหม
})
const paid = result.isDuplicate === false && result.isAmountMatched === true && result.matchedAccount != null
console.log(paid ? `ชำระแล้ว: ${result.rawSlip.transRef}` : 'อย่ารับสลิปนี้')

python

from easyslip import Client
from easyslip.models import MatchedAccount, VerifyOptions

with Client() as client:  # อ่าน API key จาก EASYSLIP_API_KEY
    result = client.verify.bank_by_image(
        "slip.jpg",
        VerifyOptions(
            match_account=True,  # เงินเข้าบัญชีรับเงินของเราไหม
            match_amount=1500.0,  # ยอดเงินถูกไหม
            check_duplicate=True,  # เป็นสลิปซ้ำไหม
        ),
    )
    paid = (
        result.is_duplicate is False
        and result.is_amount_matched is True
        and isinstance(result.matched_account, MatchedAccount)
    )
    print(f"ชำระแล้ว: {result.raw_slip.trans_ref}" if paid else "อย่ารับสลิปนี้")

package main

import (
	"context"
	"fmt"
	"log"

	easyslip "github.com/EASYSLIP-CO-LTD/sdk-go"
)

func main() {
	client, err := easyslip.NewClient("") // อ่าน API key จาก EASYSLIP_API_KEY
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	result, err := client.Verify.BankByImage(context.Background(), "slip.jpg", &easyslip.VerifyOptions{
		MatchAccount:   easyslip.Some(true),   // เงินเข้าบัญชีรับเงินของเราไหม
		MatchAmount:    easyslip.Some(1500.0), // ยอดเงินถูกไหม
		CheckDuplicate: easyslip.Some(true),   // เป็นสลิปซ้ำไหม
	})
	if err != nil {
		log.Fatal(err)
	}
	duplicate, checked := result.IsDuplicate.Value()
	amountMatched, _ := result.IsAmountMatched.Value()
	account, _ := result.MatchedAccount.Value()
	if checked && !duplicate && amountMatched && account != nil {
		fmt.Println("ชำระแล้ว:", result.RawSlip.TransRef)
	} else {
		fmt.Println("อย่ารับสลิปนี้")
	}
}

php

<?php

require __DIR__ . '/vendor/autoload.php';

use EasySlip\EasySlip;
use EasySlip\Input\FileInput;
use EasySlip\Input\VerifyOptions;

$easyslip = new EasySlip(); // อ่าน API key จาก EASYSLIP_API_KEY

$result = $easyslip->verify->bankByImage(FileInput::fromPath(__DIR__ . '/slip.jpg'), new VerifyOptions(
    matchAccount: true, // เงินเข้าบัญชีรับเงินของเราไหม
    matchAmount: 1500, // ยอดเงินถูกไหม
    checkDuplicate: true, // เป็นสลิปซ้ำไหม
));
$paid = $result->isDuplicate === false && $result->isAmountMatched === true && $result->matchedAccount !== null;
echo $paid ? "ชำระแล้ว: {$result->rawSlip->transRef}\n" : "อย่ารับสลิปนี้\n";

matchAccount เทียบบัญชีผู้รับกับบัญชีรับเงินที่คุณลงทะเบียนไว้ จึงต้องเพิ่มบัญชีรับเงินก่อน ทำได้ใน developer portal หรือใช้ SDK การตรวจสลิปแต่ละครั้งใช้โควต้า 1 ครั้ง คู่มือของแต่ละภาษามีโปรแกรมนี้ฉบับเต็ม ที่แสดงข้อความแยกตามเงื่อนไขที่ไม่ผ่าน และจัดการ error เมื่อธนาคารไม่พบรายการโอนของสลิป ดูรายละเอียดของคำขอและ response ได้ที่ POST /verify/bank

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

SDK ทำอะไรได้บ้าง

งาน	API	JavaScript	Python	Go	PHP
ข้อมูลบัญชีและโควต้า	`GET /info`	`getInfo`	`get_info`	`GetInfo`	`getInfo`
ตรวจสลิปธนาคาร	`POST /verify/bank`	`verify.bankBy*`	`verify.bank_by_*`	`Verify.BankBy*`	`verify->bankBy*`
ตรวจสลิป TrueMoney Wallet	`POST /verify/truewallet`	`verify.truewalletBy*`	`verify.truewallet_by_*`	`Verify.TruewalletBy*`	`verify->truewalletBy*`
ตรวจเบื้องหลังและตรวจเป็นชุด	Async Verify	`jobs.*`	`jobs.*`	`Jobs.*`	`jobs->*`
รหัสธนาคาร	`GET /banks`	`banks.list`	`banks.list`	`Banks.List`	`banks->list`
บัญชีรับเงิน	บัญชีธนาคาร	`bankAccounts.*`	`bank_accounts.*`	`BankAccounts.*`	`bankAccounts->*`
คิวอาร์รับเงิน	`POST /qr/generate`	`v1.generateQr`	`v1.generate_qr`	`V1.GenerateQR`	`v1->generateQr`
API v1 แบบเดิม	API v1	`v1.*`	`v1.*`	`V1.*`	`v1->*`
ตรวจเว็บฮุค	Webhook Callback	`constructWebhookEvent`	`webhooks.construct_event`	`ConstructWebhookEvent`	`Webhook::constructEvent`

By* คือวิธีส่งสลิป ได้แก่ Payload (ข้อความในคิวอาร์โค้ดของสลิป), Image (ไฟล์หรือไฟล์ที่อัปโหลดมา), Base64 หรือ URL สลิป TrueMoney Wallet ไม่มีเมธอดแบบ payload

สิ่งที่ SDK ทุกภาษาทำเหมือนกัน

timeout และการลองใหม่ การส่งแต่ละครั้งใช้เวลาได้ไม่เกิน 30 วินาที และคำขอที่ล้มเหลวจะถูกลองใหม่ไม่เกิน 2 ครั้ง เปลี่ยนทั้งสองค่าได้ตอนสร้าง client ก่อนลองใหม่ครั้งแรก SDK จะรอประมาณครึ่งวินาที แล้วเพิ่มเวลารอเป็นสองเท่าทุกครั้ง ไม่เกิน 8 วินาที
ไม่หักโควต้าซ้ำ การตรวจสลิปและการส่งงานเบื้องหลังใช้โควต้า SDK จึงลองใหม่เฉพาะเมื่อ API ตอบ 429 หรือเชื่อมต่อไม่สำเร็จก่อนคำขอจะถูกส่งออกไป การเพิ่ม แก้ไข และยกเลิกการผูกบัญชีรับเงินก็ใช้กติกาเดียวกัน ส่วนการอ่านข้อมูล การผูกบัญชี และการสร้างคิวอาร์ ส่งซ้ำได้อย่างปลอดภัย จึงลองใหม่ให้ด้วยเมื่อหมดเวลา เครือข่ายล้มเหลว หรือ API ตอบ 500, 502, 503 หรือ 504 คำตอบ 400, 401, 403, 404 หรือ 409 จะไม่ถูกลองใหม่เลย
Retry-After ถ้า API ส่ง Retry-After มา SDK จะรอตามนั้นก่อนลองใหม่ ถ้าต้องรอนานกว่า 60 วินาที SDK จะคืน error ทันที
ตรวจไฟล์ก่อนอัปโหลด รูปต้องเป็น JPEG, PNG, GIF หรือ WebP ขนาดไม่เกิน 4 MB ถ้าไฟล์ว่าง ใหญ่เกิน 4 MB หรือไม่ใช่รูป SDK จะคืน InputError โดยไม่ส่งอะไรออกไป
ค่าในคำขอ ในคำขอ type ของบัญชีรับเงินเป็น NATURAL หรือ JURISTIC และ type ของคิวอาร์เป็นค่าใดค่าหนึ่งในห้าค่า ตัวตรวจ type ของ TypeScript และ Python ไม่รับค่าอื่นผ่าน type AccountType และ QrType ส่วน PHP รับ enum AccountType และ QrType และ Go มีค่าคงที่ เช่น AccountTypeJuristic และ QRTypePromptPay ฟิลด์ในคำตอบรับข้อความใดก็ได้ ค่าใหม่ที่ API เพิ่มภายหลังจึงไม่ทำให้โค้ดของคุณพัง
error แยกตามชนิด SDK ทุกภาษาใช้ชื่อ error ชุดเดียวกัน เช่น SlipNotFoundError, QuotaExceededError และ RateLimitError และทุกตัวมี type ร่วมกันคือ EasySlipError ใน JavaScript, Python และ PHP เป็น base class ของ error ทุกตัว ส่วนใน Go เป็น interface และหา type ที่แท้จริงได้ด้วย errors.As ดูความหมายของรหัสทุกตัวที่ API คืนได้ที่รหัส Error
ตรวจเว็บฮุค SDK ทุกภาษาตรวจลายเซ็นที่คุณส่งให้ ซึ่งมาจาก header X-Thunder-Signature และเป็น sha256= ตามด้วย HMAC-SHA256 ของ body ดิบ โดยเปรียบเทียบแบบใช้เวลาคงที่ ตัวอย่างเว็บฮุคในคู่มือทุกภาษาตอบ status 400 เมื่อไม่มีลายเซ็นหรือลายเซ็นไม่ตรง และเมื่อ body ที่ลงลายเซ็นมาไม่ใช่ event ของเว็บฮุค

ซอร์สโค้ดและสัญญาอนุญาต

ซอร์สโค้ดของ SDK ทุกภาษาอยู่บน GitHub ได้แก่ sdk-js, sdk-python, sdk-go และ sdk-php ทุก repository มี README, changelog และโฟลเดอร์ examples ที่มีโปรแกรมที่รันได้จริงครบทุกเมธอด แจ้งบั๊กได้ที่หน้า Issues ของ repository นั้น ห้ามโพสต์ API key หรือสลิปจริงไว้ที่นั่น

คำถามเรื่องบัญชี โควต้า หรือการเรียกเก็บเงิน ติดต่อ Thunder Solution ได้ที่ developer portal

SDK ​

เลือกภาษา ​

การติดตั้ง ​

ใช้ SDK กับ Thunder ​

ตั้งค่า API key ​

ตรวจสลิปใบแรก ​

SDK ทำอะไรได้บ้าง ​

สิ่งที่ SDK ทุกภาษาทำเหมือนกัน ​

ซอร์สโค้ดและสัญญาอนุญาต ​

SDK