ACP / Instant Checkout: lo standard e la sua implementazione in ChatGPT

1. Perché serve ACP e perché non è «un altro REST API»

Se la guardi in modo cinico, ACP sembra un insieme di normali endpoint HTTP e strutture JSON: un certo /checkout_sessions, alcuni webhook, dei token. È facile pensare: «Ok, è un’altra API personalizzata dell’ennesima piattaforma». Ma l’idea di ACP è più profonda.

ACP è concepito come un protocollo aperto di interazione tra tre attori: la piattaforma di IA (ad esempio, ChatGPT), il tuo backend commerce e il fornitore di servizi di pagamento. Il suo obiettivo è standardizzare come descrivere prodotti e prezzi, come l’IA dichiara l’intenzione dell’utente di acquistare, come si crea una sessione di checkout, come si esegue il pagamento e come tutti gli attori apprendono lo stato finale.

L’idea chiave: lo stesso backend del merchant che implementa ACP può potenzialmente funzionare non solo con ChatGPT, ma anche con altre piattaforme LLM che adotteranno questo standard. Cioè non scrivi una «API speciale per ChatGPT», realizzi un protocollo di integrazione commerce di nuova generazione.

Instant Checkout in ChatGPT è la prima grande implementazione dello standard ACP. ChatGPT rispetta questo protocollo, chiamando i tuoi endpoint ACP e mostrando all’utente una bella interfaccia, ma le regole del gioco sono descritte nelle specifiche ACP e non sono nascoste dalla «magia di GPT» dentro una scatola nera.

2. I tre pilastri di ACP: Product Feed, Agentic Checkout, Delegated Payment

ACP ha tre specifiche principali, che citeremo costantemente:

Abbiamo già esaminato il Product Feed nelle lezioni precedenti. Ora ci interessano gli ultimi due blocchi: Agentic Checkout e Delegated Payment.

È importante distinguere tre livelli:

1. Standard (SPEC). I documenti ufficiali descrivono quali campi ed endpoint devono esistere, quali stati sono legali e quali garanzie ti impegni a fornire.
2. Pattern architetturale (ARCH). Per esempio, la scelta di memorizzare SKU e ordini in tabelle separate, creare un servizio wrapper intorno ad ACP o usare una coda per i webhook. Buone pratiche, ma non parte dello standard.
3. Implementazione concreta (esempio GiftGenius). Questo è il nostro progetto didattico: la struttura delle nostre tabelle, i nomi esatti dei tipi in TypeScript, come registriamo i log degli ordini ecc. Tutto questo è un esempio, non un documento normativo.

Sottolineeremo costantemente dove finisce la SPEC e dove inizia la tua architettura — per evitare che capiti «ho visto nella lezione il campo persona_tags e ho deciso che fa parte della specifica ufficiale».

3. Checkout session dall'interno: struttura e stati

L’oggetto centrale della Agentic Checkout Spec è la checkout_session nel tuo backend. Logicamente è lo stato dell’acquisto: quali prodotti, per quale importo, con quali opzioni di consegna e in quale stato si trova il tentativo di pagamento.

La specifica descrive i campi obbligatori di checkout_session più o meno così (formulazioni semplificate e parzialmente ridotte rispetto all’originale):

• id — identificatore di sessione (stringa) che generi e restituisci tu. ChatGPT lo userà in tutte le chiamate successive.
• buyer — informazioni sull’acquirente: nome, email, telefono, a volte indirizzo. Nella specifica reale questo oggetto è strutturato, affinché PSP e i tuoi sistemi possano utilizzarlo in modo affidabile.
• status — enum stringa che riflette lo stato attuale dell’acquisto. Stati base:
  • not_ready_for_payment — non si può ancora pagare (ad esempio, non è stata scelta la modalità di consegna o le tasse non sono state ricalcolate).
  • ready_for_payment — tutto è pronto, si può richiedere il token di pagamento ed effettuare l’addebito.
  • completed — il pagamento è andato a buon fine, l’ordine è stato creato.
  • canceled — acquisto annullato (su iniziativa dell’utente o per errore).
