API การชำระเงินใช้งานได้เฉพาะในแผน Business เท่านั้น การใช้ API การชำระเงินมีค่าธรรมเนียม 8 บาทต่อธุรกรรม ระบบจะหักค่าธรรมเนียมนี้จากยอดคงเหลือของบัญชี Bukza ของคุณ
คุณสามารถเชื่อมต่อบริการชำระเงินใดก็ได้กับ Bukza โดยใช้ API การชำระเงิน ในการเชื่อมต่อนี้ คุณต้องมีเซิร์ฟเวอร์ของตนเองที่ทำหน้าที่เป็นตัวกลางระหว่าง Bukza กับบริการชำระเงินของคุณ จำเป็นต้องมีทักษะการเขียนโปรแกรม
กรุณาทราบว่า API นี้อาจมีการเปลี่ยนแปลงในอนาคต
หากต้องการเปิดใช้งาน API การชำระเงิน ให้ส่งคำขอไปที่
support@bukza.com ในข้อความ ให้ระบุ URL ของเซิร์ฟเวอร์ของคุณที่ Bukza จะส่งคำขอไป เราจะส่ง User ID ของคุณและคีย์สำหรับสร้างค่าแฮชของลายเซ็นให้คุณ
คุณสามารถดูตัวอย่างซอร์สโค้ด JavaScript ในโปรแกรมแก้ไขโค้ดออนไลน์ได้
ที่นี่ หากต้องการทดสอบตัวอย่างนี้กับบัญชีของคุณ ให้ทำตามขั้นตอนต่อไปนี้:
- ลงทะเบียนที่ Glitch
- สร้างรีมิกซ์ของตัวอย่างการเชื่อมต่อของเราที่นี่ โดยคลิกปุ่ม "Remix" ระบบจะสร้างแอปพลิเคชันของคุณเองที่มีซอร์สโค้ดเดียวกัน
- จากนั้นเปิด TERMINAL ใน Glitch แล้วเรียกใช้คำสั่ง: npm ci ระบบจะติดตั้งแพ็กเกจที่จำเป็น
- ส่งอีเมลถึงเราที่ support@bukza.com พร้อมที่อยู่ของแอปพลิเคชันใหม่ของคุณ เราจะตั้งค่าที่อยู่นี้เป็น URL ของเซิร์ฟเวอร์ของคุณ และส่ง bukza_user_id และ bukza_key ให้คุณ
- เปิดไฟล์ .env ของแอปพลิเคชันของคุณ แล้วกรอกค่า bukza_user_id และ bukza_key ผู้ใช้ Glitch คนอื่นจะมองไม่เห็นไฟล์นี้
- ไปที่บัญชี Bukza ของคุณ ใน "การรับชำระเงิน" ให้เลือก "รับคำสั่งซื้อประเภทนี้" ในส่วน "คำสั่งซื้อที่มีการประมวลผลการชำระเงินอัตโนมัติ" และตั้งยอดชำระล่วงหน้าที่ต้องการ
- สั่งซื้อผ่านวิดเจ็ต โดยต้องใช้อีเมลของบัญชีคุณ เมื่อคุณใช้อีเมลของบัญชีในการสั่งซื้อ จะไม่มีการคิดค่าธรรมเนียมใด ๆ สำหรับการใช้ API การชำระเงิน
- ระหว่างการทดสอบ ให้ดูแท็บ "Logs" ใน Glitch ในแท็บนี้คุณจะพบบันทึกของคำขอที่ได้รับและที่ส่งออกไป
- เขียนส่วนแสดงแบบฟอร์มการชำระเงินและส่วนจัดการการตอบกลับจากระบบชำระเงินของคุณในไฟล์ server.js และ index.hbs ห้ามใส่คีย์หรือรหัสผ่านของคุณในไฟล์ใดนอกจากไฟล์ .env ผู้ใช้ Glitch คนอื่นสามารถเข้าถึงไฟล์ของโปรเจกต์และประวัติการเปลี่ยนแปลงทั้งหมดของไฟล์ได้
คุณสามารถใช้ตัวเลือกใดตัวเลือกหนึ่งจาก 2 ตัวเลือกต่อไปนี้ได้:
- "แบบกันวงเงิน" ตัวเลือกนี้ช่วยป้องกันการจองเกินจำนวน เมื่อคำสั่งซื้อเสร็จสมบูรณ์ ขั้นแรกระบบจะกันยอดเงินไว้บนบัตร จากนั้นเราจะตรวจสอบว่าคำสั่งซื้อยังจองได้และราคาไม่เปลี่ยนแปลง หากคำสั่งซื้อจองไม่ได้แล้ว ระบบจะยกเลิกการกันวงเงินทันที
ตัวเลือกการเชื่อมต่อนี้ช่วยให้คุณเรียกเก็บเงินด้วยตนเองในภายหลังได้ คุณสามารถตรวจสอบการจองด้วยตนเอง แล้วเลือกเรียกเก็บเงินหรือยกเลิกการกันวงเงินได้
- "โหมดแบบง่าย" ตัวเลือกนี้ไม่ใช้การกันวงเงิน ในกรณีนี้ ระบบจะเรียกเก็บเงินทันทีเมื่อคำสั่งซื้อเสร็จสมบูรณ์ เรายังคงตรวจสอบว่าคำสั่งซื้อยังจองได้และยอดเงินถูกต้อง หากพบปัญหา ระบบจะเพิ่มคำเตือนสำหรับผู้จัดการไว้ในข้อความ "คำสั่งซื้อใหม่"
ใช้ตัวเลือกนี้หากบริการชำระเงินของคุณไม่รองรับการกันวงเงิน
คำขอจะมีพารามิเตอร์ต่อไปนี้เสมอ:
- userId คือ ID ของคุณในระบบ Bukza เช่น 11223
- orderNumber คือหมายเลขคำสั่งซื้อใน Bukza เช่น "574285869"
- command คือชื่อคำสั่งที่ต้องเรียกใช้ ค่าที่เป็นไปได้: "GetPaymentData" "CaptureCallback" "AuthorizeCallback" "Cancel" "Capture" หรือ "Refund"
- data คือข้อมูลเพิ่มเติมของคำสั่ง เช่น หมายเลขธุรกรรมในระบบชำระเงินของคุณ: "18493853499"
- amount คือจำนวนเงินที่ชำระ เช่น 99.75
- timestamp คือจำนวนวินาทีนับตั้งแต่จุดเริ่มต้นของเวลา Unix เช่น 1596706182 ดูตัวอย่างในภาษาโปรแกรมต่าง ๆ ได้ที่: https://www.epochconverter.com
หากต้องการสร้างหรือตรวจสอบลายเซ็นของคำขอ ให้นำพารามิเตอร์ทั้งหมดนี้มาต่อกันเป็นสตริงเดียว (โดยไม่มีช่องว่างหรือเครื่องหมายบวก) คำนวณ HMAC SHA256 ด้วยคีย์ของคุณ แล้วแปลงผลลัพธ์เป็นสตริง base64:
hash = base64(hmacSha256(userId + orderNumber + command + data + amount + timestamp), key);
หมายเหตุสำคัญ:
- เมื่อแปลงค่า amount เป็นสตริง ให้ใช้จุดเป็นตัวคั่นทศนิยมหากมีเศษทศนิยม
- เมื่อได้รับคำขอ Bukza จะตรวจสอบว่า timestamp ตรงกับเวลาปัจจุบันของเซิร์ฟเวอร์และต่างกันไม่เกิน 5 นาที
- เมื่อได้รับคำขอจาก Bukza เราแนะนำให้คุณตรวจสอบ hash และ timestamp ในลักษณะเดียวกันด้วย
1.1. เมื่อคำสั่งซื้อเสร็จสมบูรณ์ Bukza จะส่งคำขอ POST ไปยัง URL ของเซิร์ฟเวอร์ของคุณ โดยมีเนื้อหาคำขอดังนี้:
{
userId:11223,
orderNumber:"574285869",
command: "GetPaymentData",
data: "",
amount: 99.75,
timestamp: 1596706182,
hash: "p2t1xcpBiXLPPDdB129vUctRAgGbzQgRcnX4IiZ0bNE="
email: "john@example.com",
phone: "+11111111111",
culture = "en",
checkStateToken = "eyJVc2VySWQiOjIsIk9yZGVyS...Ws9In0%3D"
}
ในการตอบกลับคำขอนี้ คุณต้องส่งข้อมูลในรูปแบบต่อไปนี้:
{
url: "https://yoursite.ru/amount=99.75&orderNumber=574285869&bukzaCulture=ru&bukzaUser=11223&bukzaCheckStateToken=eyJVc2VySWQiOjIsIk9yZ",
redirect: false
}
- url คือที่อยู่ของหน้าชำระเงินที่สร้างขึ้น หน้านี้อาจอยู่บนเซิร์ฟเวอร์ของคุณหรือบนเซิร์ฟเวอร์ของเกตเวย์การชำระเงินของคุณก็ได้
- redirect กำหนดว่าจะเปลี่ยนเส้นทางลูกค้าไปยัง URL ที่ระบุแบบเต็มหน้าหรือไม่ หากตั้งค่าเป็น false แบบฟอร์มการชำระเงินจะแสดงภายในวิดเจ็ตใน iframe คุณสามารถปรับขนาดของ iframe ได้ด้วย CSS ในการตั้งค่าวิดเจ็ต
- ระบบจะเพิ่ม checkStateToken ลงใน url เป็นพารามิเตอร์ bukzaCheckStateToken พารามิเตอร์นี้ช่วยให้คุณตรวจสอบสถานะคำสั่งซื้อบนหน้าชำระเงินของคุณได้ อ่านเพิ่มเติมได้ที่นี่
1.2. จากนั้นลูกค้าจะเห็นแบบฟอร์มการชำระเงินของคุณและชำระเงิน เซิร์ฟเวอร์ของคุณควรได้รับการแจ้งเตือนจากเกตเวย์การชำระเงิน เมื่อได้รับการแจ้งเตือนนี้แล้ว ให้ส่งคำขอ POST ไปยัง
https://public.bukza.com/api/pay ทันที เนื้อหาคำขอ:
{
userId:11223,
orderNumber:"574285869",
command: "AuthorizeCallback",
data: "18493853499",
amount: 99.75,
timestamp: 1596706182,
hash: "2kkjjx/grcar6B9yknqUMP6eOdMw4yJwa60Uc8fisNA=",
comment: "หมายเหตุใด ๆ เกี่ยวกับการชำระเงิน ข้อความนี้จะแสดงในหน้าผู้จัดการ และไม่ใช้ในการคำนวณลายเซ็นของคำขอ"
}
1.3. Bukza อาจทำอย่างใดอย่างหนึ่งต่อไปนี้ ขึ้นอยู่กับความพร้อมให้จองของคำสั่งซื้อและพารามิเตอร์การประมวลผล: ยกเลิกการกันวงเงิน เรียกเก็บเงินทันที หรือทำให้คำสั่งซื้อเสร็จสมบูรณ์โดยยังคงกันวงเงินไว้ ในกรณีหลัง คุณสามารถยกเลิกการชำระเงินหรือเรียกเก็บเงินได้ด้วยตนเองในหน้าผู้จัดการ ในทุกกรณี Bukza จะส่งคำขอไปยังเซิร์ฟเวอร์ของคุณ แล้วคุณต้องส่งต่อคำขอเหล่านั้นไปยังเกตเวย์การชำระเงินของคุณ
หากต้องยกเลิกการกันวงเงิน Bukza จะส่งคำขอที่มีเนื้อหาต่อไปนี้ถึงคุณ:
{
userId:11223,
orderNumber:"574285869",
command: "Cancel",
data: "18493853499",
amount: 99.75,
timestamp: 1596706182,
hash: "ejIS+AiPRSH9qXV/bBcAf7OSViCVUtj/hYPsL4aYpNM="
email: "john@example.com",
phone: "+11111111111",
}
หากต้องเรียกเก็บเงินที่กันวงเงินไว้ Bukza จะส่งคำขอที่มีเนื้อหาต่อไปนี้ถึงคุณ:
{
userId:11223,
orderNumber:"574285869",
command: "Capture",
data: "18493853499",
amount: 99.75,
timestamp: 1596706182,
hash: "JE4fRRLObEzCYk7aRFaW81DZw3sTXTOXsEcq3r8zm+Y="
email: "john@example.com",
phone: "+11111111111",
}
คุณต้องตอบกลับคำขอเหล่านี้ทุกคำขอด้วยรหัสสถานะ HTTP 200 (SUCCESS)
2.1. เมื่อคำสั่งซื้อเสร็จสมบูรณ์ Bukza จะส่งคำขอ POST ไปยัง URL ของเซิร์ฟเวอร์ของคุณเช่นกัน เหมือนในขั้นตอนที่ 1.1
2.2. จากนั้นลูกค้าจะเห็นแบบฟอร์มการชำระเงินของคุณและชำระเงิน เซิร์ฟเวอร์ของคุณควรได้รับการแจ้งเตือนจากเกตเวย์การชำระเงิน เมื่อได้รับการแจ้งเตือนนี้แล้ว ให้ส่งคำขอ POST ไปยัง
https://public.bukza.com/api/pay ทันที เนื้อหาคำขอ:
{
userId:11223,
orderNumber:"574285869",
command: "CaptureCallback",
data: "18493853499",
amount: 99.75,
timestamp: 1596706182,
hash: "eUKOwld1sEK3axhF9ZAy0WugXMJW+9nrs4BRlvnCeb0=",
comment: "หมายเหตุใด ๆ เกี่ยวกับการชำระเงิน ข้อความนี้จะแสดงในหน้าผู้จัดการ และไม่ใช้ในการคำนวณลายเซ็นของคำขอ"
}
คุณสามารถคืนเงินสำหรับการชำระเงินรายการใดรายการหนึ่งได้ในหน้าผู้จัดการ การคืนเงินอาจเป็นแบบเต็มจำนวนหรือบางส่วนก็ได้ เมื่อมีการคืนเงิน Bukza จะส่งคำขอไปยังเซิร์ฟเวอร์ของคุณ จากนั้นคุณต้องส่งคำขอที่สอดคล้องกันไปยังเกตเวย์การชำระเงินของคุณ เนื้อหาคำขอจาก Bukza:
{
userId:11223,
orderNumber:"574285869",
command: "Refund",
data: "18493853499",
amount: 50.75,
timestamp: 1596706182,
hash: "E62WH04cKUjAvQ0dmirYMc16mCGN96YyQfrft8vLj0A="
email: "john@example.com",
phone: "+11111111111",
}
คุณต้องตอบกลับคำขอเหล่านี้ทุกคำขอด้วยรหัสสถานะ HTTP 200 (SUCCESS)