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-01-23 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.

// Response Example: Initialize Session with multiple items.
{
  "ucp": {
    "version": "2026-01-23",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "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": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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": "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": 100
    },
    {
      "type": "total",
      "amount": 13100
    }
  ],
  "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
  }
]

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
    }
  ],
  "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": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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", "amount": 12500 },
     // Shipping cost might change based on new address
     { "type": "fulfillment", "display_text": "Ground Shipping", "amount": 600 },
     // Tax will likely change based on new address
     { "type": "tax", "amount": 1120 },
     { "type": "total", "amount": 14220 }
  ],
  "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-01-23",
    "capabilities": {
      "dev.ucp.shopping.checkout": [ { "version": "2026-01-23" } ],
      "dev.ucp.shopping.fulfillment": [ { "version": "2026-01-23", "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": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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": "tax", "display_text": "Estimated Tax", "amount": 1120 },
     { "type": "total", "display_text": "Total", "amount": 14220 }
  ],
  "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.

{
  "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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-01-23",
      "capabilities": [...]
  },
  "id": "da2e25ec-eef8-41b7-a439-4e62dea41bdc",
  "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

Đối với phiên bản 2026-01-23, khi một lỗi logic nghiệp vụ 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 200 OK HTTP.

Trong phiên bản 2026-01-23, bạn phải cho biết lỗi không thể khắc phục bằng cách bỏ qua mã phiên thanh toán và chỉ định "severity": "unrecoverable" trong mảng messages. Đ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.

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

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