API ธุรกรรมชำระเงิน

คำขอ

API ชำระเงินช่วยให้พ่อค้าเริ่มต้นธุรกรรมการเก็บเงินจากลูกค้า
วิธีการชำระเงินที่รองรับรวมถึง:

QRPAY (การชำระเงินตอบสนองเร็ว)
การโอนเงินธนาคาร
กระเป๋าเงินดิจิทัล
บัตรเครดิต/เดบิต
ช่องทางการชำระเงินดิจิทัลอื่นๆ

เส้นทางคำขอ:

sandbox: https://sandbox-gateway.smilepayz.com/v2.0/transaction/pay-in
production: https://gateway.smilepayz.com/v2.0/transaction/pay-in

พารามิเตอร์ Header

ฟิลด์	จำเป็น	ประเภท	คำอธิบาย
Content-Type	M	String	ข้อกำหนดประเภทเนื้อหา HTTP ค่าคงที่: application/json จำเป็นสำหรับการแยกวิเคราะห์คำขอที่เหมาะสม
X-TIMESTAMP	M	String	รูปแบบวันที่เวลา ISO 8601 พร้อม offset เขตเวลา รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00 หมายเหตุ: ต้องเป็นเวลาเซิร์ฟเวอร์ปัจจุบันภายใน ±5 นาที
X-SIGNATURE	M	String	ลายเซ็นดิจิทัลสำหรับการยืนยันตัวตนคำขอ ดู การสร้างลายเซ็น
X-PARTNER-ID	M	String	ตัวระบุพ่อค้าเฉพาะที่ได้รับมอบหมายจากแพลตฟอร์ม รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้สำหรับการยืนยันตัวตนพ่อค้าและการเส้นทางธุรกรรม กรุณาใส่ merchantID

พารามิเตอร์ Body

