Triển khai API REST thanh toán ngay trên nền tảng

Hướng dẫn này cung cấp tài liệu tham khảo API kỹ thuật và lược đồ tải trọng cho phiên bản 2026-04-08 của quy trình thanh toán ngay trên nền tảng theo Giao thức thương mại toàn cầu (UCP).

Trước khi tạo các điểm cuối, hãy đảm bảo rằng bạn đã xem Thông tin tổng quan về quy trình thanh toán ngay trên nền tảng để biết quy trình thanh toán cấp cao, các yêu cầu về việc xác thực và công cụ dành cho nhà phát triển.

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
  • Điều kiện kích hoạt: Người dùng nhấp vào "Mua ngay" trên một sản phẩm hoặc "Thanh toán qua Google" trong giỏ hàng.

Yêu cầu: Google gửi các mục hàng và thông tin địa chỉ hạn chế về người mua, bao gồm thành phố, tiểu bang và mã bưu chính.

// Request Example: Create checkout with multiple items.
{
  "line_items": [
    {
      "item": {
        // Must match ID in product feed
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      "item": {
        // Must match ID in product feed
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1"
      }
    ]
  }
}

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.

Ghi chú về trường ucp.status:

Được giới thiệu trong phiên bản 2026-04-08, trường ucp.status cho biết kết quả tạo:

  • "success" (hoặc bị bỏ qua): Mặc định. Đã tạo phiên, ngay cả khi có messages có thể khôi phục.
  • "error": Không tạo được phiên do lỗi không thể khắc phục (ví dụ: tất cả mặt hàng đều hết hàng). Trong trường hợp này, phần nội dung phản hồi phải là một đối tượng Phản hồi lỗi, chứ không phải là một đối tượng Thanh toán. Hãy xem Ví dụ về lỗi không thể khôi phục trong phần Xử lý lỗi.

Lưu ý về các thay đổi đối với mảng totals:

  • Trường type trong mỗi đối tượng trong mảng totals hiện là một chuỗi mở.
  • Giờ đây, trường amount có thể có giá trị âm (ví dụ: để biểu thị chiết khấu).
  • Các đối tượng trong totals (chẳng hạn như type: "fee" và type: "tax") có thể tuỳ ý thêm một mảng lines để liệt kê các thành phần phụ (ví dụ: phí dịch vụ hoặc phí tái chế, hoặc thông tin chi tiết về thuế nhiều cấp của tỉnh và liên bang như GST, PST hoặc QST của Canada).
  • Giá bao gồm thuế: Đối với những thị trường tính thuế gộp vào giá, subtotal phải bao gồm thuế, bạn nên bỏ qua mục dòng tax và phải cung cấp rõ ràng display_text cho các mục subtotal và fulfillment trong totals. Hãy xem bài viết Giá bao gồm thuế để biết thông tin chi tiết.
// Response Example: Initialize Session with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "path": "$.buyer",
      "content_type": "plain",
      "content": "Buyer information is required for checkout",
      "severity": "recoverable"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "path": "$.fulfillment.methods[0].destinations[0]",
      "content_type": "plain",
      "content": "Shipping address is incomplete",
      "severity": "recoverable"
    }
  ],
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 10000
        },
        {
          "type": "total",
          "amount": 10000
        }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        {
          "type": "subtotal",
          "amount": 2500
        },
        {
          "type": "total",
          "amount": 2500
        }
      ]
    }
  ],
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal", // Tax-inclusive markets: Set to "Subtotal (including taxes)".
      "amount": 12500 // Tax-inclusive markets: Amount must include tax.
    },
    {
      "type": "fee",
      "display_text": "Fees",
      "amount": 549,
      "lines": [
        { "display_text": "Service Fee", "amount": 399 },
        { "display_text": "Recycling Fee", "amount": 150 }
      ]
    },
    {
      "type": "fulfillment",
      "display_text": "Ground Shipping", // Tax-inclusive markets: Provide display text for fulfillment totals.
      "amount": 500
    },
    {
      "type": "tax", // Tax-inclusive markets: Omit this entry.
      "display_text": "Estimated Tax",
      "amount": 1050
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 14599
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Sunnyvale",
            "address_region": "CA",
            "postal_code": "94089",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": [
              "line_1",
              "line_2"
            ],
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 500} ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ {"type": "total", "amount": 1500} ]
              }
            ],
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

Giá đã bao gồm thuế

