API การทำรายการรับเงิน (Pay-In)
About 3 min
Request
Pay-In API เปิดให้ร้านค้าสามารถเริ่มต้นธุรกรรมการรับเงินจากลูกค้าได้ API นี้รองรับวิธีการชำระเงินด้วยคริปโทเคอร์เรนซีหลายประเภท เพื่อให้การรับและจัดการสินทรัพย์ดิจิทัลมีความปลอดภัยและมีประสิทธิภาพ
Request Path:
sandbox:
https://sandbox-gateway.smilepayz.com/v2.0/transaction/pay-in
production:https://gateway.smilepayz.com/v2.0/transaction/pay-in
Header Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | ระบุประเภทข้อมูลของ HTTP ค่าคงที่: application/json จำเป็นสำหรับการแปลงและประมวลผลคำขอให้ถูกต้อง |
| X-TIMESTAMP | M | String | วันที่และเวลาในรูปแบบ ISO 8601 พร้อมส่วนต่างของเขตเวลา (timezone offset) รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00 หมายเหตุ: ต้องเป็นเวลาปัจจุบันใกล้เคียงกับเวลาเซิร์ฟเวอร์ (±5 นาที) |
| X-SIGNATURE | M | String | ลายเซ็นดิจิทัลสำหรับยืนยันความถูกต้องของคำขอ (request authentication) ดูรายละเอียดที่ Signature Generation |
| X-PARTNER-ID | M | String | รหัสร้านค้าที่ยูนีค ซึ่งออกให้โดยระบบแพลตฟอร์ม รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้เพื่อยืนยันตัวตนร้านค้าและกำหนดเส้นทางของธุรกรรม โปรดกรอกค่า merchantID |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| orderNo | M | String(32) | หมายเลขอ้างอิงธุรกรรมที่ไม่ซ้ำกัน รูปแบบ: สตริงตัวอักษรและตัวเลข (ตัวเลขและตัวอักษรเท่านั้น) ความยาว: 6-32 ตัวอักษร ใช้สำหรับติดตามและอ้างอิงธุรกรรม |
| purpose | M | String(64) | วัตถุประสงค์หรือคำอธิบายของธุรกรรม รูปแบบ: สตริงเข้ารหัส UTF-8 ความยาวสูงสุด: 64 ตัวอักษร ใช้เพื่ออ้างอิงและรายงานธุรกรรม |
| merchant | M | Object | ข้อมูลร้านค้า ประกอบด้วยข้อมูลระบุตัวตนและรายละเอียดทางธุรกิจของร้านค้า ดูรายละเอียดที่ Merchant Model |
| merchantId | M | String | รหัสร้านค้าที่ยูนีค ซึ่งออกให้โดยแพลตฟอร์ม รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้เพื่อยืนยันตัวตนร้านค้าและกำหนดเส้นทางธุรกรรม |
| merchantName | O | String | ชื่อธุรกิจหรือชื่อที่แสดงของร้านค้า รูปแบบ: สตริงเข้ารหัส UTF-8 ใช้เพื่อระบุและรายงานร้านค้า |
| subMerchantId | O | String | รหัสซับเมอร์ชันต์ สำหรับโครงสร้างร้านค้ามากกว่าหนึ่งระดับ รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้เพื่อระบุและรายงานซับเมอร์ชันต์ |
| subMerchantName | O | String | ชื่อธุรกิจหรือชื่อที่แสดงของซับเมอร์ชันต์ รูปแบบ: สตริงเข้ารหัส UTF-8 ใช้เพื่อระบุและรายงานซับเมอร์ชันต์ |
| money | M | Object | รายละเอียดจำนวนเงินของธุรกรรมพร้อมสกุลเงิน ประกอบด้วยจำนวนเงินและข้อมูลสกุลเงินของธุรกรรม ดู Money Model |
| currency | M | String | รหัสสกุลเงินตามมาตรฐาน ISO 4217 ค่าคงที่: USDT (Tether USD) ใช้กำหนดกติกาการประมวลผลการชำระเงินและสกุลเงินในการรับเงิน |
| amount | M | Number | จำนวนเงินของธุรกรรมในหน่วยย่อยที่สุดของสกุลเงิน รูปแบบ: จำนวนเต็ม ตัวอย่าง: 10000 หมายถึง USDT 10000 ช่วงที่รองรับ: 100-999999999 |
| network | M | String | เครือข่ายบล็อกเชนที่ใช้สำหรับสกุลเงินดิจิทัล รูปแบบ: รหัสเครือข่ายที่กำหนดไว้ล่วงหน้า ตัวอย่าง: ERC20, BEP20, TRC20 ระบุเครือข่ายบล็อกเชนที่ใช้ประมวลผลธุรกรรม |
| productDetail | O | String(128) | รายละเอียดสินค้า หรือบริการ รูปแบบ: สตริงเข้ารหัส UTF-8 ความยาวสูงสุด: 128 ตัวอักษร ใช้เพื่อระบุและรายงานธุรกรรม |
| paymentMethod | O | String | วิธีการชำระเงินที่ใช้ในธุรกรรม รูปแบบ: รหัสวิธีการชำระเงินที่กำหนดไว้ล่วงหน้า ตัวอย่าง: USDT, BTC, ETH ใช้ระบุช่องทางการชำระเงินจริงที่ใช้ ดู Payment Method List |
| expiryPeriod | O | Number | ระยะเวลาหมดอายุของธุรกรรม (วินาที) รูปแบบ: จำนวนเต็ม ค่าเริ่มต้น: 3600 (1 ชั่วโมง) ค่าสูงสุด: 86400 (24 ชั่วโมง) ใช้กำหนดช่วงเวลาที่คำสั่งชำระเงินยังคงมีผล |
| redirectUrl | O | String(256) | URL ที่ใช้เปลี่ยนเส้นทางลูกค้าหลังชำระเงินเสร็จสิ้น รูปแบบ: URL แบบ HTTP/HTTPS ที่ถูกต้อง ความยาวสูงสุด: 256 ตัวอักษร ใช้เพื่อเปลี่ยนเส้นทางลูกค้าไปยังหน้าที่ต้องการหลังการประมวลผลการชำระเงิน |
| callbackUrl | O | String(256) | URL สำหรับ Webhook เพื่อรับการแจ้งเตือนสถานะธุรกรรมแบบเรียลไทม์ รูปแบบ: URL แบบ HTTP/HTTPS ที่ถูกต้อง ความยาวสูงสุด: 256 ตัวอักษร ใช้สำหรับการแจ้งเตือนอัปเดตสถานะธุรกรรม |
ข้อมูลสำคัญ
1. Transaction ID:
orderNoต้องมีค่าไม่ซ้ำกันในทุกธุรกรรมของร้านค้านั้น
2. Amount Format: ต้องส่งจำนวนเงินในหน่วยย่อยที่สุดของสกุลเงิน (เช่น เซนต์ของ USDT)
3. Timezone: เวลาทั้งหมดใช้เขตเวลา UTC+7
4. Network Selection: เลือกเครือข่ายบล็อกเชนให้เหมาะสมตามความต้องการของลูกค้าและต้นทุนค่าธรรมเนียมธุรกรรม
5. Payment Method: หากไม่ได้ระบุ ระบบ Smilepayz จะส่งหน้าชำระเงินที่แสดงตัวเลือกการชำระเงินทั้งหมดที่ใช้ได้
6. Expiration: ธุรกรรมจะหมดอายุโดยอัตโนมัติ หากไม่ได้ชำระเงินให้เสร็จสิ้นภายในเวลาที่กำหนด
Example Body – Transaction Request:
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
X-SIGNATURE: 7MHd9v5/m9JeqmDZVwWBZUZ5J5...7120QnFEny7Qm7uQR1G0TWCh10fsU6nVxiRoeoQ==
X-PARTNER-ID: 20001
{
"network": "TRC20",
"merchant": {
"merchantId": "20001",
"merchantName": "Smilepayz"
},
"payer": {
"phone": "0823239232823",
"email": "[email protected]"
},
"money": {
"amount": 10000,
"currency": "USDT"
},
"orderNo": "20001e9d98b01-0db2-44c9-9d45-7c",
"paymentMethod": "WALLET",
"purpose": "Payment for digital services",
"redirectUrl": "https://docs.smilepayz.com/en/"
}
Response
HTTP Response
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | ระบุประเภทข้อมูลของ HTTP Response ค่าคงที่: application/json แสดงว่าข้อมูลตอบกลับอยู่ในรูปแบบ JSON |
| X-TIMESTAMP | M | String | วันที่และเวลาในรูปแบบ ISO 8601 พร้อมส่วนต่างของเขตเวลา (timezone offset) รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00 |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| code | M | String | รหัสผลลัพธ์ของ API ใช้ระบุผลการทำงาน รูปแบบ: สตริง 2 หลัก สำเร็จ: "00", อื่น ๆ หมายถึงข้อผิดพลาด ใช้สำหรับประมวลผลผลลัพธ์เชิงโปรแกรม (programmatic handling) |
| message | M | String | ข้อความบรรยายผลลัพธ์ของการทำงานของ API ในรูปแบบที่มนุษย์อ่านเข้าใจได้ รูปแบบ: สตริงเข้ารหัส UTF-8 อธิบายรายละเอียดเพิ่มเติมเกี่ยวกับผลการทำงาน อาจถูกแปลตามภาษาที่ร้องขอ |
| orderNo | M | String | หมายเลขอ้างอิงธุรกรรมที่ร้านค้าส่งมาในคำขอ รูปแบบ: สตริงตัวอักษรและตัวเลข มีค่าเหมือนกับ orderNo ที่ส่งในคำขอเดิมใช้สำหรับติดตามและอ้างอิงธุรกรรม |
| merchant | M | Object | ข้อมูลร้านค้า ประกอบด้วยข้อมูลระบุตัวตนและรายละเอียดทางธุรกิจของร้านค้า ดู Merchant Model |
| merchantId | M | String | รหัสร้านค้าที่ยูนีค ซึ่งออกให้โดยแพลตฟอร์ม รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้เพื่อยืนยันตัวตนร้านค้าและกำหนดเส้นทางธุรกรรม |
| merchantName | O | String | ชื่อธุรกิจหรือชื่อที่แสดงของร้านค้า รูปแบบ: สตริงเข้ารหัส UTF-8 ใช้เพื่อระบุและรายงานร้านค้า |
| subMerchantId | O | String | รหัสซับเมอร์ชันต์ สำหรับโครงสร้างร้านค้าที่มีหลายระดับ รูปแบบ: สตริงตัวอักษรและตัวเลข ใช้เพื่อระบุและรายงานซับเมอร์ชันต์ |
| subMerchantName | O | String | ชื่อธุรกิจหรือชื่อที่แสดงของซับเมอร์ชันต์ รูปแบบ: สตริงเข้ารหัส UTF-8 ใช้เพื่อระบุและรายงานซับเมอร์ชันต์ |
| money | M | Object | รายละเอียดจำนวนเงินของธุรกรรมพร้อมสกุลเงินที่ยืนยันแล้ว ประกอบด้วยจำนวนเงินสุดท้ายและข้อมูลสกุลเงิน ดู Money Model |
| currency | M | String | รหัสสกุลเงินตามมาตรฐาน ISO 4217 ค่าคงที่: USDT (Tether USD) ใช้กำหนดกติกาการประมวลผลและสกุลเงินในการรับเงิน |
| amount | M | Number | จำนวนเงินของธุรกรรมในหน่วยย่อยที่สุดของสกุลเงิน รูปแบบ: จำนวนเต็ม ตัวอย่าง: 10000 หมายถึง USDT 10000 ช่วงที่รองรับ: 100-999999999 |
| transactionTime | M | String | เวลาที่ทำธุรกรรมเสร็จสิ้น รูปแบบ: yyyy-MM-ddTHH:mm:ss ตัวอย่าง: 2020-12-17T10:55:00+07:00 ใช้สำหรับติดตามเวลาและการตรวจสอบย้อนหลัง (audit) |
| channel | M | Object | ข้อมูลช่องทางการชำระเงิน ประกอบด้วยวิธีการชำระเงินและรายละเอียดการประมวลผล ดู Channel Model |
| tradeNo | O | String | หมายเลขอ้างอิงธุรกรรมภายในระบบ สำหรับการติดตามภายใน รูปแบบ: สตริงตัวอักษรและตัวเลขที่ระบบสร้างให้ ใช้สำหรับการจัดการธุรกรรมภายในและการสนับสนุน (support) |
| status | O | String | สถานะการประมวลผลของธุรกรรมในปัจจุบัน รูปแบบ: รหัสสถานะที่กำหนดไว้ล่วงหน้า ตัวอย่าง: PROCESSING, SUCCESS, FAILED, CANCELLED ใช้แสดงสถานะปัจจุบันของธุรกรรม ดู Status Model |
Content-type: application/json
X-TIMESTAMP: 2020-12-17T10:55:00+07:00
{
"channel": {
"paymentMethod": "WALLET",
"paymentUrl": "https://gateway-test.smilepayz.com/cashier/#/loading?tradeNo=3012003025112812141312194",
"cardData": {
"payeeBankCard": "TS8taf44vwibX7z4vE7aqrA7xVQjzzGKoZ",
"realAmount": 1.01,
"network": "TRC20"
}
},
"merchant": {
"accountNo": "11120001202406101410",
"merchantId": "20001",
"merchantName": "test"
},
"money": {
"amount": 300,
"currency": "USDT"
},
"orderNo": "878d95fe75ef4c49b11d266afa8dd849",
"status": "PROCESSING",
"tradeNo": "111200012411191251468673",
"transactionTime": "2024-11-19T12:51:47+07:00",
"code": "00",
"message": "Successful",
"responseCode": "2009000",
"responseMessage": "Successful"
}
Notification
HTTP Request
| Field | Required | Type | Description |
|---|---|---|---|
| Content-Type | M | String | ระบุประเภทข้อมูลของ HTTP Request ค่าคงที่: application/json แสดงว่าข้อมูลคำขออยู่ในรูปแบบ JSON |
| X-TIMESTAMP | M | String | วันที่และเวลาในรูปแบบ ISO 8601 พร้อมส่วนต่างของเขตเวลา (timezone offset) รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00 |
| X-SIGNATURE | M | String | ลายเซ็นดิจิทัลสำหรับยืนยันความถูกต้องของการแจ้งเตือน (notification authentication) ดู Callback Signature Verification |
Body Parameters
| Field | Required | Type | Description |
|---|---|---|---|
| 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 | วิธีการชำระเงินที่ใช้ในธุรกรรม รูปแบบ: รหัสวิธีการชำระเงินที่กำหนดไว้ล่วงหน้า ตัวอย่าง: USDT, BTC, ETH ใช้ระบุช่องทางการชำระเงินจริงที่ใช้ |
| transactionTime | M | String | เวลาที่ธุรกรรมเสร็จสมบูรณ์ รูปแบบ: yyyy-MM-ddTHH:mm:ss ตัวอย่าง: 2020-12-17T10:55:00+07:00 ใช้สำหรับติดตามเวลาและการตรวจสอบย้อนหลัง (audit) |
| status | M | String | สถานะสุดท้ายของการประมวลผลธุรกรรม รูปแบบ: รหัสสถานะที่กำหนดไว้ล่วงหน้า ตัวอย่าง: SUCCESS, FAILED, CANCELLED ใช้แสดงผลลัพธ์สุดท้ายของธุรกรรม ดู Status Model |
| money | M | Object | รายละเอียดจำนวนเงินของธุรกรรมพร้อมสกุลเงินที่ยืนยันแล้ว ประกอบด้วยจำนวนเงินสุดท้ายและข้อมูลสกุลเงิน ดู Money Model |
| currency | M | String | รหัสสกุลเงินตามมาตรฐาน ISO 4217 ค่าคงที่: USDT (Tether USD) ใช้กำหนดกติกาการประมวลผลและสกุลเงินในการรับเงิน |
| amount | M | Number | จำนวนเงินของธุรกรรมในหน่วยย่อยที่สุดของสกุลเงิน รูปแบบ: จำนวนเต็ม ตัวอย่าง: 10000 หมายถึง USDT 10000 ช่วงที่รองรับ: 100-999999999 |
| payer | M | Object | ข้อมูลผู้ชำระเงิน ประกอบด้วยข้อมูลระบุตัวตนและช่องทางติดต่อของลูกค้า ดู Payer Model |
Return
การตอบกลับที่สำคัญ
Notification Response: โปรดตอบกลับด้วยสตริง
SUCCESSเพียงอย่างเดียว เพื่อยืนยันว่าระบบของคุณได้รับการแจ้งเตือนแล้ว
{
"merchantId": "20001",
"merchantName": "test",
"money": {
"amount": 150,
"currency": "USDT"
},
"orderNo": "20001f7d65167e8b1419896f2dfb",
"payer": {
"name": "payerName"
},
"paymentMethod": "USDT",
"status": "SUCCESS",
"tradeNo": "111200012412151710505955",
"transactionTime": "2024-12-15T17:10:51"
}
SUCCESS