Implementazione dell'API REST per il checkout nativo

Questa guida fornisce il riferimento tecnico dell'API e gli schemi del payload per la versione 2026-04-08 dell'acquisto rapido nativo di Universal Commerce Protocol (UCP).

Prima di creare gli endpoint, assicurati di aver esaminato la panoramica del checkout nativo per il flusso di checkout di alto livello, i requisiti di autenticazione e gli strumenti per sviluppatori.

Crea sessione di pagamento

Questo endpoint consente la creazione di una sessione di pagamento contenente i prodotti che un utente è interessato ad acquistare.

  • Endpoint: POST /checkout-sessions
  • Trigger:l'utente fa clic su "Acquista ora" su un prodotto o su "Pagamento rapido su Google" dal carrello.

Richiesta:Google invia gli elementi pubblicitari e informazioni sull'indirizzo limitate dell'acquirente, tra cui città, stato e codice postale.

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

Risposta:restituisci la sessione inizializzata con totali, tasse (inizialmente stimate) e funzionalità di pagamento.

Nota sul campo ucp.status:

Introdotto nella versione 2026-04-08, il campo ucp.status indica il risultato della creazione:

  • "success" (o omesso): impostazione predefinita. Sessione creata, anche con messages recuperabili.
  • "error": la creazione della sessione non è riuscita a causa di un errore irreversibile (ad es. tutti gli articoli non sono disponibili). In questo caso, il corpo della risposta deve essere un oggetto di risposta di errore, non un oggetto di pagamento. Consulta l'esempio di errore irrecuperabile nella sezione Gestione degli errori.

Nota sulle modifiche all'array totals:

  • Il campo type all'interno di ogni oggetto dell'array totals ora è una stringa aperta.
  • Ora il campo amount può essere negativo (ad esempio, per rappresentare gli sconti).
  • Gli oggetti in totals (ad esempio type: "fee" e type: "tax") possono includere facoltativamente un array lines per elencare in dettaglio i sottocomponenti (ad es. commissioni di servizio o riciclaggio o suddivisioni fiscali provinciali e federali a più livelli come GST, PST o QST canadesi).
  • Prezzi comprensivi di tasse:per i mercati in cui i prezzi devono essere comprensivi di tasse, l'attributo subtotal deve includere le tasse, la voce di tax deve essere omessa e l'attributo display_text deve essere fornito esplicitamente per le voci subtotal e fulfillment in totals. Per i dettagli, vedi Prezzi comprensivi di tasse.
// 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"
    }
  ]
}

Prezzi comprensivi di imposte

Per i mercati in cui l'imposta è inclusa nel subtotale visualizzato anziché essere dettagliata separatamente, l'implementazione deve rispettare i seguenti requisiti quando vengono forniti i dati della sessione di pagamento:

  • Includi imposte nel subtotale:il campo amount per la voce subtotal deve includere tutte le imposte applicabili.
  • Ometti le voci fiscali separate:non includere un oggetto dedicato con type: "tax" nell'array totals.
  • Fornisci un testo visualizzato personalizzato:devi includere un attributo display_text all'interno dell'oggetto subtotale che indichi esplicitamente che le tasse sono incluse, ad esempio "Subtotal (including taxes)". Devi includere anche un attributo display_text per le voci di evasione (ad es. "Shipping").

Esempio: array di totali comprensivi di tasse

L'esempio seguente mostra un array totals per un commerciante in un mercato con tasse incluse:

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

Ripartizione fiscale a più livelli

Per i mercati che richiedono informazioni fiscali dettagliate a più livelli o in più giurisdizioni (come l'imposta GST o HST federale canadese e l'imposta PST o QST provinciale), puoi fornire un oggetto type: "tax" di primo livello con un array lines nidificato:

  • Aggrega imposta di primo livello: restituisce un singolo oggetto tax aggregato contenente l'imposta totale amount e una descrizione display_text (ad es. "Taxes").
  • Suddivisione delle voci secondarie:elenca i singoli componenti fiscali nell'array lines con i rispettivi display_text (ad es. "TPS / GST (5%)", "TVQ / QST (9.975%)") e amount.
  • Invariante:la somma di tutti gli importi delle voci secondarie deve essere uguale a tax dell'amount della voce principale.

Esempio: ripartizione delle imposte a più livelli

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

Recupera sessione di pagamento

Questo endpoint consente il recupero di una sessione di checkout.

  • Endpoint: GET /checkout-sessions/{id}