• currency — codice valuta in formato ISO 4217 in minuscolo ("usd", "eur" ecc.).
• line_items — elenco delle righe del carrello, ciascuna con il proprio SKU, quantità e costo calcolato.
• fulfillment_address — indirizzo di consegna (se pertinente).
• fulfillment_options e fulfillment_option_id — opzioni di consegna (o esecuzione) disponibili e l’opzione selezionata.
• totals — somme aggregate: costo prodotti, tasse, consegna, totale finale.
• order — oggetto che descrive l’ordine che verrà creato dopo il completamento positivo della sessione.
• messages — elenco di messaggi utente che ChatGPT può mostrare all’acquirente: ad esempio avvisi o errori.
• links — elenco di link, per esempio alla policy di reso, Privacy Policy e Terms of Service.

Non è necessario implementare nel demo tutti i campi, ma è importante capire l’idea: checkout_session è «la storia e lo stato attuale di un tentativo di acquisto», e ChatGPT si aspetta di trovarvi tutto ciò che serve per un UX corretto.

Per semplificare, introduciamo nel nostro codice didattico un tipo semplificato:

// Modello semplificato di checkout_session per GiftGenius (non la SPEC completa)
type GGCheckoutStatus = 'not_ready_for_payment' | 'ready_for_payment' | 'completed' | 'canceled';

type GGLineItem = { skuId: string; quantity: number; total: number };

type GGCheckoutSession = {
  id: string;
  status: GGCheckoutStatus;
  currency: 'usd';
  lineItems: GGLineItem[];
  grandTotal: number;
};

Questo modello è volutamente più semplice di quello ufficiale, ma è perfetto per la pratica: imparare a tenere a mente stati e transizioni senza affogare in cento campi.

4. Ciclo di vita di checkout_session

La specifica Agentic Checkout descrive diverse operazioni su checkout_session. In forma semplificata il ciclo di vita appare così:

1. Creazione della sessione: POST /checkout_sessions.
2. Aggiornamento della sessione: POST /checkout_sessions/{id}.
3. Completamento della sessione (complete): POST /checkout_sessions/{id}/complete.
4. (A volte) Annullamento: endpoint cancel separato o passaggio a canceled tramite aggiornamento.

Guardando dagli stati, si può disegnare questo diagramma:

stateDiagram-v2
    [*] --> not_ready_for_payment
    not_ready_for_payment --> ready_for_payment: calcolo di spedizione/tasse
scelta delle opzioni
    ready_for_payment --> completed: POST /complete riuscito
    ready_for_payment --> canceled: annullamento da parte dell’utente o errore
    not_ready_for_payment --> canceled: errore, dati incompatibili

La creazione della checkout_session di solito la avvia nello stato not_ready_for_payment o direttamente ready_for_payment, se tutto il necessario per il pagamento è già noto (ad esempio, bene digitale senza consegna e tasse). Gli aggiornamenti si usano per aggiungere dati (indirizzo, codici promozionali, opzione di consegna) e ricalcolare gli importi. Il completamento è il momento in cui entra in gioco il Delegated Payment e il denaro viene effettivamente addebitato.

Qui è importante capire la suddivisione dei ruoli:

• ChatGPT avvia la creazione, gli aggiornamenti e il completamento della sessione, in base al dialogo con l’utente.
• Il tuo backend (del merchant) è responsabile della logica di business corretta: verifica degli SKU, disponibilità, calcolo dei prezzi e delle tasse, cambio degli stati, creazione degli ordini.
• Il PSP (Stripe e altri) effettua il pagamento reale e rilascia lo Shared Payment Token, che il merchant utilizza per addebitare i fondi.

Più avanti sovrapporremo a questo state diagram le richieste HTTP concrete e minuscoli esempi di codice.

5. Creazione di checkout_session: cosa si aspetta da noi ChatGPT

Quando ChatGPT (o un agente) decide che l’utente vuole davvero acquistare qualcosa, forma i line items in base al Product Feed: elenco degli SKU, quantità, valuta prevista e, possibilmente, preferenze aggiuntive di consegna. Poi chiama il tuo endpoint POST /checkout_sessions.

