Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Vendita di beni fisici: flussi di pagamento

Lezione 7 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Cosa puoi vendere
  2. Flusso 1: Pagamento esterno, il percorso predefinito
  3. Flusso 2: Metodi di pagamento salvati in precedenza
  4. Flusso 3: La scheda di checkout di ChatGPT (beta privata)
  5. Il server è la fonte della verità
  6. Mantieni gli strumenti utili disponibili senza UI
  7. Punti chiave

Lezione riscritta il 3 novembre 2026 sulla base del riferimento API Checkout, della pagina Aggiungi UI al tuo server MCP e delle Linee guida sui plugin di OpenAI. La versione precedente trattava la vendita di abbonamenti e prodotti digitali utilizzando funzioni inventate (defineProduct, commerceFlow) e una struttura di commissione del 30%/15% senza fonti. Le regole attuali sui plugin limitano il commercio ai soli beni fisici e la documentazione non menziona commissioni. Fonti: Riferimento API Checkout · Linee guida sui plugin.

Cosa puoi vendere

Inizia dalla regola, perché governa tutto il resto. Le regole di pubblicazione di OpenAI sono chiare: un plugin può effettuare transazioni commerciali solo per beni fisici. La vendita di prodotti digitali o servizi—abbonamenti, contenuti digitali, token, crediti—è vietata, sia direttamente che indirettamente (ad esempio, tramite un upsell freemium). Si applica anche un elenco di beni e servizi vietati (contenuti per adulti, giochi d’azzardo, farmaci da prescrizione, armi, tabacco e nicotina, software piratati, servizi finanziari fuorvianti, tra gli altri). La Lezione 13 rivede cosa può ancora fare un servizio in abbonamento entro questi limiti.

In questo quadro, OpenAI documenta tre flussi di pagamento.

Flusso 1: Pagamento esterno, il percorso predefinito

Il pagamento esterno è l’approccio raccomandato ed è disponibile per tutti. L’interfaccia utente del plugin presenta i prodotti idonei, ad esempio con un pulsante “Acquista”. Quando l’utente decide di acquistare, l’interfaccia lo reindirizza a un tunnel di checkout ospitato sul tuo dominio. Prezzi, riscossione, tasse, sconti, spedizione, rimborsi, assistenza e conformità rimangono interamente tua responsabilità. Dopo l’acquisto, l’utente può tornare su ChatGPT con la conferma dell’ordine o il tracking della spedizione.

Per aprire questo link, ChatGPT fornisce l’estensione window.openai.openExternal({ href }), che apre un link controllato nel browser dell’utente. Devi dichiarare le destinazioni di reindirizzamento consentite in _meta["openai/widgetCSP"].redirect_domains: la policy standard _meta.ui.csp non copre questo caso. Per una destinazione approvata, ChatGPT aggiunge di default un parametro ?redirectUrl=… all’indirizzo; impostando redirectUrl: false lo si previene.

function openPayment(cartUrl) {
  if (window.openai?.openExternal) {
    window.openai.openExternal({ href: cartUrl });
  } else {
    // L'host non ha questa estensione: lascia che l'utente copi il link
    document.querySelector("#payment-link").textContent = cartUrl;
  }
}

Le regole sono specifiche: finché il pagamento integrato non è aperto al tuo plugin, il pagamento esterno è il percorso obbligatorio. Nessuna altra soluzione di pagamento di terze parti può essere integrata o ospitata nell’interfaccia utente del plugin.

Flusso 2: Metodi di pagamento salvati in precedenza

Per acquisti idonei di beni fisici, l’interfaccia utente può offrire al cliente un metodo di pagamento che ha già salvato con te. L’utente seleziona questo metodo e conferma l’acquisto all’interno di ChatGPT, senza lasciare la conversazione. Il tuo server MCP elabora l’ordine e restituisce la conferma vincolante. Questo flusso può visualizzare i metodi di pagamento salvati, ma non può raccogliere nuovi dettagli di pagamento.

Flusso 3: La scheda di checkout di ChatGPT (beta privata)

Per raccogliere un nuovo metodo di pagamento all’interno del flusso, hai bisogno della scheda di checkout di ChatGPT. Questa funzionalità di pagamento integrato è in beta privata, riservata a specifici marketplace, e non è accessibile a tutti gli sviluppatori o utenti. Il suo funzionamento vale la pena di essere compreso perché illustra la divisione dei ruoli tra l’host e il tuo server:

  1. Uno strumento MCP restituisce una sessione di pagamento in structuredContent.
  2. Il componente visualizza articoli, totali, termini e opzioni di spedizione.
  3. Quando l’utente sceglie di pagare, il componente chiama window.openai.requestCheckout(session); ChatGPT apre la sua scheda di checkout.
  4. Dopo la convalida, ChatGPT invia un token che rappresenta il metodo di pagamento scelto allo strumento complete_checkout del tuo server. Questo strumento addebita tramite il tuo provider di pagamento e restituisce l’ordine finalizzato: il risultato che il componente riceve in risposta a requestCheckout.

La sessione deve contenere un identificatore univoco, articoli e le loro quantità, totali in unità di valuta minori (centesimi, non euro decimali), provider di pagamento e metadati del commerciante, e link obbligatori: termini, privacy, rimborsi e assistenza. ChatGPT aggiunge i propri campi, come merchant o conversation_id.

Il server è la fonte della verità

Indipendentemente dal flusso, si applica la stessa disciplina:

  • I prezzi e lo stato dell’ordine provengono dal server, mai da un totale calcolato nel componente.
  • Il token di pagamento viene verificato, l’operazione è idempotente—un doppio clic non deve addebitare due volte—l’ordine viene registrato e viene restituita una ricevuta di riferimento.
  • L’annullamento, il rifiuto del pagamento e gli errori del provider sono gestiti nel componente. Per la scheda di checkout, gli errori payment_declined e requires_3ds restituiti da complete_checkout vengono visualizzati direttamente nella scheda di ChatGPT.

Per la scheda di checkout, payment_mode: "test" ti permette di testare il flusso end-to-end con carte di test senza muovere fondi reali.

Mantieni gli strumenti utili disponibili senza UI

Come per il resto del plugin, il catalogo e le capacità di ordinazione devono rimanere accessibili tramite strumenti utilizzabili senza un componente. L’interfaccia utente serve a presentare prodotti, prezzi, termini e scelte di pagamento prima della conferma. Non sostituisce strumenti dati robusti e non decide mai su un prezzo.

Punti chiave

  • Un plugin vende solo beni fisici: abbonamenti, contenuti digitali, crediti e upsell freemium sono vietati
  • Il pagamento esterno sul tuo dominio è il percorso raccomandato disponibile per tutti; openExternal apre il link
  • I metodi di pagamento salvati possono essere offerti, non raccolti
  • La scheda di checkout di ChatGPT (requestCheckout + complete_checkout) è in beta privata, riservata a specifici marketplace
  • Il server è la fonte della verità: calcoli dei prezzi lato server, operazioni idempotenti, importi in unità minori