Richiesta:Google invia l'ID della sessione di pagamento. Se utilizzi ID globali (ad es. gid://merchant.example.com/Checkout/session_abc123), tieni presente che l'ID nel percorso della richiesta sarà solo l'ultimo componente di questo ID (ad es. session_abc123).

Risposta:restituisci l'oggetto di pagamento completo. Per una sessione multi-articolo creata nella versione 2026-01-23 o successive, l'array line_items conterrà più voci di articoli.

Aggiorna la sessione di pagamento

Questo endpoint consente di aggiornare una sessione di pagamento. Quando l'indirizzo di spedizione viene aggiornato, è necessario ricalcolare e restituire le imposte e le opzioni di spedizione.

  • Endpoint: PUT /checkout-sessions/{id}

Aggiorna l'indirizzo di spedizione

  • Trigger:l'utente seleziona o modifica l'indirizzo di spedizione.

Richiesta:Google aggiorna l'indirizzo di evasione quando l'utente modifica il proprio indirizzo di spedizione.

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

Risposta:ricalcola le tasse e le opzioni di spedizione in base alle necessità e restituisci l'intero oggetto di pagamento.

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

Idratazione completa dell'oggetto di pagamento

Richiesta: Google invia l'oggetto di pagamento completo con le informazioni aggiornate (inclusi l'indirizzo di evasione completo e i dati di contatto dell'acquirente) quando l'acquirente fa clic su "Paga con 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"
          }
        ]
      }
    ]
  }
}

Risposta:ricalcola le tasse e le opzioni di spedizione in base alle necessità e restituisci l'intero oggetto di pagamento.

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

Completa la sessione di pagamento

Questo endpoint consente di completare una sessione di pagamento e di effettuare un ordine. Deve restituire la sessione di pagamento completata e includere i dati dell'ordine. L'elaborazione del pagamento dovrebbe iniziare dopo la ricezione di questa chiamata.

Richiesta:Google invia lo strumento di pagamento selezionato dal gestore dei pagamenti, incluse le credenziali (ad es. dati di tokenizzazione di Google Pay) e gli indicatori di rischio relativi all'acquirente per consentirti di eseguire il tuo rilevamento delle frodi. I contenuti del token dipendono dal tuo fornitore di servizi di pagamento.

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

Se per completare il pagamento sono necessarie informazioni obbligatorie che non sono state fornite nella sessione di pagamento, puoi impedire il completamento del pagamento e richiedere queste informazioni restituendo uno stato non completato nella risposta.

Se Google può raccogliere le informazioni mancanti utilizzando i campi definiti da UCP (ad esempio, l'indirizzo email dell'acquirente), imposta status su incomplete e includi uno o più messaggi nell'array messages con severity impostato su recoverable, indicando quali informazioni mancano.

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

Al ricevimento di uno strumento di pagamento Google Pay, devi:

  1. Validate handler: conferma che handler_id corrisponde all'handler di pagamento Google Pay definito nella configurazione.
  2. Estrai token:recupera il token del metodo di pagamento generato da payment.instruments[0].credential.token.
  3. Elabora pagamento:utilizza il token e i dettagli della transazione per completare il pagamento. Per la documentazione dettagliata sulla gestione e sulle specifiche di tokenizzazione, consulta la documentazione dell'API Google Pay.

Risposta: se il pagamento può essere completato e lo hai elaborato, restituisci l'oggetto di pagamento completo che indica che l'ordine è stato completato, incluso lo strumento di pagamento confermato (con i metadati dello strumento e l'indirizzo di fatturazione, senza il token credential o signals), l'ID ordine e un URL permalink all'ordine.

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

Annulla sessione di pagamento

Questo endpoint annulla una sessione di pagamento.

  • Endpoint: POST /checkout-sessions/{id}/cancel

Richiesta:Google invia l'ID della sessione di pagamento.

Risposta:restituisci l'oggetto di pagamento completo con lo stato aggiornato a canceled.

Gestione degli errori

Per linee guida complete su come formattare i messaggi di errore e sulla distinzione tra errori di protocollo e di logica di business, consulta la panoramica dei codici di errore.

Errore irreversibile

A partire dalla versione 2026-04-08, quando un errore non recuperabile impedisce la creazione della sessione di pagamento (ad es. tutti gli articoli sono esauriti), restituisci un errore HTTP 200 OK. Nel corpo della risposta, imposta "status": "error" all'interno dell'oggetto ucp. Indica a Google che la richiesta era valida, ma una regola aziendale ha bloccato la creazione della sessione. In questo caso, non viene restituito alcun ID sessione di checkout.

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