Brick API Documentation
Brick

การกำหนดค่าและการนำไปใช้งาน

ภาพรวม

หน้าชำระเงินเป็นประสบการณ์การชำระเงิน Brick ที่โฮสต์ไว้ซึ่งรวมเอา:

  • การกำหนดค่าที่จัดการโดยแดชบอร์ดสำหรับการสร้างแบรนด์และการตั้งค่าแบบฝัง
  • การสร้างเซสชันที่ขับเคลื่อนด้วย API สำหรับแต่ละธุรกรรม

การตั้งค่านี้ช่วยให้ผู้ค้าสามารถเก็บการจัดรูปแบบหน้าและการตั้งค่าการปฏิบัติงานไว้ในแดชบอร์ด Brick ในขณะที่แบ็กเอนด์สร้างเซสชันการชำระเงินเฉพาะธุรกรรมผ่าน API

จะกำหนดค่าหน้าชำระเงินได้ที่ไหน

เปิดแดชบอร์ด Brick และไปที่ Settings > Checkout

หน้านี้ประกอบด้วยการกำหนดค่าระดับผู้ขายสำหรับประสบการณ์การชำระเงินที่โฮสต์

Brick Checkout Page configuration dashboard


การกำหนดค่าหน้าชำระเงิน

การตั้งค่าต่อไปนี้ได้รับการจัดการใน Dashboard UI

สนามคำอธิบายหมายเหตุการใช้งาน
Titleชื่อผู้ขายหรือผลิตภัณฑ์ที่แสดงบนหน้าที่โฮสต์ใช้ป้ายกำกับที่หันหน้าเข้าหาลูกค้า
Primary Colorสีเน้นแบรนด์หลักนำไปใช้กับองค์ประกอบ UI หลัก
Font Colorสีข้อความหลักตรวจสอบให้แน่ใจว่ามีคอนทราสต์เพียงพอ
Logo URLโลโก้ที่แสดงบนหน้าชำระเงินจะต้องเข้าถึงได้แบบสาธารณะ
Favicon URLไอคอนแท็บเบราว์เซอร์จะต้องเข้าถึงได้แบบสาธารณะ
Font Familyการตั้งค่าการพิมพ์สำหรับหน้าที่โฮสต์ใช้แบบอักษรที่รองรับ
Button Radiusรัศมีมุมของปุ่มควบคุมสไตล์การมองเห็น
Success URLเปลี่ยนเส้นทาง URL หลังจากเสร็จสิ้นสำเร็จอย่าใช้เป็นแหล่งยืนยันการชำระเงินเพียงแห่งเดียว
Failed URLเปลี่ยนเส้นทาง URL หลังจากล้มเหลวหรือยกเลิกใช้สำหรับ UX เท่านั้น
Client Receipt Emailอีเมลผู้รับใบเสร็จรับเงินจัดการในแดชบอร์ด
Client Receipt WhatsAppหมายเลขผู้รับใบเสร็จ WhatsAppจัดการในแดชบอร์ด
Published Keyรหัสสาธารณะสำหรับการเริ่มต้นส่วนหน้าของหน้าชำระเงินปลอดภัยสำหรับการใช้งานส่วนหน้า
Allowed Domainsรายการที่อนุญาตของโดเมนสำหรับการดำเนินการฝัง HTMLจำเป็นสำหรับโฟลว์แบบฝัง


ความรับผิดชอบในการกำหนดค่า

ความรับผิดชอบของแดชบอร์ด

การควบคุมแดชบอร์ด:

  • การสร้างแบรนด์เพจที่โฮสต์
  • พฤติกรรมการเปลี่ยนเส้นทาง
  • เผยแพร่การสร้างคีย์
  • โดเมนที่อนุญาตสำหรับการใช้งานแบบฝัง
  • การกำหนดค่าการติดต่อใบเสร็จรับเงิน

ความรับผิดชอบของแบ็กเอนด์

การควบคุมแบ็กเอนด์ของคุณ:

  • สร้างโทเค็นการเข้าถึงสาธารณะ
  • การสร้างเซสชันการชำระเงิน
  • การจัดเก็บการอ้างอิงธุรกรรม
  • รับโทรกลับ
  • ตรวจสอบสถานะการทำธุรกรรมเมื่อจำเป็น

แบบจำลองข้อมูลรับรอง

หน้าชำระเงินใช้ข้อมูลรับรองที่แตกต่างกันสำหรับเลเยอร์ที่แตกต่างกัน

หนังสือรับรองใช้โดยวัตถุประสงค์
Published Keyส่วนหน้าโหลดการกำหนดค่าการชำระเงินของผู้ขาย
Client IDแบ็กเอนด์ใช้เพื่อสร้างโทเค็นการเข้าถึงสาธารณะ
Client Secretแบ็กเอนด์ใช้เพื่อสร้างโทเค็นการเข้าถึงสาธารณะ
publicAccessTokenการเรียกแบ็กเอนด์ APIอนุญาตจุดสิ้นสุดของหน้าชำระเงินที่ได้รับการป้องกัน