ฟิลด์	จำเป็น	ประเภท	คำอธิบาย
orderNo	M	String(32)	ตัวระบุธุรกรรมเฉพาะสำหรับการติดตามพ่อค้า รูปแบบ: ตัวอักษรและตัวเลขเท่านั้น ความยาว: 6-32 ตัวอักษร ต้องไม่ซ้ำกันภายในขอบเขตพ่อค้า
purpose	M	String(64)	คำอธิบายธุรกรรมที่อ่านได้ รูปแบบ: สตริงที่เข้ารหัส UTF-8 ความยาว: 1-64 ตัวอักษร ใช้สำหรับประวัติธุรกรรมและการรายงาน
merchant	M	Object	ภาชนะข้อมูลการระบุตัวตนและธุรกิจของพ่อค้า ประกอบด้วยรายละเอียดพ่อค้าหลักและพ่อค้าย่อย จำเป็นสำหรับการเส้นทางธุรกรรมและการชำระบัญชี
merchantId	M	String	ตัวระบุพ่อค้าหลักที่ได้รับมอบหมายจากแพลตฟอร์ม รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้สำหรับการเส้นทางธุรกรรมและการประมวลผลการชำระบัญชี
merchantName	O	String	ชื่อธุรกิจที่ลงทะเบียนของพ่อค้า รูปแบบ: สตริงที่เข้ารหัส UTF-8 แสดงในอินเทอร์เฟซการชำระเงินและบันทึกธุรกรรม
subMerchantId	O	String	ตัวระบุพ่อค้าย่อยสำหรับโครงสร้างพ่อค้าหลายระดับ รูปแบบ: สตริงตัวอักษรและตัวเลข จำเป็นสำหรับการประมวลผลธุรกรรมพ่อค้าย่อย
subMerchantName	O	String	ชื่อธุรกิจพ่อค้าย่อยสำหรับการแสดงผล รูปแบบ: สตริงที่เข้ารหัส UTF-8 แสดงในอินเทอร์เฟซการชำระเงินและบันทึกธุรกรรม
money	M	Object	ภาชนะข้อกำหนดจำนวนเงินและสกุลเงินธุรกรรม กำหนดมูลค่าการชำระเงินและหน่วยเงิน จำเป็นสำหรับการประมวลผลการชำระเงินและการชำระบัญชี
currency	M	String	ข้อกำหนดรหัสสกุลเงิน ISO 4217 ค่าคงที่: THB (บาทไทย) กำหนดกฎการประมวลผลการชำระเงินและสกุลเงินการชำระบัญชี
amount	M	Number	จำนวนเงินธุรกรรมในหน่วยสกุลเงินที่เล็กที่สุด รูปแบบ: ค่าจำนวนเต็ม ตัวอย่าง: 200 แทน THB 200.00 ช่วง: 100-999999999
payer	M	Object	ภาชนะข้อมูลการชำระเงินของลูกค้า ใช้สำหรับการยืนยันการชำระเงินและการสื่อสารกับลูกค้า
name	M	String	ชื่อเต็มของลูกค้าสำหรับการยืนยันการชำระเงิน รูปแบบ: สตริงที่เข้ารหัส UTF-8 ใช้สำหรับการประมวลผลการชำระเงินและบันทึกธุรกรรม
accountNo	M	String	หมายเลขบัญชีธนาคารลูกค้าสำหรับการประมวลผลการชำระเงิน รูปแบบ: สตริงตัวเลข ใช้สำหรับยืนยันการชำระเงินโอนเงินผ่านธนาคาร
bankName	M	String	ชื่อธนาคารของลูกค้าสำหรับการประมวลผลการชำระเงิน รูปแบบ: รหัสธนาคารที่กำหนดไว้ล่วงหน้า ตัวอย่าง: KBANK, BBL, SCB ดู รายการวิธีการชำระเงิน
paymentMethod	O	String	ข้อกำหนดวิธีการชำระเงินที่ต้องการ รูปแบบ: รหัสวิธีการชำระเงินที่กำหนดไว้ล่วงหน้า ตัวอย่าง: QRPAY or KBANK หากไม่ระบุ จะแสดงหน้าคัดเลือกวิธีการชำระเงิน ดู รายการวิธีการชำระเงิน
expiryPeriod	O	Number	ระยะเวลาหมดอายุเซสชันการชำระเงินเป็นวินาที รูปแบบ: ค่าจำนวนเต็ม ค่าเริ่มต้น: 3600 วินาที (1 ชั่วโมง)
redirectUrl	O	String(256)	URL ปลายทางการเปลี่ยนเส้นทางหลังการชำระเงิน รูปแบบ: URL HTTP/HTTPS ที่ถูกต้อง ความยาวสูงสุด: 256 ตัวอักษร ลูกค้าจะถูกเปลี่ยนเส้นทางมาที่นี่หลังการเสร็จสิ้นการชำระเงิน
callbackUrl	O	String(256)	URL ปลายทางการแจ้งเตือน Webhook รูปแบบ: URL HTTP/HTTPS ที่ถูกต้อง ความยาวสูงสุด: 256 ตัวอักษร รับการอัปเดตสถานะธุรกรรมแบบเรียลไทม์

หมายเหตุสำคัญ

1. การเลือกวิธีการชำระเงิน: หากไม่ระบุ paymentMethod Smilepayz จะส่งคืนหน้าชำระเงินสำหรับลูกค้าเพื่อเลือกวิธีการชำระเงินที่ต้องการ

2. ความต้องการข้อมูลผู้จ่ายเงิน: เมื่อระบุ paymentMethod คุณต้องให้ชื่อผู้จ่ายเงิน หมายเลขบัญชี และชื่อธนาคารสำหรับการยืนยันการชำระเงิน

3. ความต้องการการโอนเงินธนาคาร: เมื่อตั้งค่า paymentMethod เป็น BANK ข้อมูลผู้จ่ายเงิน (name, accountNo, bankName) เป็น ⚠️ บังคับ สำหรับการประมวลผลการโอนเงินธนาคาร

4. อ้างอิงชื่อธนาคาร: สำหรับชื่อธนาคารที่รองรับ กรุณาดู รายการวิธีการชำระเงิน

---

ตัวอย่าง Body – คำขอธุรกรรม:

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001