Đối với những thị trường mà thuế được tính vào tổng phụ hiển thị thay vì được liệt kê riêng, bạn phải tuân thủ các yêu cầu sau khi cung cấp dữ liệu phiên thanh toán:

  • Bao gồm thuế trong giá trị bán phần: Trường amount cho mục subtotal phải bao gồm tất cả các khoản thuế hiện hành.
  • Bỏ qua các mục thuế riêng biệt: Đừng thêm một đối tượng chuyên biệt có type: "tax" trong mảng totals.
  • Cung cấp văn bản hiển thị tuỳ chỉnh: Bạn phải thêm một thuộc tính display_text trong đối tượng tổng phụ để nêu rõ rằng thuế đã được tính, chẳng hạn như "Subtotal (including taxes)". Bạn cũng phải thêm một thuộc tính display_text cho các mục thực hiện đơn hàng (ví dụ: "Shipping").

Ví dụ: Mảng tổng số bao gồm thuế

Ví dụ sau đây minh hoạ một mảng totals cho một người bán ở thị trường có thuế:

"totals": [
  {
    "type": "subtotal",
    "display_text": "Subtotal (including taxes)",
    "amount": 12500
  },
  {
    "type": "fulfillment",
    "display_text": "Shipping",
    "amount": 399
  },
  {
    "type": "total",
    "display_text": "Total",
    "amount": 12899
  }
]

Phân loại thuế theo nhiều cấp

Đối với những thị trường yêu cầu thông tin công bố thuế nhiều cấp hoặc nhiều khu vực tài phán (chẳng hạn như GST hoặc HST của liên bang Canada và PST hoặc QST của tỉnh), bạn có thể cung cấp một đối tượng type: "tax" cấp cao nhất có mảng lines lồng nhau:

  • Tổng hợp thuế cấp cao nhất: Trả về một đối tượng tax tổng hợp duy nhất chứa tổng thuế amount và một display_text mô tả (ví dụ: "Taxes").
  • Bảng chi tiết dòng phụ: Liệt kê từng thành phần thuế trong mảng lines cùng với display_text tương ứng (ví dụ: "TPS / GST (5%)", "TVQ / QST (9.975%)") và amount.
  • Bất biến: Tổng số tiền của tất cả các mục phụ phải bằng amount của mục tax gốc.

Ví dụ: Bảng chi tiết thuế theo nhiều cấp

{
  "type": "tax",
  "display_text": "Taxes",
  "amount": 1498,
  "lines": [
    { "display_text": "TPS / GST (5%)", "amount": 500 },
    { "display_text": "TVQ / QST (9.975%)", "amount": 998 }
  ]
}

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ã 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), hãy 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. Đối với một phiên nhiều mặt hàng được tạo trong phiên bản 2026-01-23 trở lên, mảng line_items sẽ chứa nhiều mục nhập mặt hàng.

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}

Cập nhật địa chỉ giao hàng

  • Điều kiện kích hoạt: Người dùng chọn hoặc thay đổi địa chỉ giao hàng.

Yêu cầu: Google cập nhật địa chỉ thực hiện đơn hàng khi người dùng thay đổi địa chỉ giao hàng.

// Request Example: Update shipping address with multiple items.
{
  "line_items": [
    {
      // line_items id from Create Checkout response
      "id": "line_1",
      "item": {
        "id": "product_12345"
      },
      "quantity": 1
    },
    {
      // line_items id from Create Checkout response
      "id": "line_2",
      "item": {
        "id": "product_67890"
      },
      "quantity": 1
    }
  ],
  "context": {
    "language": "en"
  },
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": [
          "line_1",
          "line_2"
        ],
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "selected_destination_id": "addr_1",
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

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.

// Response Example: Updated session with new address for multiple items.
{
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "currency": "USD",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     // Shipping cost might change based on new address
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
     {
       "type": "fee",
       "display_text": "Fees",
       "amount": 549,
       "lines": [
         { "display_text": "Service Fee", "amount": 399 },
         { "display_text": "Recycling Fee", "amount": 150 }
       ]
     },
     // Tax will likely change based on new address
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  }
  // ... other fields like ucp, status, messages, links
}

Hoàn tất quá trình truyền dữ liệu cho đối tượng thanh toán

Yêu cầu: Google gửi toàn bộ đối tượng thanh toán có thông tin mới cập nhật (bao gồm cả địa chỉ thực hiện đơn hàng đầy đủ và thông tin liên hệ của người mua) khi người mua nhấp vào "Thanh toán bằng GPay".

// Request Example: full checkout object hydration for multiple items.
{
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": { "id": "product_12345" },
      "quantity": 1
    },
    {
      "id": "line_2",
      "item": { "id": "product_67890" },
      "quantity": 1
    }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "selected_option_id": "ship_ground"
          }
        ]
      }
    ]
  }
}

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.

