Copy page

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

ภาพรวม

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

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

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

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

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

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

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

การตั้งค่าต่อไปนี้ได้รับการจัดการใน 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

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

Example Response

Code
{
  "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

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

Optional Fixed-Amount Example

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

Example cURL

Code
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

Code
{
  "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 ในคอลเลกชันที่ทดสอบ
• ขีดจำกัดจำนวนเงิน QRIS และขีดจำกัดบัญชีเสมือนเป็นไปตามกฎผลิตภัณฑ์รับเงินที่กำหนดค่าโดย 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. ตรวจสอบการโทรกลับก่อนที่จะเปลี่ยนไปใช้การใช้งานจริง