Doğrudan ödeme REST API'si uygulaması

Bu kılavuzda, Evrensel Ticaret Protokolü (UCP) doğrudan ödeme sayfasının 2026-04-08 sürümü için teknik API referansı ve yük şemaları sağlanmaktadır.

Uç noktalarınızı oluşturmadan önce, üst düzey ödeme adımları, kimlik doğrulama koşulları ve geliştirici araçları için Yerel ödeme genel bakış bölümünü incelediğinizden emin olun.

Ödeme oturumu oluşturma

Bu uç nokta, kullanıcının satın almak istediği ürünleri içeren bir ödeme oturumu oluşturulmasına olanak tanır.

  • Uç nokta: POST /checkout-sessions
  • Tetikleyici: Kullanıcı, bir üründe "Hemen satın al"ı veya alışveriş sepetinde "Google'da ödeme"yi tıklar.

İstek: Google, satır öğelerini ve alıcıyla ilgili sınırlı adres bilgilerini (şehir, eyalet ve posta kodu dahil) gönderir.

// 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"
      }
    ]
  }
}

Yanıt: Başlatılan oturumu toplamlar, vergiler (başlangıçta tahmini) ve ödeme özellikleri ile birlikte döndürürsünüz.

ucp.status alanı ile ilgili not:

2026-04-08 sürümünde kullanıma sunulan ucp.status alanı, oluşturma sonucunu gösterir:

  • "success" (veya atlandı): Varsayılan. Kurtarılabilir messages olsa bile oturum oluşturuldu.
  • "error": Oturum oluşturma, kurtarılamayan bir hata nedeniyle başarısız oldu (ör. tüm öğeler stokta yok). Bu durumda, yanıt gövdesi bir ödeme nesnesi değil, hata yanıtı nesnesi olmalıdır. Hata işleme bölümündeki Kurtarılamayan Hata örneği'ne bakın.

totals dizisi değişiklikleriyle ilgili not:

  • totals dizisindeki her nesnenin type alanı artık açık bir dizedir.
  • amount alanı artık negatif olabilir (ör. indirimleri göstermek için).
  • totals içindeki nesneler (ör.type: "fee" ve type: "tax"), alt bileşenleri (ör. hizmet veya geri dönüşüm ücretleri ya da Kanada GST, PST veya QST gibi çok katmanlı eyalet ve federal vergi dökümleri) ayrıntılandırmak için isteğe bağlı olarak bir lines dizisi içerebilir.
  • Vergi dahil fiyatlandırma: Vergi dahil fiyatlandırmanın geçerli olduğu pazarlarda subtotal, vergi içermelidir. tax satır öğesi atlanmalı ve totals içindeki subtotal ve fulfillment girişleri için display_text açıkça sağlanmalıdır. Ayrıntılar için Vergi dahil fiyatlandırma bölümüne bakın.
// 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"
    }
  ]
}

Vergi dahil fiyatlandırma

Verginin ayrı ayrı listelenmek yerine gösterilen alt toplama dahil edildiği pazarlarda, ödeme oturumu verileri sağlanırken uygulamanız aşağıdaki koşullara uymalıdır:

  • Alt toplama vergiyi dahil et: subtotal girişi için amount alanı, geçerli tüm vergileri içermelidir.
  • Ayrı vergi girişlerini atlayın: totals dizisine type: "tax" içeren özel bir nesne eklemeyin.
  • Özel görüntülü reklam metni sağlayın: Alt toplam nesnesine, vergilerin dahil olduğunu açıkça belirten bir display_text özellik eklemeniz gerekir. Örneğin: "Subtotal (including taxes)". Ayrıca, karşılama girişleri için bir display_text özelliği (ör. "Shipping") de eklemeniz gerekir.

Örnek: Vergi dahil toplamlar dizisi

Aşağıdaki örnekte, vergi dahil pazardaki bir satıcı için totals dizisi gösterilmektedir:

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

Çok katmanlı vergi dökümü

Ayrıntılı çok katmanlı veya çok yargı alanlı vergi açıklamaları gerektiren pazarlar için (ör. Kanada federal GST veya HST ve eyalet PST veya QST) iç içe yerleştirilmiş bir lines dizisi içeren üst düzey bir type: "tax" nesnesi sağlayabilirsiniz:

  • Üst düzey vergi toplama: Toplam vergiyi tax içeren tek bir toplama nesnesi amount ve açıklayıcı bir display_text (ör. "Taxes") döndürün.
  • Alt satır dökümü: lines dizisindeki ayrı vergi bileşenlerini ilgili display_text (ör. "TPS / GST (5%)", "TVQ / QST (9.975%)") ve amount ile birlikte ayrıntılı olarak listeleyin.
  • Değişmez: Tüm alt satır tutarlarının toplamı, üst tax girişinin amount değerine eşit olmalıdır.

Örnek: Çok katmanlı vergi dökümü

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

Ödeme oturumu alma

Bu uç nokta, ödeme oturumunun alınmasına olanak tanır.

  • Uç nokta: GET /checkout-sessions/{id}