Dal lato del merchant in questo momento bisogna:

1. Convalidare i dati in ingresso: assicurarsi che tutti gli SKU esistano, siano vendibili e non violino policy (ad esempio, niente alcol per minorenni).
2. Calcolare prezzi e tasse in base alle tue regole.
3. Preparare le opzioni di consegna (fulfillment options), se il bene è fisico.
4. Restituire una checkout_session corretta con stato e importi.

Un handler semplicissimo in Express per GiftGenius può apparire così:

// Pseudocodice: creazione di una checkout_session semplificata
app.post('/checkout_sessions', async (req, res) => {
  const items = req.body.lineItems as GGLineItem[];  // skuId + quantity
  const pricedItems = await priceItems(items);       // calcoliamo il total per ogni SKU
  const grandTotal = sum(pricedItems.map(i => i.total));

  const session: GGCheckoutSession = {
    id: generateId(),
    status: 'ready_for_payment', // per i regali digitali si può essere subito pronti al pagamento
    currency: 'usd',
    lineItems: pricedItems,
    grandTotal,
  };

  res.status(201).json(session);
});

Qui facciamo alcune cose:

• Non ci fidiamo dei prezzi in ingresso dal client (ChatGPT) e li ricalcoliamo con i nostri dati — è fondamentale per la sicurezza del commerce.
• Generiamo il nostro id di sessione (ad esempio, prefisso gg_chk_...).
• Restituiamo lo stato ready_for_payment se non abbiamo passaggi aggiuntivi (niente consegna, tasse automatiche, modello semplice).

In un backend compatibile ACP reale restituirai inoltre messages, links e l’oggetto composto totals, nonché compilerai order (almeno in bozza), come descritto nella specifica.

6. Aggiornamento di checkout_session e idempotenza

Dopo la creazione della sessione, ChatGPT può chiedere all’utente dettagli aggiuntivi: indirizzo di consegna, applicazione di un coupon, cambio dell’opzione di esecuzione. Quando questi dati arrivano, la piattaforma effettua la chiamata POST /checkout_sessions/{id} per farti aggiornare i calcoli.

Dal punto di vista del codice è molto simile alla creazione, ma invece di generare una nuova sessione tu:

• trovi quella esistente tramite id;
• applichi le modifiche (ad esempio, cambi fulfillment_option_id o aggiungi lo sconto);
• ricalcoli gli importi;
• restituisci la checkout_session aggiornata.

È importante che la specifica ammetta chiamate ripetute (per problemi di rete o retry da parte di ChatGPT). Perciò, come nei moduli precedenti in cui abbiamo parlato di idempotenza di strumenti e webhook, qui è consigliato usare Idempotency-Key nelle intestazioni della richiesta e gestire accuratamente i retry.

Un handler ipotetico di aggiornamento potrebbe essere così:

app.post('/checkout_sessions/:id', async (req, res) => {
  const id = req.params.id;
  const key = req.header('Idempotency-Key'); // stesso key => stesso effetto
  const existing = await loadSessionWithIdempotency(id, key, req.body);

  // applyUpdates all'interno può ricalcolare prezzi, consegna ecc.
  const updated = await applyUpdates(existing, req.body);
  await saveSession(updated, key);

  res.json(updated);
});

Qui non seguiamo rigidamente la struttura SPEC, ma mostriamo l’idea: in ingresso — modifiche e chiave idempotente, in uscita — stato consistente di checkout_session. Se ti arriva la stessa richiesta con la stessa chiave, devi restituire lo stesso risultato, senza creare ordini extra o duplicati nei log.

7. Completamento di checkout_session e Delegated Payment: come funziona lo Shared Payment Token

Il momento più interessante e delicato — il completamento della checkout_session, quando il denaro viene davvero addebitato. Qui entra in gioco la seconda specifica: Delegated Payment.

L’idea di Delegated Payment

L’utente inserisce o seleziona i dati di pagamento nell’interfaccia di ChatGPT (carta, wallet, metodo salvato). La piattaforma non ti invia questi dati direttamente — invece richiede al PSP (ad esempio, Stripe) un token speciale, Shared Payment Token (SPT), che:

