จะเชื่อมต่อบริการชำระเงินของฉันผ่าน API ได้อย่างไร?

Payment API จะใช้งานได้เฉพาะกับแผนบิสซิเนสเท่านั้น มีค่าธรรมเนียม 8 บาทต่อธุรกรรมเมื่อใช้ Payment API ค่าธรรมเนียมนี้จะถูกหักจากยอดคงเหลือบัญชี Bukza ของคุณ

คุณสามารถเชื่อมต่อบริการชำระเงินใด ๆ กับ Bukza ได้โดยใช้ Payment API ในการดำเนินการนี้ คุณจะต้องมีเซิร์ฟเวอร์ของคุณเองเพื่อทำหน้าที่เป็นตัวกลางระหว่าง Bukza กับบริการชำระเงินของคุณ จำเป็นต้องมีทักษะการเขียนโปรแกรม

โปรดทราบว่า API นี้อาจมีการเปลี่ยนแปลงในอนาคต

ฉันจะเปิดใช้งาน API ได้อย่างไร?

หากต้องการเปิดใช้งาน Payment API กรุณาส่งคำขอไปที่ support@bukza.com ในข้อความของคุณ โปรดระบุ URL ของเซิร์ฟเวอร์ที่ Bukza ควรส่งคำขอไป เราจะให้ User ID และคีย์ที่ใช้ในการสร้างลายเซ็น hash แก่คุณ

ตัวอย่างการเชื่อมต่อสำเร็จรูป

คุณสามารถดูตัวอย่างซอร์สโค้ด JavaScript ในโปรแกรมแก้ไขโค้ดออนไลน์ ที่นี่

หากต้องการทดสอบตัวอย่างนี้กับบัญชีของคุณ ให้ทำตามขั้นตอนดังนี้:

สร้างบัญชีที่ Glitch
สร้างรีมิกซ์ของตัวอย่างการเชื่อมต่อของเรา ที่นี่ โดยคลิกปุ่ม "Remix" ระบบจะสร้างแอปพลิเคชันของคุณเองโดยใช้ซอร์สโค้ดเดียวกัน
จากนั้น เปิด TERMINAL ใน Glitch และรันคำสั่ง: npm ci ระบบจะติดตั้ง dependencies ที่จำเป็น
ส่งอีเมลถึงเราที่ support@bukza.com พร้อมที่อยู่แอปพลิเคชันใหม่ของคุณ เราจะตั้งค่านี้เป็น URL เซิร์ฟเวอร์ของคุณและส่ง bukza_user_id และ bukza_key ให้คุณ
เปิดไฟล์ .env ของแอปพลิเคชันของคุณและกรอกค่า bukza_user_id และ bukza_key ไฟล์นี้จะไม่ปรากฏให้ผู้ใช้ Glitch คนอื่นเห็น
ไปที่บัญชี Bukza ของคุณ ในแบบฟอร์มการประมวลผลการชำระเงิน ให้เปิดใช้งาน "คำสั่งซื้อที่มีการประมวลผลการชำระเงินอัตโนมัติ" และตั้งค่าจำนวนเงินชำระล่วงหน้าตามที่ต้องการ
ดำเนินการสั่งซื้อผ่านวิดเจ็ต โดยใช้ที่อยู่อีเมลของบัญชีคุณ เมื่อคุณใช้ที่อยู่อีเมลของบัญชีในการสั่งซื้อ จะไม่มีการคิดค่าธรรมเนียมใด ๆ สำหรับการใช้ Payment API
ระหว่างการทดสอบ ให้ตรวจสอบแท็บ "Logs" ใน Glitch ที่นี่คุณจะพบบันทึกของคำขอที่ได้รับและส่งออก
ดำเนินการแสดงฟอร์มชำระเงินของคุณเองและจัดการการตอบกลับจากระบบชำระเงินของคุณในไฟล์ server.js และ index.hbs ห้ามใส่คีย์หรือรหัสผ่านของคุณในไฟล์ใด ๆ ยกเว้นไฟล์ .env ไฟล์โปรเจกต์และประวัติการเปลี่ยนแปลงทั้งหมดสามารถเข้าถึงได้โดยผู้ใช้ Glitch คนอื่น

