Việc tích hợp gốc yêu cầu bạn tạo một API RESTful mà Google có thể gọi để tạo và quản lý các phiên thanh toán.
Quy trình tổng thể như sau:
- Tạo phiên thanh toán: Người dùng và (không bắt buộc) một Nhân viên đang trong một vòng lặp thêm các mặt hàng vào phiên.
- Bàn giao cho giao diện người dùng của Google: Sau khi người dùng quyết định thanh toán, Agent (nếu đã tương tác) sẽ chuyển quyền kiểm soát cho giao diện người dùng của Google (truyền dữ liệu phiên thanh toán)
- Thanh toán thủ công: Giờ đây, người dùng chỉ tương tác với giao diện người dùng của Google để điền thông tin nhạy cảm về việc thực hiện và thanh toán, rồi gửi đơn đặt hàng. Agent không tham gia vào phần này, đảm bảo tính xác định.
- Hoàn tất và trả lại: Giao diện người dùng của Google sẽ hiện trang "Cảm ơn" để xác nhận đơn đặt hàng. Nếu muốn, người dùng có thể được chuyển hướng trở lại Đại lý. Đại lý này có thể đã được thông báo về giao dịch mua đã hoàn tất.
Các bước sau đây mô tả những điểm cuối API mà bạn sẽ cần triển khai và hành vi của chúng.
1. Tạo phiên thanh toán
Điểm cuối này cho phép tạo một phiên thanh toán có chứa những sản phẩm mà người dùng muốn mua.
- Điểm cuối:
POST /checkout-sessions - Trình kích hoạt: Người dùng nhấp vào "Mua" trên một sản phẩm.
Yêu cầu: Google gửi mục hàng và đơn vị tiền tệ.
{
"line_items": [
{
"item": {
"id": "product_12345", // Must match Product Feed ID
"title": "Running Shoes"
},
"quantity": 1
}
],
"currency": "USD"
}
Phản hồi: Bạn trả về phiên đã khởi tạo cùng với tổng số tiền, thuế (ban đầu là ước tính) và các khả năng thanh toán. Bạn phải thêm đường liên kết đến điều khoản dịch vụ và chính sách quyền riêng tư. Các đường liên kết này sẽ xuất hiện bên dưới nút thanh toán.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [
{
"name": "dev.ucp.shopping.checkout",
"version": "2026-01-11"
},
{
"name": "dev.ucp.shopping.fulfillment",
"version": "2026-01-11"
}
]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "incomplete",
"line_items": [
{
"id": "line_1",
"item": {
"id": "product_12345",
"title": "Running Shoes",
"price": 10000
},
"quantity": 1,
"base_amount": 10000,
"subtotal": 10000,
"total": 10000
}
],
"totals": [
{ "type": "subtotal", "amount": 10000 }, // in cents
{ "type": "tax", "amount": 0 },
{ "type": "total", "amount": 10000 }
],
"payment": {
"handlers": [
{
"id": "gpay",
"name": "com.google.pay",
"config": {
"api_version": 2,
"api_version_minor": 0,
"merchant_info": {
"merchant_id": "12345678901234567890",
"merchant_name": "Example Merchant"
},
"allowed_payment_methods": [
{
"type": "CARD",
"parameters": {
"allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
"allowed_card_networks": ["VISA", "MASTERCARD"]
},
"tokenization_specification": {
"type": "PAYMENT_GATEWAY",
"parameters": {
"gateway": "stripe",
"gateway_merchant_id": "exampleGatewayMerchantId"
}
}
}
]
}
}
]
},
"links": [
{ "type": "privacy_policy", "url": "https://m.com/privacy" },
{ "type": "terms_of_service", "url": "https://m.com/terms" }
]
}
2. Lấy phiên thanh toán
Điểm cuối này cho phép truy xuất một phiên thanh toán.
- Điểm cuối:
GET /checkout-sessions/{id}
Yêu cầu: Google gửi mã nhận dạng của phiên thanh toán. Nếu bạn sử dụng mã nhận dạng chung (ví dụ: gid://merchant.example.com/Checkout/session_abc123), lưu ý rằng mã nhận dạng trong đường dẫn yêu cầu sẽ chỉ là thành phần cuối cùng của mã nhận dạng này (ví dụ:
session_abc123).
Phản hồi: Bạn trả về toàn bộ đối tượng thanh toán.
3. Cập nhật phiên thanh toán
Điểm cuối này cho phép cập nhật một phiên thanh toán. Khi địa chỉ giao hàng được cập nhật, bạn phải tính toán lại và trả về thuế cũng như các lựa chọn vận chuyển.
- Điểm cuối:
PUT /checkout-sessions/{id} - Điều kiện kích hoạt: Người dùng chọn hoặc thay đổi địa chỉ giao hàng, cập nhật lựa chọn giao hàng hoặc cập nhật thông tin thanh toán.
Yêu cầu: Google gửi toàn bộ đối tượng thanh toán kèm theo thông tin mới cập nhật.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"buyer": {
"first_name": "John",
"last_name": "Doe",
"email": "john@example.com"
},
"fulfillment": {
"methods": [
{
"type": "shipping",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"selected_destination_id": "dest_1"
}
]
},
"payment": {
"selected_instrument_id": "pi_gpay_5678",
"instruments": [
{
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"rich_text_description": "Google Pay •••• 5678"
}
]
}
// ... other fields (line_items, currency, etc.)
}
Phản hồi: Bạn tính lại thuế và các lựa chọn vận chuyển nếu cần, đồng thời trả về toàn bộ đối tượng thanh toán.
{
"id": "gid://merchant.example.com/Checkout/session_abc123",
"totals": [
{ "type": "subtotal", "amount": 10000 },
{ "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
{ "type": "tax", "amount": 850 },
{ "type": "total", "amount": 11350 }
],
// ... other fields (line_items, currency, etc.)
"fulfillment": {
"methods": [
{
"id": "method_shipping",
"type": "shipping",
"line_item_ids": ["line_1"],
"selected_destination_id": "dest_1",
"destinations": [
{
"id": "dest_1",
"postal_code": "94043",
"country": "US",
"address_locality": "Mountain View",
"address_region": "CA"
}
],
"groups": [
{
"id": "group_1",
"line_item_ids": ["line_1"],
"selected_option_id": "ship_ground",
"options": [
{
"id": "ship_ground",
"title": "Ground (3-5 days)",
"total": 500
},
{
"id": "ship_express",
"title": "Express (1-2 days)",
"total": 1500
}
]
}
]
}
]
}
}
4. Hoàn tất phiên thanh toán
Điểm cuối này cho phép hoàn tất một phiên thanh toán và đặt hàng. Thao tác này sẽ trả về phiên thanh toán đã hoàn tất và bao gồm thông tin đơn đặt hàng. Quá trình xử lý thanh toán sẽ bắt đầu sau khi nhận được lệnh gọi này.
- Điểm cuối:
POST /checkout-sessions/{id}/complete - Điều kiện kích hoạt: Người dùng nhấp vào "Đặt hàng".
Yêu cầu: Google gửi mã thông báo thanh toán (blob được mã hoá) từ nhà cung cấp (ví dụ: Google Pay) và tín hiệu rủi ro về người mua để bạn tự phát hiện hành vi gian lận.
{
"payment_data": {
"id": "pi_gpay_5678",
"handler_id": "gpay",
"type": "card",
"brand": "mastercard",
"last_digits": "5678",
"billing_address": {
"postal_code": "94043",
"address_country": "US"
},
"credential": {
"type": "PAYMENT_GATEWAY",
"token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
}
}
}
Phản hồi: Bạn trả về toàn bộ đối tượng thanh toán cho biết đơn đặt hàng đã hoàn tất, bao gồm cả mã đơn đặt hàng và URL liên kết cố định đến đơn đặt hàng.
{
"ucp": {
"version": "2026-01-11",
"capabilities": [...]
},
"id": "gid://merchant.example.com/Checkout/session_abc123",
"status": "completed",
// ... other fields (line_items, currency, etc.)
"order_id": "gid://merchant.example.com/Order/789",
"order_permalink_url": "https://merchant.example.com/orders/789"
}
5. Huỷ phiên thanh toán
Điểm cuối này huỷ một phiên thanh toán.
- Điểm cuối:
POST /checkout-sessions/{id}/cancel
Yêu cầu: Google gửi mã nhận dạng của phiên thanh toán.
Phản hồi: Bạn trả về toàn bộ đối tượng thanh toán với trạng thái được cập nhật thành canceled.