// Response Example: Session after full hydration with multiple items.
{
  "ucp": {
    "version": "2026-04-08",
    "status": "success",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-04-08" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-04-08", "extends": "dev.ucp.shopping.checkout" } ]
    },
    "payment_handlers": {
      "com.google.pay": [
        {
          "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
          "version": "2026-01-23",
          "spec": "https://pay.google.com/gp/p/ucp/2026-01-23/",
          "schema": "https://pay.google.com/gp/p/ucp/2026-01-23/schemas/config.json",
          "config": {
            "api_version": 2,
            "api_version_minor": 0,
            "environment": "TEST",
            "merchant_info": {
              "merchant_name": "Example Merchant",
              "merchant_id": "KWMZPRLQFTYNXSDB",
              "merchant_origin": "checkout.merchant.com"
            },
            "allowed_payment_methods": [
              {
                "type": "CARD",
                "parameters": {
                  "allowed_auth_methods": [ "PAN_ONLY", "CRYPTOGRAM_3DS" ],
                  "allowed_card_networks": [ "AMEX", "DISCOVER", "JCB", "MASTERCARD", "VISA" ],
                  "billing_address_required": true,
                  "billing_address_parameters": {
                    "format": "FULL",
                    "phone_number_required": true
                  }
                },
                "tokenization_specification": {
                  "type": "PAYMENT_GATEWAY",
                  "parameters": {
                    "gateway": "example",
                    "gatewayMerchantId": "exampleGatewayMerchantId"
                  }
                }
              }
            ]
          }
        }
      ]
    }
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "ready_for_complete",
  "currency": "USD",
  "buyer": {
    "first_name": "John",
    "last_name": "Buyer",
    "email": "johnbuyer@example.com",
    "phone_number": "+18888888888"
  },
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000,
        "image_url": "https://merchant.example.com/images/product_12345.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 10000 },
        { "type": "total", "amount": 10000 }
      ]
    },
    {
      "id": "line_2",
      "item": {
        "id": "product_67890",
        "title": "T-Shirt",
        "price": 2500,
        "image_url": "https://merchant.example.com/images/product_67890.png"
      },
      "quantity": 1,
      "totals": [
        { "type": "subtotal", "amount": 2500 },
        { "type": "total", "amount": 2500 }
      ]
    }
  ],
  "totals": [
     { "type": "subtotal", "display_text": "Subtotal", "amount": 12500 },
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
      {
        "type": "fee",
        "display_text": "Fees",
        "amount": 549,
        "lines": [
          { "display_text": "Service Fee", "amount": 399 },
          { "display_text": "Recycling Fee", "amount": 150 }
        ]
      },
     { "type": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14769 }
  ],
  "fulfillment": {
    "methods": [
      {
        "id": "method_shipping",
        "type": "shipping",
        "line_item_ids": ["line_1", "line_2"],
        "selected_destination_id": "addr_1",
        "destinations": [
          {
            "id": "addr_1",
            "first_name": "Alice",
            "last_name": "Receiver",
            "street_address": "1600 Amphitheatre Pkwy",
            "extended_address": "Suite #60",
            "address_locality": "Mountain View",
            "address_region": "CA",
            "postal_code": "94043",
            "address_country": "US",
            "phone_number": "+18888888888"
          }
        ],
        "groups": [
          {
            "id": "group_1",
            "line_item_ids": ["line_1", "line_2"],
            "selected_option_id": "ship_ground",
            "options": [
              {
                "id": "ship_ground",
                "title": "Ground (3-5 days)",
                "description": "Estimated Delivery: Fri 5/8", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 600 } ]
              },
              {
                "id": "ship_express",
                "title": "Express (1-2 days)",
                "description": "Estimated Delivery: Wed 5/6", // Maximum length: 200 characters.
                "totals": [ { "type": "total", "amount": 1600 } ]
              }
            ]
          }
        ]
      }
    ]
  },
  "links": [
    {
      "type": "terms_of_service",
      "url": "https://m.com/terms",
      "title": "Terms of Service"
    },
    {
      "type": "privacy_policy",
      "url": "https://m.com/privacy",
      "title": "Privacy Policy"
    }
  ]
}

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.

Yêu cầu: Google gửi công cụ thanh toán đã chọn từ trình xử lý thanh toán, bao gồm cả thông tin xác thực (ví dụ: dữ liệu mã hoá bằng mã thông báo Google Pay) và tín hiệu rủi ro về người mua để bạn tự thực hiện quy trình phát hiện hành vi gian lận. Nội dung của mã thông báo sẽ tuỳ thuộc vào Nhà cung cấp dịch vụ thanh toán của bạn.

{
  "payment": {
    "instruments": [
      {
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        },
        "credential": {
          "token": "examplePaymentMethodToken",
          "type": "PAYMENT_GATEWAY"
        },
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "selected": true,
        "type": "card"
      }
    ]
  },
  "signals": {
    "com.google.authentication_triggered": "",
    "com.google.authorization_processed_with_3ds": "",
    "com.google.avs_full_result": "",
    "com.google.cvv_result": "",
    "com.google.ip_address": "203.0.113.1",
    "dev.ucp.buyer_id": "ec46fedc6aad89d3660a50a61d00b4908fd160ecf5dda6d49ed41a605c5b180a",
    "dev.ucp.buyer_ip": "203.0.113.1"
  }
}