• è univocamente associato al merchant e alla specifica sessione;
• è limitato per importo e durata di vita;
• non ti rivela il numero reale della carta.

Ne risulta questo quadro:

Questo design permette al merchant di evitare di conservare i dati di pagamento e di concentrarsi sulla logica dell’ordine, lasciando le questioni di compliance al PSP e alla piattaforma.

Insight

Il senso dello Shared Payment Token è nascondere al tuo backend i dati della carta, ma far sì che sia tu a eseguire il pagamento. Ma si può guardarlo anche da un’altra prospettiva.

Avrai sicuramente visto situazioni in cui un negozio o un hotel prima blocca (pre‑autorizza) i fondi sulla tua carta e poi, dopo un po’, li addebita. Ecco: considera lo Shared Payment Token come un token di hold (pre‑autorizzazione). ChatGPT ha pre‑autorizzato i fondi sul conto dell’utente, ma non li ha addebitati. Ti ha passato questo token di hold e ora puoi inoltrarlo a Stripe e addebitare l’importo.

Ci sono due sfumature importanti:

• gli importi di hold e addebito non devono differire in modo significativo, e idealmente devono coincidere;
• puoi vendere tramite ChatGPT il primo mese di abbonamento a 1 $, e poi addebitare ogni mese 49,99 $

Richiesta POST /checkout_sessions/{id}/complete

Quando l’utente preme il pulsante di conferma del pagamento in Instant Checkout, ChatGPT:

1. Richiede l’SPT al PSP (ad esempio tramite Stripe ACP API).
2. Invia questo token al tuo backend tramite POST /checkout_sessions/{id}/complete insieme ai dati dell’acquirente.

La specifica descrive il corpo della richiesta più o meno così (di seguito un esempio adattato e ridotto dalla documentazione ufficiale):

POST /checkout_sessions/checkout_session_123/complete

{
  "buyer": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "johnsmith@mail.com"
  },
  "payment_data": {
    "token": "spt_123",
    "provider": "stripe"
  }
}

Il tuo backend deve quindi:

1. Trovare la checkout_session con id checkout_session_123.
2. Verificare che lo stato consenta il completamento (di solito ready_for_payment).
3. Creare il pagamento presso il PSP usando il token spt_123 (il metodo dipende dal PSP, nel caso di Stripe — un certo endpoint e tipo di payment method).
4. Attendere la conferma dell’operazione di pagamento.
5. Aggiornare la checkout_session a completed, creare e salvare l’ordine, compilare il campo order nella struttura della sessione.
6. Restituire la checkout_session aggiornata nella risposta.

In TypeScript molto semplificato, potrebbe apparire così:

app.post('/checkout_sessions/:id/complete', async (req, res) => {
  const { id } = req.params;
  const { buyer, payment_data } = req.body;
  const session = await loadSession(id);

  await chargeWithSharedToken(payment_data.token, session.grandTotal);
  const completed = await markSessionCompleted(session, buyer);

  res.json(completed);
});

Nel mondo reale tra queste righe si nascondono la gestione degli errori, i tentativi di retry, il logging e l’integrazione con il tuo modello di ordini.

Se qualcosa va storto (ad esempio, pagamento rifiutato), devi restituire la checkout_session con stato not_ready_for_payment o canceled e compilare messages in modo che ChatGPT possa spiegare correttamente all’utente cosa è successo.

8. Instant Checkout in ChatGPT: come si compone in un unico flusso

Ora mettiamo insieme questi pezzi in uno scenario completo «dall’intenzione al pagamento» in ChatGPT. Puoi vedere la lezione come il «decodificare» ciò che si nasconde dietro un solo pulsante «Acquista» nel widget.

Scenario semplificato:

1. L’utente scrive: «Trova un regalo digitale per un amico fino a 50 $ e concludi subito l’acquisto».
2. L’agente (o l’app stessa di ChatGPT) usa il Product Feed per trovare SKU adatti entro il budget.
3. ChatGPT mostra in chat alcune card di regali (tramite il tuo widget GiftGenius) e propone di scegliere.
4. Dopo la scelta, ChatGPT forma i line items e chiama POST /checkout_sessions sul tuo backend ACP, ottenendo una checkout_session con importi e stato.
5. Nell’UI di Instant Checkout l’utente vede l’importo finale, il nome del prodotto, la policy di reso e il pulsante di conferma.
6. Alla conferma, ChatGPT ottiene lo Shared Payment Token dal PSP e chiama POST /checkout_sessions/{id}/complete, come discusso sopra.
7. Il tuo backend esegue il pagamento, crea l’ordine, restituisce la checkout_session con stato completed.
8. ChatGPT mostra all’utente la conferma, e il tuo backend (tramite webhook secondo la Agentic Checkout Spec) può inviare un evento a OpenAI perché la piattaforma conosca l’esito dell’ordine.

Come sequence diagram appare così:

sequenceDiagram
    actor U as Utente
    participant GPT as ChatGPT
    participant GG as GiftGenius ACP backend
    participant PSP as Stripe (PSP)

    U->>GPT: Voglio un regalo fino a 50 $ e acquistarlo qui
    GPT->>GG: POST /checkout_sessions (line_items)
    GG-->>GPT: checkout_session (ready_for_payment)
    GPT->>U: Mostra Instant Checkout (prodotto, prezzo, ToS)
    U->>GPT: Clicca «Conferma pagamento»
    GPT->>PSP: Richiede SPT per importo e merchant
    PSP-->>GPT: Shared Payment Token (spt_xxx)
    GPT->>GG: POST /checkout_sessions/{id}/complete (token + buyer)
    GG->>PSP: Pagamento con SPT
    PSP-->>GG: Pagamento riuscito
    GG-->>GPT: checkout_session (completed + order)
    GPT-->>U: Mostra conferma d’acquisto

In questo scenario non compare mai una chiamata «arbitraria» al tuo database o a strani endpoint interni. Tutto rientra nel contratto ACP rigorosamente descritto, dove ogni attore conosce il proprio ruolo.

9. Mini‑pratica: backend ACP semplificato per GiftGenius

Per evitare che questa lezione resti teoria pura, è importante «visualizzare» mentalmente l’implementazione dello strato ACP per il nostro progetto didattico.

Immagina che GiftGenius abbia già:

• Una base di SKU e prezzi, su cui formiamo il Product Feed (modellata nelle lezioni precedenti).
• Un modello semplice di ordini: tabella orders con campi id, userId, skuId, amount, currency, status, createdAt.
• L’interfaccia ChatGPT App e lo strato MCP, che sa raccomandare i regali (costruito nei moduli precedenti del corso).

Ora il tuo compito — aggiungere sopra a questo un altro piccolo servizio gg-acp:

• Endpoint POST /checkout_sessions:
  • Accetta elenco di SKU e quantità.
  • Ricalcola gli importi in base al tuo DB.
  • Crea un ordine in bozza (ad esempio con stato pending) e una checkout_session con stato ready_for_payment.
  • Restituisce la checkout_session.
• Endpoint POST /checkout_sessions/{id}:
  • Trova la sessione e l’ordine.
  • Applica le modifiche (ad esempio, supporto di un codice promo che riduce il totale).
  • Restituisce la checkout_session aggiornata.
• Endpoint POST /checkout_sessions/{id}/complete:
  • Riceve SPT, importo e dati dell’acquirente.
  • Nella versione demo può semplicemente marcare l’ordine come «pagato» senza chiamata reale al PSP (oppure puoi simulare Stripe).
  • Aggiorna la checkout_session allo stato completed e la collega a order_id.

Tutto questo servizio si può implementare in una piccola applicazione Node/Express o in endpoint del Next.js App Router. L’importante è rispettare il contratto per formato e stati, anche se simuli il pagamento.

Un modello d’ordine in TypeScript potrebbe apparire così:

// Modello d'ordine semplificato di GiftGenius
type GGOrderStatus = 'pending' | 'paid' | 'canceled';

type GGOrder = {
  id: string;
  userId: string;
  skuId: string;
  amount: number;
  currency: 'usd';
  status: GGOrderStatus;
};