{
    "payer": {
        "name": "test",
        "accountNo": "123456789009",
      "bankName": "KBANK"
    },
    "merchant": {
        "merchantId": "20001"
    },
    "money": {
        "amount": 10000,
        "currency": "THB"
    },
  "orderNo": "20001e9d98b010db244c99d457c",
    "paymentMethod": "QRPAY",
    "purpose": "วัตถุประสงค์สำหรับธุรกรรมจาก Java SDK",
    "redirectUrl": "https://docs.smilepayz.com/en/"
}

Response

การตอบสนอง HTTP

ฟิลด์	จำเป็น	ประเภท	คำอธิบาย
Content-Type	M	String	ข้อกำหนดประเภทเนื้อหาการตอบสนอง HTTP ค่าคงที่: application/json ระบุรูปแบบการตอบสนอง JSON
X-TIMESTAMP	M	String	รูปแบบวันที่เวลา ISO 8601 พร้อมออฟเซ็ตเขตเวลา รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00

พารามิเตอร์เนื้อหา

ฟิลด์	จำเป็น	ประเภท	คำอธิบาย
code	M	String	รหัสสถานะการตอบสนอง API ที่ระบุผลลัพธ์การดำเนินการ รูปแบบ: สตริงสองหลัก สำเร็จ: "00", ข้อผิดพลาด: รหัสอื่นๆ ใช้สำหรับการจัดการการตอบสนองแบบโปรแกรม
message	M	String	คำอธิบายสถานะการตอบสนองที่อ่านได้โดยมนุษย์ รูปแบบ: สตริงที่เข้ารหัส UTF-8 ให้ข้อมูลรายละเอียดเกี่ยวกับผลลัพธ์การดำเนินการ แปลเป็นภาษาตามภาษาของคำขอ
orderNo	M	String	หมายเลขอ้างอิงธุรกรรมพ่อค้าเดิม รูปแบบ: เหมือนกับ orderNo ในคำขอ ใช้สำหรับการติดตามธุรกรรมและการตรวจสอบ
tradeNo	O	String	หมายเลขอ้างอิงธุรกรรมภายในสำหรับการติดตามระบบ รูปแบบ: สตริงตัวอักษรและตัวเลขที่สร้างโดยระบบ ใช้สำหรับการจัดการธุรกรรมภายในและการสนับสนุน
merchant	M	Object	ภาชนะข้อมูลพ่อค้าพร้อมรายละเอียดบัญชี ประกอบด้วยการระบุตัวตนพ่อค้าและข้อมูลบัญชี ดู โมเดลพ่อค้า
merchantId	M	String	ตัวระบุพ่อค้าหลักที่กำหนดโดยแพลตฟอร์ม รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้สำหรับการเส้นทางธุรกรรมและการประมวลผลการชำระบัญชี
merchantName	O	String	ชื่อธุรกิจที่ลงทะเบียนของพ่อค้า รูปแบบ: สตริงที่เข้ารหัส UTF-8 แสดงในอินเทอร์เฟซการชำระเงินและบันทึกธุรกรรม
subMerchantId	O	String	ตัวระบุพ่อค้าย่อยสำหรับโครงสร้างพ่อค้าหลายระดับ รูปแบบ: สตริงตัวอักษรและตัวเลข จำเป็นสำหรับการประมวลผลธุรกรรมพ่อค้าย่อย
subMerchantName	O	String	ชื่อธุรกิจพ่อค้าย่อยสำหรับการแสดงผล รูปแบบ: สตริงที่เข้ารหัส UTF-8 แสดงในอินเทอร์เฟซการชำระเงินและบันทึกธุรกรรม
money	M	Object	รายละเอียดจำนวนธุรกรรมพร้อมข้อกำหนดสกุลเงิน ประกอบด้วยจำนวนการชำระเงินที่ยืนยันและสกุลเงิน ดู โมเดลเงิน
currency	M	String	ข้อกำหนดรหัสสกุลเงิน ISO 4217 ค่าคงที่: THB (บาทไทย) กำหนดกฎการประมวลผลการชำระเงินและสกุลเงินการชำระบัญชี
amount	M	Number	จำนวนธุรกรรมในหน่วยสกุลเงินที่เล็กที่สุด รูปแบบ: ค่าจำนวนเต็ม ตัวอย่าง: 200 แทน THB 200.00 ช่วง: 100-999999999
payAmount	O	Number	จำนวนการชำระเงินจริงหลังหักค่าธรรมเนียมและการปรับปรุง รูปแบบ: ค่าทศนิยม ตัวอย่าง: 199.98 แทน THB 199.98 ใช้สำหรับการคำนวณการชำระบัญชี
transactionTime	M	String	รูปแบบวันที่เวลา ISO 8601 (yyyy-MM-ddTHH:mm:ss±HH:mm) ตัวอย่าง: 2020-12-17T10:55:00+07:00 เวลาที่ระบบประมวลผลธุรกรรม
channel	M	Object	รายละเอียดช่องทางการประมวลผลการชำระเงินและคำแนะนำ ประกอบด้วยวิธีการชำระเงิน URL และข้อมูลเพิ่มเติม ดู โมเดลช่องทาง
status	O	String	สถานะการประมวลผลธุรกรรมปัจจุบัน รูปแบบ: รหัสสถานะที่กำหนดไว้ล่วงหน้า ตัวอย่าง: PROCESSING, SUCCESS, FAILED ดู โมเดลสถานะ

Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00