ตัวเลือกการเชื่อมต่อ

คุณสามารถเลือกใช้งานได้ 1 ใน 2 ตัวเลือก:

"แบบมีการอนุมัติก่อน" — ตัวเลือกนี้ช่วยป้องกันการจองเกินจำนวน เมื่อคำสั่งซื้อเสร็จสิ้น ระบบจะทำการอนุมัติวงเงินในบัตรก่อน จากนั้นเราจะตรวจสอบว่าคำสั่งซื้อยังคงมีอยู่และราคายังไม่เปลี่ยนแปลง หากคำสั่งซื้อไม่สามารถดำเนินการได้อีกต่อไป การอนุมัติวงเงินจะถูกยกเลิกทันที

ด้วยตัวเลือกนี้ คุณสามารถเรียกเก็บเงินภายหลังได้ด้วยตนเอง คุณสามารถตรวจสอบการจองด้วยตัวเองและเลือกเรียกเก็บเงินหรือยกเลิกการอนุมัติวงเงิน
"โหมดง่าย" — ตัวเลือกนี้จะไม่ใช้การอนุมัติวงเงินล่วงหน้า ในกรณีนี้ ระบบจะเรียกเก็บเงินทันทีเมื่อคำสั่งซื้อเสร็จสิ้น เรายังคงตรวจสอบความพร้อมใช้งานและจำนวนเงินของคำสั่งซื้อ และหากมีปัญหา จะมีคำเตือนสำหรับผู้จัดการในข้อความ "คำสั่งซื้อใหม่"

ใช้ตัวเลือกนี้หากบริการชำระเงินของคุณไม่รองรับการอนุมัติวงเงินล่วงหน้า

ฉันจะสร้าง signing hash ได้อย่างไร?

พารามิเตอร์ต่อไปนี้จะถูกรวมอยู่ในคำขอเสมอ:

userId — ID ของคุณในระบบ Bukza เช่น 11223
orderNumber — หมายเลขคำสั่งซื้อใน Bukza เช่น "574285869"
command — ชื่อคำสั่งที่ต้องการดำเนินการ ค่าที่เป็นไปได้: "GetPaymentData", "CaptureCallback", "AuthorizeCallback", "Cancel", "Capture" หรือ "Refund"
data — ข้อมูลเพิ่มเติมของคำสั่ง เช่น หมายเลขธุรกรรมในระบบชำระเงินของคุณ: "18493853499"
amount — จำนวนเงินที่ชำระ เช่น 99.75
timestamp — จำนวนวินาทีตั้งแต่ Unix epoch เช่น 1596706182 ดูตัวอย่างในภาษาโปรแกรมต่าง ๆ ได้ที่: https://www.epochconverter.com

ในการสร้างหรือยืนยันลายเซ็นของคำขอ ให้นำพารามิเตอร์ทั้งหมดนี้มาต่อกันเป็นสตริงเดียว (โดยไม่เว้นวรรคหรือเครื่องหมายบวก) คำนวณ HMAC SHA256 โดยใช้คีย์ของคุณ และแปลงผลลัพธ์เป็นสตริง base64:

hash = base64(hmacSha256(userId + orderNumber + command + data + amount + timestamp), key);

ตัวอย่างการใช้งานในภาษาโปรแกรมต่าง ๆ: https://www.jokecamp.com/blog/examples-of-creating-base64-hashes-using-hmac-sha256-in-different-languages/

คุณสามารถตรวจสอบการคำนวณได้ที่นี่: http://jsfiddle.net/dwyrk513/1/

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

เมื่อต้องแปลงค่า amount เป็นสตริง ให้ใช้จุด (.) เป็นตัวคั่นทศนิยม หากมีเศษส่วน
เมื่อรับคำขอ Bukza จะตรวจสอบว่า timestamp ตรงกับเวลาปัจจุบันของเซิร์ฟเวอร์และไม่ต่างกันเกิน 5 นาที
เมื่อรับคำขอจาก Bukza เราแนะนำให้คุณตรวจสอบ hash และ timestamp ในลักษณะเดียวกัน

ตัวเลือกที่ 1 "แบบมีการอนุมัติก่อน (Pre-authorization)"

