การชำระเงินแบบฝัง

การผสานรวมการชำระเงินแบบฝังช่วยให้คุณฝังการชำระเงินบนเว็บในแพลตฟอร์มของ Google ได้ ใช้เส้นทางนี้หากผลิตภัณฑ์ของคุณต้องใช้ตรรกะที่ซับซ้อน (เช่น การปรับแต่ง) ซึ่ง Native API ไม่รองรับ คุณจะต้อง ใช้ UI การชำระเงินที่จะฝังอยู่ในขั้นตอนการชำระเงินผ่าน iframe

การชำระเงินแบบฝังคืออะไร

การชำระเงินแบบฝัง (EC) ช่วยให้โฮสต์ (เช่น Google Search หรือเอเจนต์ AI) แสดงการชำระเงินบนเว็บที่มีอยู่ภายในแอปพลิเคชันของตน (โดยใช้ iframe หรือ WebView) ได้ ซึ่งแตกต่างจากการเปลี่ยนเส้นทางบนเว็บมาตรฐานตรงที่ช่วยให้มีการสื่อสารแบบ สองทาง โฮสต์สามารถ "มอบหมาย" งานที่เฉพาะเจาะจง เช่น การเลือกที่อยู่ที่บันทึกไว้หรือการชำระเงินด้วยข้อมูลเข้าสู่ระบบที่จัดเก็บไว้ เพื่อมอบประสบการณ์ที่ รวดเร็วและเป็นธรรมชาติมากขึ้น ในขณะที่คุณยังคงเป็นผู้ขายที่บันทึกไว้และ จัดการการสร้างคำสั่งซื้อจริง

รายการตรวจสอบการใช้งานของผู้ขาย

หากต้องการรองรับการชำระเงินแบบฝัง คุณต้องใช้ข้อกำหนดต่อไปนี้ ใน UCP API และแอปพลิเคชันการชำระเงินส่วนหน้า

1. เปิดใช้การค้นพบ (UCP API)

คุณต้องประกาศว่าการชำระเงินรองรับส่วนขยายแบบฝังในการตอบกลับของ UCP API

• การดำเนินการ: เพิ่มออบเจ็กต์ความสามารถ dev.ucp.shopping.embedded_checkout ลงในอาร์เรย์ความสามารถในการตอบกลับของ UCP
• ข้อกำหนด: ใส่ URL ของข้อกำหนดและสคีมา
• ไม่บังคับ: หากคุณต้องใช้การตรวจสอบสิทธิ์ (เช่น โทเค็น JWT) เพื่อโหลด ชำระเงิน ให้ตั้งค่า auth.required เป็น true

"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. จัดการการเริ่มต้น URL (ส่วนหน้า)

เมื่อโฮสต์โหลด continue_url ระบบจะเพิ่มพารามิเตอร์การค้นหาที่เฉพาะเจาะจง ส่วนหน้าต้องแยกวิเคราะห์ข้อมูลเหล่านี้ทันทีเมื่อโหลด

• การดำเนินการ: แยกวิเคราะห์พารามิเตอร์การค้นหาของ URL ต่อไปนี้
  • ec_version: เวอร์ชันของโปรโตคอล (เช่น 2026-01-11)
  • ec_auth: (หากมี) ตรวจสอบโทเค็นการให้สิทธิ์ที่โฮสต์ระบุ หากคุณตั้งค่า auth.required: true
  • ec_delegate: รายการการดำเนินการที่คั่นด้วยคอมมาซึ่งโฮสต์ต้องการ จัดการโดยตรง (เช่น payment.credential, fulfillment.address_change, payment.instruments_change)

3. สร้างการสื่อสาร (ส่วนหน้า)

การสื่อสารจะเกิดขึ้นโดยใช้ postMessage โดยใช้รูปแบบ JSON-RPC 2.0

• การดำเนินการ: ใช้ Listener สำหรับเหตุการณ์ message
• ข้อกำหนด: คุณต้องตรวจสอบแหล่งที่มาของทุกข้อความเพื่อให้แน่ใจว่าข้อความนั้นตรงกับโฮสต์
• การรองรับเนทีฟ: สำหรับโฮสต์แอปที่มาพร้อมเครื่อง ให้ตรวจสอบและใช้ส่วนกลางที่แทรก (เช่น window.EmbeddedCheckoutProtocolConsumer) หาก postMessage ไม่พร้อมใช้งาน