กฎสำคัญ:

  • อย่าเปิดเผย Client Secret ในโค้ดส่วนหน้า
  • อย่าใช้ Published Key เป็นข้อมูลรับรอง API
  • สร้าง publicAccessToken ใหม่ให้ใกล้เคียงกับเวลาใช้งาน

จุดเข้าส่วนหน้า

หน้าชำระเงินสามารถเริ่มต้นได้สองวิธี

จุดเข้าวัตถุประสงค์
https://checkout.onebrick.io/?pubkey=<Published Key>โหลดส่วนหน้าการชำระเงินที่โฮสต์โดยแบรนด์
checkoutUrl ส่งคืนโดย POST /v1/payments/checkoutเปิดเซสชันการชำระเงินเฉพาะธุรกรรม

ใช้ Published Key เมื่อคุณต้องการฟรอนท์เอนด์ที่โฮสต์ไว้หรือโฟลว์แบบฝังที่กำหนดค่าไว้

ใช้ checkoutUrl ที่สร้างโดย API เมื่อลูกค้าต้องทำธุรกรรมเฉพาะให้เสร็จสิ้น


ขั้นตอนการดำเนินการที่แนะนำ

ขั้นตอนที่ 1 กำหนดค่าหน้าชำระเงินในแดชบอร์ด

ก่อนที่จะส่งการเข้าชมสดใดๆ:

  1. ตั้งชื่อเพจ สี โลโก้ และไอคอน Fav
  2. กำหนดค่า Success URL และ Failed URL
  3. ตรวจสอบฟิลด์ปลายทางใบเสร็จรับเงินหากใช้
  4. คัดลอก Published Key
  5. เพิ่มโดเมนที่ได้รับอนุญาตหากคุณวางแผนที่จะฝังเพจ

ขั้นตอนที่ 2 สร้างโทเค็นการเข้าถึงสาธารณะ

การเรียก API ของหน้าชำระเงินที่ได้รับการป้องกันจำเป็นต้องมีโทเค็นการเข้าถึงสาธารณะ

Endpoint

Code
GET /v2/payments/auth/token

Example

TerminalCode
curl -u "<CLIENT_ID>:<CLIENT_SECRET>" \ "https://sandbox.onebrick.io/v2/payments/auth/token"

Example Response