1.1. เมื่อคำสั่งซื้อเสร็จสิ้น Bukza จะส่ง POST request ไปยัง 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 — ที่อยู่ของหน้าชำระเงินที่สร้างขึ้น หน้านี้สามารถอยู่บนเซิร์ฟเวอร์ของคุณหรือเซิร์ฟเวอร์ของ payment gateway ของคุณก็ได้
redirect — กำหนดว่าผู้ใช้ควรถูกเปลี่ยนเส้นทางไปยัง URL ที่ระบุโดยสมบูรณ์หรือไม่ หากตั้งค่าเป็น false ฟอร์มชำระเงินจะปรากฏในวิดเจ็ตภายใน iframe คุณสามารถปรับขนาด iframe ได้โดยใช้ CSS ในการตั้งค่าวิดเจ็ต
checkStateToken จะถูกเพิ่มใน url เป็นพารามิเตอร์ bukzaCheckStateToken พารามิเตอร์นี้ช่วยให้คุณตรวจสอบสถานะคำสั่งซื้อบนหน้าชำระเงินของคุณ อ่านเพิ่มเติมเกี่ยวกับเรื่องนี้ ที่นี่

1.2. ขณะนี้ลูกค้าจะเห็นฟอร์มชำระเงินของคุณและดำเนินการชำระเงิน คุณควรได้รับการแจ้งเตือนจาก payment gateway ไปยังเซิร์ฟเวอร์ของคุณ หลังจากได้รับการแจ้งเตือนนี้ ให้ส่ง POST request ไปที่ 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 จะส่งคำขอไปยังเซิร์ฟเวอร์ของคุณ ซึ่งคุณควรส่งต่อไปยัง payment gateway ของคุณ

หากต้องการยกเลิกการอนุมัติวงเงิน 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 status 200 (SUCCESS) สำหรับคำขอเหล่านี้ทุกครั้ง

ตัวเลือกที่ 2 "โหมดง่าย"

2.1. เมื่อคำสั่งซื้อเสร็จสิ้น Bukza จะส่ง POST request ไปยัง URL เซิร์ฟเวอร์ของคุณเช่นเดียวกับขั้นตอน 1.1

2.2. ขณะนี้ลูกค้าจะเห็นฟอร์มชำระเงินของคุณและดำเนินการชำระเงิน คุณควรได้รับการแจ้งเตือนจาก payment gateway ไปยังเซิร์ฟเวอร์ของคุณ หลังจากได้รับการแจ้งเตือนนี้ ให้ส่ง POST request ไปที่ https://public.bukza.com/api/pay ทันที เนื้อหาคำขอ:

{
    userId:11223,
    orderNumber:"574285869",
    command: "CaptureCallback",
    data: "18493853499",
    amount: 99.75,
    timestamp: 1596706182,
    hash: "eUKOwld1sEK3axhF9ZAy0WugXMJW+9nrs4BRlvnCeb0=",
    comment: "ความคิดเห็นใด ๆ เกี่ยวกับการชำระเงิน ข้อความนี้จะแสดงในอินเทอร์เฟซผู้จัดการ และจะไม่ถูกนำไปใช้ในการคำนวณลายเซ็นคำขอ"
}

คืนเงิน

คุณสามารถใช้ส่วนติดต่อผู้จัดการเพื่อคืนเงินสำหรับการชำระเงินแต่ละรายการ การคืนเงินสามารถคืนเต็มจำนวนหรือบางส่วนก็ได้ เมื่อมีการดำเนินการคืนเงิน Bukza จะส่งคำขอไปยังเซิร์ฟเวอร์ของคุณ จากนั้นคุณต้องส่งคำขอที่เกี่ยวข้องไปยัง payment gateway ของคุณ เนื้อหาคำขอจาก Bukza:

{
    userId:11223,
    orderNumber:"574285869",
    command: "Refund",
    data: "18493853499",
    amount: 50.75,
    timestamp: 1596706182,
    hash: "E62WH04cKUjAvQ0dmirYMc16mCGN96YyQfrft8vLj0A="
    email: "john@example.com",
    phone: "+11111111111",
}

คุณควรตอบกลับด้วย HTTP status 200 (SUCCESS) สำหรับคำขอเหล่านี้ทุกครั้ง