{
    "channel": {
        "additionalInfo": {},
        "paymentMethod": "QRPAY",
        "paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=111200572411191251468673",
        "qrString": "00020101021229370016A0000006770101110113006680870163353037645406299.985802TH63048436"
    },
    "merchant": {
        "accountNo": "11120001202406101410",
        "merchantId": "20001",
        "merchantName": "test"
    },
    "money": {
        "amount": 300,
        "payAmount": 299.98,
        "currency": "THB"
    },
    "orderNo": "878d95fe75ef4c49b11d266afa8dd849",
    "status": "PROCESSING",
    "tradeNo": "111200012411191251468673",
    "transactionTime": "2024-11-19T12:51:47+07:00"
}

{
    "channel": {
        "additionalInfo": {},
        "paymentMethod": "BANK",
      "paymentUrl": "https://gateway.smilepayz.com/cashier/#/loading?tradeNo=1112001125042408363186433",
      "receiverBankName": "KBANK",
      "vaNumber": "2053617290"
    },
    "code": "00",
    "merchant": {
        "accountNo": "11120011202402290943",
        "merchantId": "20011",
        "merchantName": "bradytest123www"
    },
    "message": "Successful",
    "money": {
        "amount": 100,
        "payAmount": 99.99,
        "currency": "THB"
    },
    "orderNo": "20011b5baff0ed8ac4f0c873920e",
    "status": "PROCESSING",
    "tradeNo": "1112001125042408363186433",
    "transactionTime": "2025-04-24T08:36:32+07:00"
}

แจ้งเตือน

คำขอ HTTP

ฟิลด์	จำเป็น	ประเภท	คำอธิบาย
Content-Type	M	String	ข้อกำหนดประเภทเนื้อหา HTTP สำหรับการแจ้งเตือน ค่าคงที่: application/json ระบุรูปแบบข้อมูล JSON
X-TIMESTAMP	M	String	รูปแบบวันที่เวลา ISO 8601 พร้อมออฟเซ็ตเขตเวลา รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00
X-SIGNATURE	M	String	ลายเซ็นดิจิทัลสำหรับการยืนยันการแจ้งเตือน รูปแบบ: ลายเซ็นที่เข้ารหัส Base64 ใช้เพื่อยืนยันความถูกต้องของการแจ้งเตือน ดู วิธีตรวจสอบค่านี้

พารามิเตอร์เนื้อหา

