Thanh toán tích hợp

Việc tích hợp tính năng Thanh toán tích hợp cho phép bạn nhúng quy trình thanh toán dựa trên web vào các nền tảng của Google. Hãy sử dụng đường dẫn này nếu sản phẩm của bạn yêu cầu logic phức tạp (ví dụ: tuỳ chỉnh) mà Native API không hỗ trợ. Bạn sẽ triển khai một giao diện người dùng thanh toán được nhúng vào quy trình thanh toán thông qua một iframe.

Tính năng thanh toán tích hợp là gì?

Tính năng thanh toán được nhúng (EC) cho phép một máy chủ lưu trữ (chẳng hạn như Google Tìm kiếm hoặc một AI Agent) hiển thị quy trình thanh toán dựa trên web hiện có của bạn trong ứng dụng của họ (bằng cách sử dụng iframe hoặc webview). Không giống như lệnh chuyển hướng web tiêu chuẩn, lệnh này cho phép giao tiếp hai chiều. Đơn vị lưu trữ có thể "uỷ quyền" các tác vụ cụ thể, chẳng hạn như chọn địa chỉ đã lưu hoặc thanh toán bằng thông tin đăng nhập đã lưu trữ để mang lại trải nghiệm nhanh hơn và tự nhiên hơn, trong khi bạn vẫn là Người bán đã đăng ký và xử lý việc tạo đơn đặt hàng thực tế.

Danh sách kiểm tra việc triển khai của người bán

Để hỗ trợ tính năng Thanh toán được nhúng, bạn phải triển khai các yêu cầu sau trên UCP API và ứng dụng thanh toán trên giao diện người dùng.

1. Bật tính năng khám phá (UCP API)

Bạn phải khai báo rằng quy trình thanh toán của bạn hỗ trợ tiện ích nhúng trong các phản hồi UCP API.

• Hành động: Thêm đối tượng chức năng dev.ucp.shopping.embedded_checkout vào mảng chức năng phản hồi UCP.
• Yêu cầu: Thêm URL của quy cách và lược đồ.
• Không bắt buộc: Nếu bạn yêu cầu xác thực (ví dụ: mã thông báo JWT) để tải trang thanh toán, hãy đặt auth.required thành 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. Xử lý quá trình khởi tạo URL (giao diện người dùng)

Khi máy chủ tải continue_url của bạn, máy chủ sẽ thêm các tham số truy vấn cụ thể. Giao diện người dùng của bạn phải phân tích cú pháp các thông tin này ngay khi tải.

• Hành động: Phân tích cú pháp các tham số truy vấn URL sau:
  • ec_version: Phiên bản giao thức (ví dụ: 2026-01-11).
  • ec_auth: (Nếu có) Xác thực mã thông báo uỷ quyền do máy chủ lưu trữ cung cấp, nếu bạn đặt auth.required: true.
  • ec_delegate: Danh sách các thao tác được phân tách bằng dấu phẩy mà máy chủ lưu trữ muốn xử lý theo cách tự nhiên (ví dụ: payment.credential, fulfillment.address_change, payment.instruments_change).

3. Thiết lập giao tiếp (giao diện người dùng)

Quá trình giao tiếp diễn ra bằng cách sử dụng postMessage theo định dạng JSON-RPC 2.0.

• Hành động: Triển khai một trình nghe cho các sự kiện message.
• Yêu cầu: Bạn phải xác thực nguồn gốc của mọi thông báo để đảm bảo thông báo đó khớp với máy chủ lưu trữ.
• Hỗ trợ gốc: Đối với các máy chủ ứng dụng gốc, hãy kiểm tra và sử dụng các biến toàn cục được chèn (ví dụ: window.EmbeddedCheckoutProtocolConsumer) nếu postMessage không có sẵn.

4. Thực hiện quy trình bắt tay (giao diện người dùng)

Ngay khi trang thanh toán hiển thị, bạn phải cho biết bạn đã sẵn sàng và xác nhận những quyền uỷ quyền mà bạn chấp nhận.

• Hành động: Gửi yêu cầu ec.ready ngay sau khi tải.
• Tải trọng: Thêm một mảng delegate liệt kê các chức năng mà bạn đồng ý cho phép máy chủ xử lý.
• Ví dụ: Nếu URL được yêu cầu là ec_delegate=payment.credential và bạn chấp nhận, hãy thêm "payment.credential" vào tải trọng 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. Triển khai logic uỷ quyền (giao diện người dùng)

Nếu chấp nhận một hoạt động uỷ quyền trong quy trình bắt tay, bạn phải sửa đổi hành vi giao diện người dùng để tránh xung đột.

• Hành động: Ẩn các phần tử giao diện người dùng có liên quan đối với các việc cần làm được uỷ quyền.
• Ví dụ: Nếu fulfillment.address_change được uỷ quyền, hãy ẩn biểu mẫu địa chỉ và thay vào đó, hiện nút "Thay đổi địa chỉ".
• Thao tác: Khi người dùng nhấp vào nút đó, hãy gửi một thông báo _request (ví dụ: ec.fulfillment.address_change_request) cho người tổ chức.
• Hành động: Chờ phản hồi của người tổ chức. Phản hồi sẽ chứa dữ liệu mới (ví dụ: địa chỉ đã chọn).
• Yêu cầu: Cập nhật trạng thái thanh toán bằng cách sử dụng một phương thức thay thế kiểu PUT (thay thế toàn bộ phần đối tượng) dựa trên dữ liệu do máy chủ lưu trữ trả về.

// 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. Gửi thông tin cập nhật về vòng đời và trạng thái (giao diện người dùng)

Bạn phải thông báo cho ứng dụng lưu trữ về trạng thái thanh toán để ứng dụng này có thể cập nhật giao diện người dùng hoặc xử lý lỗi.

• Hành động: Gửi thông báo (thông báo không có mã nhận dạng) khi trạng thái thay đổi:
  • ec.start: Khi quy trình thanh toán hiển thị đầy đủ.
  • ec.line_items.change: Nếu nội dung hoặc tổng số tiền trong giỏ hàng thay đổi.
  • ec.buyer.change: Nếu thông tin người mua được cập nhật.
  • ec.complete: Khi đơn đặt hàng được thực hiện thành công.
  • ec.error: Nếu xảy ra lỗi nghiêm trọng.

7. Thực thi bảo mật (máy chủ/tiêu đề)

Bạn phải đảm bảo rằng quy trình thanh toán của bạn không bị đối tượng xấu nhúng.

• Việc cần làm: Triển khai tiêu đề Chính sách bảo mật nội dung (CSP).
• Yêu cầu: Đặt frame-ancestors <host_origin>; để chỉ cho phép các máy chủ lưu trữ đáng tin cậy nhúng.
• Điều hướng: Chặn logic điều hướng người dùng rời khỏi quy trình thanh toán (ví dụ: xoá các đường liên kết "Tiếp tục mua sắm" dẫn đến trang chủ của bạn). Bạn có thể được miễn xác minh 3DS hoặc chuyển hướng thanh toán cho bên thứ ba.