JSONCode
{ "status": 200, "data": { "message": "Access token is valid for 5 minutes and can use one time only", "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "issuedAt": "2026-03-17T11:54:06.736541", "expiresAt": "2026-03-17T11:59:06.736541" } }

ขั้นตอนที่ 3 สร้างเซสชันการชำระเงิน

เรียกหน้าชำระเงินเพื่อสร้างจุดสิ้นสุดจากแบ็กเอนด์ของคุณ

Endpoint

Code
POST /v1/payments/checkout

Headers

Code
publicAccessToken: Bearer <accessToken> Content-Type: application/json

Example Request

JSONCode
{ "externalId": "CO-1773723246580", "currency": "IDR", "description": "Gaming Voucher Free Amount" }

Optional Fixed-Amount Example

JSONCode
{ "externalId": "CO-1773723246580", "currency": "IDR", "description": "Gaming Voucher", "amount": 12012, "type": "qris" }

Example cURL

TerminalCode
curl --request POST \ --url "https://sandbox.onebrick.io/v1/payments/checkout" \ --header "publicAccessToken: Bearer <accessToken>" \ --header "Content-Type: application/json" \ --data '{ "externalId": "CO-1773723246580", "currency": "IDR", "description": "Gaming Voucher Free Amount" }'

Example Response

JSONCode
{ "status": 200, "data": { "id": "QyECa1OpjWJcyfzXOLT6HKCxAVoDzUs3", "externalId": "CO-1773723246580", "status": "CREATED", "checkoutUrl": "https://sandbox-checkout.onebrick.io/aiU5tkLQZeZzXXdgwZUenOyGgTf41mKqyXv9XS96yB4QE9lze2wuMFhfPH4jMC2%2B", "currency": "IDR", "amount": null, "type": "", "createdAt": "2026-03-17T04:54:06Z", "description": "Gaming Voucher Free Amount" }, "errors": null, "hashcode": "38d4b6cc3dd7a6cbb400f08c3bed1228" }

ขั้นตอนที่ 4 นำเสนอการชำระเงินให้กับลูกค้า

คุณสามารถนำเสนอการชำระเงินในรูปแบบใดรูปแบบหนึ่งต่อไปนี้:

  • เปลี่ยนเส้นทางลูกค้าไปที่ checkoutUrl
  • เปิด checkoutUrl จากปุ่มหรือ CTA
  • เริ่มต้นส่วนหน้าชำระเงินของแบรนด์โดยใช้ Published Key
  • ฝังเพจหากโดเมนต้นทางอยู่ในรายการที่อนุญาต

ขั้นตอนที่ 5 ยืนยันผลการชำระเงิน

อย่าพึ่งพาเฉพาะ URL การเปลี่ยนเส้นทางเท่านั้น

ใช้:

  • การเรียกกลับ Brick เป็นแหล่งที่มาของความจริง
  • การตรวจสอบสถานะเพื่อตรวจสอบการปฏิบัติงานเมื่อจำเป็น

การกำหนดค่าฝัง HTML

หากคุณวางแผนที่จะฝังหน้าชำระเงิน:

  1. เพิ่มต้นทางที่อนุญาตทั้งหมดภายใต้ Allowed Domains
  2. บันทึกการกำหนดค่า
  3. ทดสอบการฝังจากแต่ละโดเมนที่ได้รับอนุมัติ

หากต้นทางไม่อยู่ในรายการที่อนุญาต หน้าที่โฮสต์หรือการตรวจสอบสถานะที่เกี่ยวข้องอาจล้มเหลวเนื่องจากข้อจำกัดของต้นทาง



ข้อจำกัดในการดำเนินการ

ข้อจำกัดของโทเค็น

  • โทเค็นการเข้าถึงสาธารณะมีอายุสั้น
  • การตอบสนองโทเค็นที่ทดสอบระบุว่าใช้ได้ 5 นาทีและใช้ครั้งเดียว
  • สร้างโทเค็นใหม่ก่อนคำขอที่ได้รับการป้องกัน

ข้อจำกัดด้านสิ่งแวดล้อม

สิ่งแวดล้อมURL ฐาน
แซนด์บ็อกซ์https://sandbox.onebrick.io
การผลิตhttps://api.onebrick.io

ใช้ https:// ที่ชัดเจนใน URL พื้นฐานทั้งหมด

หลีกเลี่ยง:

Code
http://sandbox.onebrick.io

การเปลี่ยนเส้นทาง HTTP อาจทำให้ไคลเอ็นต์บางตัวลองอีกครั้งในชื่อ GET ซึ่งสามารถทริกเกอร์ 405 method_not_allowed ได้

ข้อจำกัดในการอ้างอิง

  • externalId ไม่ควรซ้ำกันต่อธุรกรรม
  • เก็บทั้งรหัสธุรกรรมที่ส่งคืนของ externalId และ Brick ของคุณ

ข้อจำกัดของช่องสัญญาณ

  • รองรับ qris และ virtual_account ในคอลเลกชันที่ทดสอบ
  • ขีดจำกัดจำนวนเงิน QR Code และขีดจำกัดบัญชีเสมือนเป็นไปตามกฎผลิตภัณฑ์รับเงินที่กำหนดค่าโดย Brick


การแก้ไขปัญหา

400 คำขอไม่ถูกต้อง

สาเหตุทั่วไป:

  • ไม่มีช่องที่ต้องกรอก
  • JSON ไม่ถูกต้อง
  • ประเภทฟิลด์ผิด

แนวปฏิบัติที่ดีที่สุด:

  • ส่ง JSON ที่ถูกต้องเท่านั้น
  • อย่าใส่ความคิดเห็นไว้ในเนื้อหาคำขอ JSON

401 ไม่ได้รับอนุญาต

สาเหตุทั่วไป:

  • โทเค็นไม่ถูกต้อง
  • โทเค็นหายไป
  • โทเค็นหมดอายุ
  • ข้อมูลรับรองสภาพแวดล้อมที่ไม่ถูกต้อง

ไม่อนุญาตให้ใช้วิธี 405

สาเหตุทั่วไป:

  • ใช้ GET แทน POST สำหรับ /v1/payments/checkout
  • โพสต์ไปที่ URL ของ http:// และปล่อยให้ลูกค้าติดตามการเปลี่ยนเส้นทาง

ข้อมูลแบ็กเอนด์ที่แนะนำในการจัดเก็บ

สำหรับแต่ละเซสชันหน้าชำระเงิน ให้จัดเก็บอย่างน้อย:

  • externalId
  • รหัสธุรกรรม Brick
  • checkoutUrl
  • status
  • currency
  • amount
  • description
  • การประทับเวลาการสร้าง

ซึ่งจะช่วยในการกระทบยอด สนับสนุนการตรวจสอบ และการจับคู่การโทรกลับ

รายการตรวจสอบการเริ่มใช้งานจริง

  1. ยืนยันว่าเปิดใช้งานการเข้าถึงการผลิตแล้ว
  2. กำหนดค่า URL ติดต่อกลับของการผลิต
  3. ตรวจสอบช่องการสร้างแบรนด์ทั้งหมดภายใต้ Settings > Checkout
  4. ตรวจสอบ Success URL และ Failed URL
  5. คัดลอกและตรวจสอบ Published Key
  6. เพิ่มโดเมนที่ได้รับการอนุมัติทั้งหมดลงใน Allowed Domains
  7. ทดสอบโฟลว์จำนวนเปิดหนึ่งรายการและโฟลว์จำนวนคงที่หนึ่งรายการในแซนด์บ็อกซ์
  8. ตรวจสอบการโทรกลับก่อนที่จะเปลี่ยนไปใช้การใช้งานจริง
Last modified on