Nếu cần thông tin bắt buộc để hoàn tất quy trình thanh toán nhưng thông tin đó chưa được cung cấp trong phiên thanh toán, bạn có thể ngăn người dùng hoàn tất quy trình thanh toán và yêu cầu họ cung cấp thông tin đó bằng cách trả về trạng thái chưa hoàn tất trong phản hồi.

Nếu Google có thể thu thập thông tin còn thiếu bằng cách sử dụng các trường do UCP xác định (ví dụ: địa chỉ email của người mua), hãy đặt status thành incomplete và thêm một hoặc nhiều thông báo vào mảng messages với severity được đặt thành recoverable, cho biết thông tin nào còn thiếu.

{
  "ucp": {
    "version": "2026-04-08",
    "status": "success"
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "incomplete",
  "messages": [
    {
      "type": "error",
      "code": "missing_buyer_info",
      "severity": "recoverable",
      "content": "Buyer email is required"
    },
    {
      "type": "error",
      "code": "missing_fulfillment_info",
      "severity": "recoverable",
      "content": "Select delivery window for your purchase"
    }
  ]
}

Khi nhận được một phương thức thanh toán trên Google Pay, bạn phải:

  1. Xác thực trình xử lý: Xác nhận handler_id tương ứng với trình xử lý thanh toán Google Pay được xác định trong cấu hình của bạn.
  2. Trích xuất mã thông báo: Truy xuất mã thông báo phương thức thanh toán đã tạo từ payment.instruments[0].credential.token.
  3. Xử lý thanh toán: Sử dụng mã thông báo và chi tiết giao dịch để hoàn tất thanh toán. Hãy tham khảo tài liệu về Google Pay API để biết tài liệu chi tiết về quy cách và cách xử lý mã hoá.

Phản hồi: Nếu có thể hoàn tất quy trình thanh toán và bạn đã xử lý khoản thanh toán, bạn sẽ 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ả phương thức thanh toán đã xác nhận (phản hồi siêu dữ liệu phương thức và địa chỉ thanh toán, không có mã thông báo credential nhạy cảm hoặc signals), mã đơn đặt hàng và URL liên kết cố định đến đơn đặt hàng.

{
  "ucp": {
      "version": "2026-04-08",
      "status": "success",
      "capabilities": [...]
  },
  "id": "bf8c1b4b-6b1c-4c6a-8f2a-53c2a7c3b2e1",
  "status": "completed",

  // ... other fields (line_items, currency, etc.)

  "payment": {
    "instruments": [
      {
        "id": "94e7fee0-1a82-4c2a-9ef4-0861a3c829b2",
        "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "type": "card",
        "selected": true,
        "display": {
          "brand": "VISA",
          "description": "Visa •••• 1234",
          "last_digits": "1234"
        },
        "billing_address": {
          "first_name": "John",
          "last_name": "Buyer",
          "street_address": "100 Main St",
          "extended_address": "Apt 4B",
          "address_locality": "San Francisco",
          "address_region": "CA",
          "postal_code": "94105",
          "address_country": "US",
          "phone_number": "+18888888888"
        }
      }
    ]
  },
  "order": {
    "id": "ORD1773956535.2727807",
    // Example customer-facing order number
    "label": "#100",
    "permalink_url": "https://merchant.example.com/orders/789"
  }
}

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ã 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.

Xử lý lỗi

Để biết toàn bộ nguyên tắc về cách định dạng thông báo lỗi và sự khác biệt giữa lỗi giao thức và lỗi logic nghiệp vụ, hãy xem Tổng quan về mã lỗi.

Lỗi không thể khôi phục

Bắt đầu từ phiên bản 2026-04-08, khi một lỗi không thể khắc phục ngăn việc tạo phiên thanh toán (ví dụ: tất cả mặt hàng đều hết hàng), hãy trả về một HTTP 200 OK. Trong nội dung phản hồi, hãy đặt "status": "error" trong đối tượng ucp. Điều này cho Google biết rằng yêu cầu này hợp lệ, nhưng một quy tắc kinh doanh đã chặn việc tạo phiên. Trong trường hợp này, không có mã phiên thanh toán nào được trả về.

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ucp": {
    "version": "2026-04-08",
    "status": "error"
  },
  "messages": [
    {
      "type": "error",
      "code": "out_of_stock",
      "content": "All requested items are currently out of stock",
      "severity": "unrecoverable"
    }
  ],
  "continue_url": "https://merchant.com/"
}