4. ทำการแฮนด์เชค (ส่วนหน้า)

ทันทีที่การชำระเงินแสดงผล คุณต้องแจ้งให้โฮสต์ทราบว่าคุณพร้อมแล้วและ ยืนยันการมอบสิทธิ์ที่คุณยอมรับ

• การดำเนินการ: ส่งคำขอ ec.ready ทันทีหลังจากโหลด
• เพย์โหลด: ใส่delegateอาร์เรย์ที่แสดงรายการความสามารถที่คุณตกลง ให้โฮสต์จัดการ
• ตัวอย่าง: หาก URL ที่ขอคือ ec_delegate=payment.credential และคุณ ยอมรับ ให้ใส่ "payment.credential" ในเพย์โหลด ec.ready

// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. ใช้ตรรกะการมอบสิทธิ์ (ส่วนหน้า)

หากยอมรับการมอบสิทธิ์ในการแฮนด์เชค คุณต้องแก้ไขลักษณะการทำงานของ UI เพื่อหลีกเลี่ยงความขัดแย้ง

• การดำเนินการ: ซ่อนองค์ประกอบ UI ที่เกี่ยวข้องสำหรับงานที่มอบหมาย
• ตัวอย่าง: หากมีการมอบสิทธิ์ให้ fulfillment.address_change ให้ซ่อนแบบฟอร์มที่อยู่ และแสดงปุ่ม "เปลี่ยนที่อยู่" แทน
• การดำเนินการ: เมื่อผู้ใช้คลิกปุ่มนั้น ให้ส่งข้อความ _request (เช่น ec.fulfillment.address_change_request) ให้แก่โฮสต์
• การดำเนินการ: รอการตอบกลับจากโฮสต์ การตอบกลับจะมีข้อมูลใหม่ (เช่น ที่อยู่ที่เลือก)
• ข้อกำหนด: อัปเดตสถานะการชำระเงินโดยใช้การแทนที่สไตล์ PUT (แทนที่ทั้งส่วนออบเจ็กต์) ตามข้อมูลที่โฮสต์ส่งคืน

// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. ส่งการอัปเดตวงจรและสถานะ (ส่วนหน้า)

คุณต้องแจ้งให้โฮสต์ทราบสถานะการชำระเงินเพื่อให้โฮสต์อัปเดต UI หรือจัดการข้อผิดพลาดได้

• การดำเนินการ: ส่งการแจ้งเตือน (ข้อความที่ไม่มีรหัส) เมื่อสถานะเปลี่ยนแปลง
  • ec.start: เมื่อมองเห็นการชำระเงินทั้งหมด
  • ec.line_items.change: หากเนื้อหาหรือยอดรวมของรถเข็นมีการอัปเดต
  • ec.buyer.change: หากมีการอัปเดตรายละเอียดผู้ซื้อ
  • ec.complete: เมื่อสั่งซื้อสำเร็จ
  • ec.error: หากเกิดข้อผิดพลาดร้ายแรง

7. บังคับใช้การรักษาความปลอดภัย (เซิร์ฟเวอร์/ส่วนหัว)

คุณต้องตรวจสอบว่าผู้ไม่ประสงค์ดีไม่สามารถฝังการชำระเงินของคุณได้

• การดำเนินการ: ใช้ส่วนหัวของนโยบายรักษาความปลอดภัยเนื้อหา (CSP)
• ข้อกำหนด: ตั้งค่า frame-ancestors <host_origin>; เพื่ออนุญาตการฝัง เฉพาะโฮสต์ที่เชื่อถือได้
• การนำทาง: บล็อกตรรกะที่นำผู้ใช้ออกจากขั้นตอนการชำระเงิน (เช่น นำลิงก์ "เลือกซื้อต่อ" ที่นำไปยังหน้าแรกออก) เราอนุญาตข้อยกเว้นสำหรับการยืนยัน 3DS หรือการเปลี่ยนเส้นทางการชำระเงินของบุคคลที่สาม