İstek: Google, ödeme oturumunun kimliğini gönderir. Global kimlikler (ör. gid://merchant.example.com/Checkout/session_abc123) kullanıyorsanız istek yolundaki kimliğin yalnızca bu kimliğin son bileşeni (ör. session_abc123) olacağını unutmayın.

Yanıt: Ödeme nesnesinin tamamını döndürürsünüz. 2026-01-23 veya sonraki bir sürümde oluşturulan çok öğeli bir oturum için line_items dizisi birden fazla öğe girişi içerir.

Ödeme oturumunu güncelleme

Bu uç nokta, ödeme oturumunun güncellenmesine olanak tanır. Kargo adresi güncellendiğinde vergileri ve kargo seçeneklerini yeniden hesaplayıp döndürmesi gerekir.

  • Uç nokta: PUT /checkout-sessions/{id}

Kargo adresini güncelleme

  • Tetikleyici: Kullanıcı, kargo adresini seçer veya değiştirir.

İstek: Kullanıcı kargo adresini değiştirdiğinde Google, karşılama adresini günceller.

// 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"
          }
        ]
      }
    ]
  }
}

Yanıt: Vergileri ve kargo seçeneklerini gerektiği gibi yeniden hesaplar ve tam ödeme nesnesini döndürürsünüz.

// 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
}

Ödeme nesnesinin tam hydration'ı

İstek: Alıcı "GPay ile öde"yi tıkladığında Google, güncellenmiş bilgilerle (tam sipariş adresi ve alıcı iletişim bilgileri dahil) birlikte tam ödeme nesnesini gönderir.

// 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"
          }
        ]
      }
    ]
  }
}

Yanıt: Vergileri ve kargo seçeneklerini gerektiği gibi yeniden hesaplar ve tam ödeme nesnesini döndürürsünüz.

// 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"
    }
  ]
}

Ödeme oturumunu tamamlayın

Bu uç nokta, ödeme oturumunun tamamlanmasına ve sipariş verilmesine olanak tanır. Tamamlanan ödeme oturumunu döndürmeli ve sipariş bilgilerini içermelidir. Ödeme işleme, bu görüşme alındıktan sonra başlamalıdır.

İstek: Google, kendi sahtekarlık tespitinizi yapabilmeniz için ödeme işleyiciden kimlik bilgisi (ör. Google Pay jetonlaştırma verileri) ve alıcıyla ilgili risk sinyalleri dahil olmak üzere seçilen ödeme aracını gönderir. Jeton içerikleri, ödeme hizmeti sağlayıcınıza bağlıdır.

{
  "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"
  }
}

Ödeme işleminin tamamlanması için zorunlu olan ve ödeme oturumunda sağlanmamış bilgiler gerekiyorsa yanıtta tamamlanmamış bir durum döndürerek ödeme işleminin tamamlanmasını engelleyebilir ve bu bilgileri isteyebilirsiniz.

Google, eksik bilgileri UCP tarafından tanımlanan alanları kullanarak toplayabiliyorsa (örneğin, alıcının e-posta adresi) status değerini incomplete olarak ayarlayın ve messages dizisine severity değeri recoverable olarak ayarlanmış bir veya daha fazla mesaj ekleyerek hangi bilgilerin eksik olduğunu belirtin.

{
  "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"
    }
  ]
}

Google Pay ödeme aracı aldıktan sonra:

  1. İşleyiciyi doğrulama: handler_id öğesinin, yapılandırmanızda tanımlanan Google Pay ödeme işleyicisine karşılık geldiğini onaylayın.
  2. Jetonu ayıklama: Oluşturulan ödeme yöntemi jetonunu payment.instruments[0].credential.token konumundan alın.
  3. Ödemeyi işleme: Ödemeyi tamamlamak için jetonu ve işlem ayrıntılarını kullanın. Tokenleştirme spesifikasyonu ve işleme hakkında ayrıntılı dokümanlar için Google Pay API belgelerine bakın.

Yanıt: Ödeme işlemi tamamlanabiliyorsa ve ödemeyi işlediyseniz siparişin tamamlandığını belirten tam ödeme nesnesini döndürürsünüz. Bu nesne, onaylanmış ödeme aracını (hassas credential jetonu veya signals olmadan araç meta verilerini ve fatura adresini yansıtarak), sipariş kimliğini ve siparişe yönelik bir sabit bağlantı URL'sini içerir.

{
  "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"
  }
}

Ödeme oturumunu iptal etme

Bu uç nokta, ödeme oturumunu iptal eder.

  • Uç nokta: POST /checkout-sessions/{id}/cancel

İstek: Google, ödeme oturumunun kimliğini gönderir.

Yanıt: Durumu canceled olarak güncellenmiş tam ödeme nesnesini döndürürsünüz.

Hata işleme

Hata mesajlarını biçimlendirme ve protokol ile iş mantığı hataları arasındaki fark hakkında eksiksiz yönergeler için Hata kodlarına genel bakış başlıklı makaleyi inceleyin.

Düzeltilemeyen Hata

2026-04-08 sürümünden itibaren, kurtarılamayan bir hata ödeme oturumu oluşturulmasını engellediğinde (ör. tüm öğeler stokta yok) HTTP 200 OK döndürülür. Yanıt gövdesinde, "status": "error" değerini ucp nesnesi içinde ayarlayın. Bu, Google'a isteğin geçerli olduğunu ancak bir işletme kuralının oturum oluşturmayı engellediğini bildirir. Bu durumda ödeme oturumu kimliği döndürülmez.

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/"
}