arrow_back_ios

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

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

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

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

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

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

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

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

    ตัวเลือกการเชื่อมต่อนี้ช่วยให้คุณเรียกเก็บเงินด้วยตนเองในภายหลังได้ คุณสามารถตรวจสอบการจองด้วยตนเอง แล้วเลือกเรียกเก็บเงินหรือยกเลิกการกันวงเงินได้

  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);
ตัวอย่างการเขียนโค้ดในภาษาโปรแกรมต่าง ๆ: 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 "แบบกันวงเงิน"

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 "โหมดแบบง่าย"

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)