ฟิลด์	จำเป็น	ประเภท	คำอธิบาย
orderNo	M	String	หมายเลขอ้างอิงธุรกรรมพ่อค้าเดิมสำหรับการอ้างอิง รูปแบบ: เหมือนกับ orderNo ในคำขอ ใช้สำหรับการตรวจสอบและติดตามธุรกรรม
tradeNo	M	String	หมายเลขอ้างอิงธุรกรรมภายในสำหรับการติดตามระบบ รูปแบบ: สตริงตัวอักษรและตัวเลขที่สร้างโดยระบบ ใช้สำหรับการจัดการธุรกรรมภายในและการสนับสนุน
merchantId	M	String	ตัวระบุพ่อค้าหลักสำหรับการเส้นทางธุรกรรม รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้สำหรับการระบุตัวตนพ่อค้าและการประมวลผลการชำระบัญชี
merchantName	M	String	ชื่อธุรกิจที่ลงทะเบียนของพ่อค้าสำหรับการแสดงผล รูปแบบ: สตริงที่เข้ารหัส UTF-8 แสดงในบันทึกธุรกรรมและรายงาน
subMerchantId	O	String	ตัวระบุพ่อค้าย่อยสำหรับโครงสร้างหลายระดับ รูปแบบ: สตริงตัวอักษรและตัวเลข รวมเมื่อพ่อค้าย่อยเกี่ยวข้องกับธุรกรรม
subMerchantName	O	String	ชื่อธุรกิจพ่อค้าย่อยสำหรับการแสดงผล รูปแบบ: สตริงที่เข้ารหัส UTF-8 รวมเมื่อพ่อค้าย่อยเกี่ยวข้องกับธุรกรรม
paymentMethod	M	String	วิธีการชำระเงินที่ใช้สำหรับการประมวลผลธุรกรรม รูปแบบ: รหัสวิธีการชำระเงินที่กำหนดไว้ล่วงหน้า ตัวอย่าง: QRPAY, BANK ระบุช่องทางการชำระเงินที่ใช้จริง
transactionTime	M	String	รูปแบบวันที่เวลา ISO 8601 (yyyy-MM-ddTHH:mm:ss±HH:mm) เวลาที่ผู้ให้บริการการชำระเงินเสร็จสิ้นธุรกรรม
status	M	String	สถานะการประมวลผลธุรกรรมสุดท้าย รูปแบบ: รหัสสถานะที่กำหนดไว้ล่วงหน้า ตัวอย่าง: SUCCESS, FAILED ระบุผลลัพธ์สุดท้ายของธุรกรรม ดู โมเดลสถานะ
money	M	Object	รายละเอียดจำนวนธุรกรรมสุดท้ายพร้อมสกุลเงิน ประกอบด้วยจำนวนการชำระเงินที่ยืนยันและสกุลเงิน อาจแตกต่างจากจำนวนคำขอเนื่องจากค่าธรรมเนียมหรือการปรับปรุง ดู โมเดลเงิน
currency	M	String	ข้อกำหนดรหัสสกุลเงิน ISO 4217 ค่าคงที่: THB (บาทไทย) กำหนดกฎการประมวลผลการชำระเงินและสกุลเงินการชำระบัญชี
amount	M	Number	จำนวนธุรกรรมในหน่วยสกุลเงินที่เล็กที่สุด รูปแบบ: ค่าจำนวนเต็ม ตัวอย่าง: 200 แทน THB 200.00 ช่วง: 100-999999999
payAmount	O	Number	จำนวนการชำระเงินจริงหลังหักค่าธรรมเนียมและการปรับปรุง รูปแบบ: ค่าทศนิยม ตัวอย่าง: 199.98 แทน THB 199.98 ใช้สำหรับการคำนวณการชำระบัญชี
payer	M	Object	ข้อมูลลูกค้าที่ให้ระหว่างการชำระเงิน รูปแบบ: วัตถุข้อมูลลูกค้า ประกอบด้วยรายละเอียดผู้จ่ายเงินเมื่อพร้อมใช้งาน ดู โมเดลผู้จ่ายเงิน

การคืนค่า

สำคัญ

การแจ้งเตือนกรุณาคืนเฉพาะสตริง SUCCESS

{
  "merchantId": "20001",
  "merchantName": "test",
  "money": {
    "amount": 150,
    "currency": "THB"
  },
  "orderNo": "20001f7d65167e8b1419896f2dfb",
  "payer": {
    "name": "payerName",
    "accountNo": "*****25432"
  },
  "paymentMethod": "QRPAY",
  "status": "SUCCESS",
  "tradeNo": "111200012412151710505955",
  "transactionTime": "2024-12-15T17:10:51"
}

SUCCESS