In produzione, sopra a questo compariranno integrazioni con il tuo Auth/Identity (per sapere quale utente è il chat), webhook verso OpenAI e scenari di reso più complessi. Ma come passo didattico in questa lezione è sufficiente imparare a percorrere con sicurezza il ciclo: creare una sessione → aggiornare → completare, senza perdere denaro né buon senso.

10. Errori tipici nella progettazione di ACP / Instant Checkout

Errore №1: confusione di ruoli («ChatGPT è il mio negozio»).
A volte gli sviluppatori assegnano mentalmente a ChatGPT il ruolo di «sistema centrale di record» e tentano di memorizzare lo stato di business dell’ordine lato piattaforma: «visto che c’è checkout_session, allora leggerò la storia ordini da OpenAI». È una strada senza uscita. checkout_session è un oggetto di protocollo, non la fonte di verità sugli ordini. La fonte di verità è il tuo backend commerce: è lì che devono vivere ordini, stati, resi e report. ChatGPT in questo schema è solo un «frontend in chat» affidabile.

Errore №2: fidarsi dei prezzi in ingresso da ChatGPT.
È facile pensare: «l’agente ha già scelto gli SKU e persino calcolato il totale, accettiamo quel totale e addebitiamo». Non si può fare. L’input da ChatGPT (line items, prezzi previsti) va percepito come una proposta, non come un ordine. Il tuo backend deve verificare in autonomia SKU, prezzi, disponibilità, applicabilità degli sconti ecc., confrontandoli con il Product Feed e il tuo DB. Altrimenti ti troverai con un allegro set di bug: «l’utente ha comprato a 0,01 $ perché il modello ha deciso di arrotondare».

Errore №3: ignorare gli stati e la state machine.
Nei primi prototipi spesso si fa un’implementazione «bucherellata»: lo stato della sessione è sempre completed, o semplicemente ok, e qualsiasi divergenza con lo stato reale del pagamento viene nascosta all’interno. Alla fine, ChatGPT non può mostrare correttamente all’utente cosa stia accadendo: pagamento in corso, già completato o annullato. Molto più affidabile è implementare onestamente la state machine not_ready_for_payment → ready_for_payment → completed/canceled e restituire lo stato reale dal backend, senza inventare campi ad‑hoc.

Errore №4: usare lo Shared Payment Token come «carta riutilizzabile».
Per concezione, l’SPT è un token monouso o comunque strettamente limitato: è legato a una specifica operazione, a un importo e a un merchant. Provare a metterlo in cache «per ogni evenienza» o usarlo di nuovo per un altro acquisto è una cattiva idea. Nel migliore dei casi il PSP rifiuterà il secondo tentativo; nel peggiore — confonderai la contabilità dei pagamenti e gli ordini. Per ogni checkout_session.complete deve esserci un token fresco; se il pagamento non è riuscito — va richiesto un nuovo token.

Errore №5: assenza di idempotenza in /checkout_sessions e nei webhook.
Nella rete reale le richieste possono essere duplicate: ChatGPT può ripetere POST /checkout_sessions dopo un timeout, il PSP può inviare di nuovo un webhook dopo un errore temporaneo. Se la tua implementazione ogni volta crea un nuovo ordine e una nuova riga in database, otterrai rapidamente caos: addebiti doppi, ordini duplicati e strani scostamenti tra sistemi. L’uso di Idempotency-Key, il controllo dei repeat e la memorizzazione dei risultati delle chiamate precedenti non è «un’ottimizzazione opzionale», ma un elemento necessario di una integrazione ACP affidabile.

Errore №6: dimenticare il legame con il Product Feed.
A volte lo strato ACP viene progettato «nel vuoto»: SKU e prezzi vengono presi da tabelle interne che non coincidono con ciò che finisce nel Product Feed. Di conseguenza, ChatGPT mostra una cosa (dal feed) e nel checkout tramite ACP ne scorre un’altra. Per evitare sorprese, è importante che il tuo modello di SKU e prezzi sia unico: feed, backend ACP e database interno devono guardare alla stessa fonte di verità, anche se sopra ci sono proiezioni e cache diverse.