Pagamento nativo

L'integrazione nativa richiede la creazione di un'API RESTful che Google possa chiamare per creare e gestire le sessioni di pagamento.

Il flusso generale è il seguente:

Crea sessione di pagamento:l'utente e, facoltativamente, un agente si trovano in un ciclo aggiungendo elementi alla sessione.
Trasferimento a un'interfaccia utente di Google:una volta che l'utente decide di eseguire il pagamento, l'agente (se coinvolto) passa il controllo a un'interfaccia utente di Google (trasmettendo i dati della sessione di pagamento)
Pagamento manuale:ora l'utente interagisce solo con l'interfaccia utente di Google per compilare i dettagli sensibili di evasione e pagamento e inviare l'ordine. L'agente non è coinvolto in questa parte, garantendo il determinismo.
Completamento e restituzione: l'interfaccia utente di Google mostra una pagina di ringraziamento per confermare l'ordine. Facoltativamente, l'utente può essere reindirizzato all'agente, che potrebbe aver già ricevuto una notifica dell'acquisto completato.

I passaggi seguenti descrivono gli endpoint API che dovrai implementare e i relativi comportamenti.

1. 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
Attivatore: l'utente fa clic su "Acquista" su un prodotto.

Richiesta:Google invia gli elementi pubblicitari e la valuta.

{
  "line_items": [
    {
      "item": {
        "id": "product_12345", // Must match Product Feed ID
        "title": "Running Shoes"
      },
      "quantity": 1
    }
  ],
  "currency": "USD"
}

Risposta:restituisci la sessione inizializzata con totali, tasse (inizialmente stimate) e funzionalità di pagamento. Devi includere i link ai tuoi termini di servizio e alle norme sulla privacy, che verranno visualizzati sotto il pulsante di pagamento.

{
  "ucp": {
    "version": "2026-01-11",
    "capabilities": [
      {
        "name": "dev.ucp.shopping.checkout",
        "version": "2026-01-11"
      },
      {
        "name": "dev.ucp.shopping.fulfillment",
        "version": "2026-01-11"
      }
    ]
  },
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "status": "incomplete",
  "line_items": [
    {
      "id": "line_1",
      "item": {
        "id": "product_12345",
        "title": "Running Shoes",
        "price": 10000
      },
      "quantity": 1,
      "base_amount": 10000,
      "subtotal": 10000,
      "total": 10000
    }
  ],
  "totals": [
    { "type": "subtotal", "amount": 10000 }, // in cents
    { "type": "tax", "amount": 0 },
    { "type": "total", "amount": 10000 }
  ],
  "payment": {
    "handlers": [
      {
        "id": "gpay",
        "name": "com.google.pay",
        "config": {
           "api_version": 2,
           "api_version_minor": 0,
           "merchant_info": {
             "merchant_id": "12345678901234567890",
             "merchant_name": "Example Merchant"
           },
           "allowed_payment_methods": [
             {
               "type": "CARD",
               "parameters": {
                 "allowed_auth_methods": ["PAN_ONLY", "CRYPTOGRAM_3DS"],
                 "allowed_card_networks": ["VISA", "MASTERCARD"]
               },
               "tokenization_specification": {
                 "type": "PAYMENT_GATEWAY",
                 "parameters": {
                   "gateway": "stripe",
                   "gateway_merchant_id": "exampleGatewayMerchantId"
                 }
               }
             }
           ]
        }
      }
    ]
  },
  "links": [
    { "type": "privacy_policy", "url": "https://m.com/privacy" },
    { "type": "terms_of_service", "url": "https://m.com/terms" }
  ]
}

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

3. Aggiorna sessione di pagamento

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

Endpoint: PUT /checkout-sessions/{id}
Attivazione: l'utente seleziona o modifica l'indirizzo di spedizione, aggiorna la selezione di spedizione o aggiorna i dati di pagamento.

Richiesta:Google invia l'oggetto di pagamento completo con le informazioni aggiornate.

{
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "buyer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com"
  },
  "fulfillment": {
     "methods": [
       {
         "type": "shipping",
         "destinations": [
           {
             "id": "dest_1",
             "postal_code": "94043",
             "country": "US",
             "address_locality": "Mountain View",
             "address_region": "CA"
           }
         ],
         "selected_destination_id": "dest_1"
       }
     ]
  },
  "payment": {
    "selected_instrument_id": "pi_gpay_5678",
    "instruments": [
      {
        "id": "pi_gpay_5678",
        "handler_id": "gpay",
        "type": "card",
        "brand": "mastercard",
        "last_digits": "5678",
        "rich_text_description": "Google Pay •••• 5678"
      }
    ]
  }
  // ... other fields (line_items, currency, etc.)
}

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

{
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "totals": [
     { "type": "subtotal", "amount": 10000 },
     { "type": "shipping", "display_text": "Ground Shipping", "amount": 500 },
     { "type": "tax", "amount": 850 },
     { "type": "total", "amount": 11350 }
  ],

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

  "fulfillment": {
      "methods": [
          {
            "id": "method_shipping",
            "type": "shipping",
            "line_item_ids": ["line_1"],
            "selected_destination_id": "dest_1",
            "destinations": [
               {
                 "id": "dest_1",
                 "postal_code": "94043",
                 "country": "US",
                 "address_locality": "Mountain View",
                 "address_region": "CA"
               }
            ],
            "groups": [
              {
                "id": "group_1",
                "line_item_ids": ["line_1"],
                "selected_option_id": "ship_ground",
                "options": [
                  {
                    "id": "ship_ground",
                    "title": "Ground (3-5 days)",
                    "total": 500
                  },
                  {
                    "id": "ship_express",
                    "title": "Express (1-2 days)",
                    "total": 1500
                  }
                ]
              }
            ]
          }
      ]
  }
}

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

Endpoint: POST /checkout-sessions/{id}/complete
Trigger:l'utente fa clic su "Effettua ordine".

Richiesta:Google invia il token di pagamento (blob criptato) dal fornitore (ad es. Google Pay) e indicatori di rischio sull'acquirente per eseguire il rilevamento delle frodi.

{
  "payment_data": {
    "id": "pi_gpay_5678",
    "handler_id": "gpay",
    "type": "card",
    "brand": "mastercard",
    "last_digits": "5678",
    "billing_address": {
      "postal_code": "94043",
      "address_country": "US"
    },
    "credential": {
       "type": "PAYMENT_GATEWAY",
       "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  }
}

Risposta:restituisci l'oggetto di pagamento completo che indica che l'ordine è completo, inclusi l'ID ordine e un URL permalink all'ordine.

{
  "ucp": {
      "version": "2026-01-11",
      "capabilities": [...]
  },
  "id": "gid://merchant.example.com/Checkout/session_abc123",
  "status": "completed",

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

  "order_id": "gid://merchant.example.com/Order/789",
  "order_permalink_url": "https://merchant.example.com/orders/789"
}