Module ChatGPT Checkout PrestaShop (ACP): volledige gids
Installeer en configureer dfaiagent 2.0.0: Agentic Commerce Protocol-endpoint (ACP) voor de platforms voor AI-winkelagenten die u als verkoper hebben toegelaten.
dfaiagent opent in uw winkel een toegangspunt volgens het Agentic Commerce Protocol (ACP), het open protocol van OpenAI en Stripe. Een platform voor AI-winkelagenten dat u als verkoper heeft toegelaten, kan er een betaalsessie aanmaken, adres en levering kiezen en de aankoop afronden: er ontstaat een echte PrestaShop-bestelling met de prijzen, btw, voorraad en vervoerders van uw winkel.
Lees dit vóór elk project. De module schrijft u bij geen enkel platform in en garandeert geen verkoop: toegang hangt ervan af of elk platform uw winkel toelaat. Op 20 november 2026 vermeldt de pagina van OpenAI voor verkopers dat ChatGPT afstapt van een zelfstandige Instant Checkout-ervaring en vooral productfeeds opent, met een wachtlijst. We vonden geen officiële bron die zegt dat Claude of Perplexity ACP-endpoints van verkopers aanroepen. Controleer de voorwaarden van het gekozen platform voordat u het endpoint activeert.
Nieuw in 2.0.0
- Volledig herschreven. Versie 1.0.0 verwerkte geen enkel verzoek (fatale fout bij het laden van de klassen): updaten wordt sterk aanbevolen.
- ACP-protocol
2026-04-17(huidige versie) en2026-01-30, naast2025-09-29(formaat van 1.0.0). - Prijzen, btw en voorraad onder vergrendeling herberekend door PrestaShop; voor elke bestelling wordt een gastklant aangemaakt, nooit gekoppeld aan een bestaand account via het e-mailadres.
- Gecorrigeerde, idempotente betaling met gedeeld Stripe-token, met automatische terugbetaling als de bestelling mislukt.
- Volledige back-office: dashboard, installatieassistent, catalogus, regels, betaling, webhooks, sessies, logboek, diagnose, beveiliging en een blok op de bestelpagina.
- Compatibel met PrestaShop 1.7.8; interface in 8 talen (FR, EN, ES, DE, IT, PL, NL, PT).
Vereisten
- PrestaShop 1.7.8 tot 9.x. Getest op 1.7.8.11 (PHP 7.4), 8.2.1 (PHP 8.1) en 9.1.5 (PHP 8.5), ook in multistore.
- Winkel via HTTPS: zonder HTTPS antwoordt de API met een JSON-fout, nooit met een doorverwijzing.
- Vriendelijke URL’s ingeschakeld (Winkelparameters → Verkeer & SEO).
- Gepubliceerde juridische pagina’s: voorwaarden, privacy, retouren en contact. Ze worden vóór de betaling naar de agent gestuurd.
- Optioneel: een Stripe-account om het gedeelde token af te schrijven. Begin in testmodus.
Installatie
- Back-office → Modules → Een module uploaden, kies dan
dfaiagent-2.0.0.zip. - Het menu Bestellingen → AI-agenten (ACP) verschijnt. Het endpoint blijft uit zolang u het niet in de assistent activeert (antwoord 503).
Update vanaf 1.0.0
Upload de zip van 2.0.0 over 1.0.0 heen. Uw integratie blijft werken: de API-sleutel blijft geldig, maar alleen de hash wordt bewaard (de leesbare waarde wordt uit de database gewist); het ondertekeningsgeheim wordt versleuteld; het formaat van 1.0.0 blijft behouden (versie 2025-09-29 als de header ontbreekt, optionele Idempotency-Key, base64-handtekening). Sessies en bestellingen van 1.0.0 verschijnen in de module. De diagnose raadt daarna aan de sleutel te vernieuwen en de 1.0.0-compatibiliteit uit te schakelen.
Installatieassistent

De assistent begeleidt u in 7 stappen:
- Basis-URL: pad van de endpoints (standaard
acp, dushttps://uw-winkel.nl/acp) en controle van de vriendelijke URL’s. - API-sleutel: maak per platform een sleutel aan, met een label. Hij begint met
dfak_en wordt maar één keer getoond: geef hem meteen via een veilig kanaal door aan het platform. - Handtekening van verzoeken: genereer een geheim of plak het geheim van het platform. De handtekening is standaard verplicht.
- Betaling: gedeeld Stripe-token of bestellingen die „wachten op betaling”.
- Bestelwebhook (optioneel): HTTPS-URL van het platform en geheim.
- Verbindingstest: de ingebouwde testagent maakt een sessie aan, voegt een adres toe, berekent verzending en btw, leest de sessie en annuleert ze. Er wordt geen betaling of bestelling aangemaakt. Deze stap controleert ook of de publieke URL bereikbaar is.
- Activering: open het endpoint. U kunt het op elk moment uitschakelen.
Dashboard

Het dashboard toont alleen cijfers die in uw winkel gemeten zijn: bestellingen en omzet van agenten, geopende en afgeronde sessies, API-aanroepen en fouten, en de controlepunten die de diagnose meldt.
Getoonde catalogus

Kies de getoonde categorieën, sluit producten uit en stel de klantengroep voor de prijzen in (standaard de groep Gast, gebruikt voor zowel de offerte als de bestelling). Altijd uitgesloten: inactieve, onzichtbare of niet-bestelbare producten, producten zonder getoonde prijs, voorbehouden aan een andere groep of met verplichte personalisatie. Dezelfde regels gelden voor de feed en de betaling: een product dat niet in de feed staat, kan niet gekocht worden.
Landen, vervoerders en limieten

Beperk de leveringslanden en aangeboden vervoerders, geef de levertijd van elke vervoerder op en stel een maximumbedrag per bestelling en een maximumaantal bestellingen per uur in. Kies ook de CMS-pagina’s die als voorwaarden, privacy, retouren en contact naar de agent gaan.
Betaling

Met Stripe (gedeeld token)
Vul uw geheime Stripe-sleutel in (die wordt versleuteld). Bij het afronden schrijft de module het Shared Payment Token van de agent af, met een idempotentiesleutel die gekoppeld is aan de sessie, het token, het bedrag en de valuta:
- één afschrijving, ook als het verzoek herhaald wordt of in een time-out loopt;
- kaart geweigerd:
payment_declined, de sessie kan met een ander middel betaald worden; - 3-D Secure vereist: de betaalintentie wordt geannuleerd en de agent krijgt
requires_3ds; - totaal anders dan getoond aan de koper: er wordt niets afgeschreven (
price_change); - afschrijving gelukt, bestelling mislukt: automatische terugbetaling (of annulering van de autorisatie), gastklant verwijderd, waarschuwing in het logboek en, als u dat inschakelt, per e-mail.
Standaard directe inning. Uitgestelde inning is beschikbaar als optie, maar Stripe documenteert handmatige inning voor gedeelde tokens niet expliciet: overleg met Stripe voordat u ze inschakelt.
De module is getest tegen een gesimuleerde Stripe, niet tegen de echte Stripe. De veldnamen volgen de Stripe-documentatie over gedeelde tokens (API-versie „preview”). Valideer het volledige verloop in de testmodus van Stripe voordat u live gaat.
Zonder Stripe
De bestelling krijgt de status „Wacht op betaling (AI-agent)”, zonder factuur, en er wordt niets afgeschreven. U int daarna met uw eigen betaalmiddel.
Bestelwebhooks

De module stuurt order_create bij het aanmaken van de bestelling en daarna order_update bij elke statuswijziging of terugbetaling. De body bevat de volledige bestelling (regels, aanpassingen, terugbetaald totaal), zonder persoonsgegevens. Hij wordt ondertekend in de header Merchant-Signature: t=<tijdstempel>,v1=<HMAC-SHA256 hex van "t.body">.
Bij een fout volgen nieuwe pogingen na 1 min, 5 min, 30 min, 2 u, 6 u en 24 u, daarna „niet afgeleverd” met een waarschuwing. Alleen publieke HTTPS-URL’s worden aanvaard: privé- en lokale adressen, cloudmetadata, inloggegevens in de URL en gevoelige poorten worden geweigerd, en doorverwijzingen worden niet gevolgd.
Sessies en logboek

De sessielijst toont voor elke door een agent geopende sessie de status, de protocolversie, het getoonde totaal en de aangemaakte bestelling. Sessiegegevens worden versleuteld en 24 u na afloop gewist.

Het logboek registreert verzoeken en gebeurtenissen (betalingen, terugbetalingen, webhooks, waarschuwingen) met gemaskeerde persoonsgegevens. Sleutels staan er nooit in: alleen hun prefix wordt genoteerd.
Bestellingen geplaatst door een agent

De bestelling krijgt het privébericht „bestelling geplaatst door een AI-winkelagent” en een blok op haar pagina: Stripe-betaling, volledige of gedeeltelijke terugbetaling, annulering. Het aanmaken van een PrestaShop-creditnota start ook de Stripe-terugbetaling. Elke actie stuurt order_update naar het platform. De koper ontvangt de standaard-e-mails van PrestaShop.
Beveiliging

- API-sleutels van 256 bits, gehasht opgeslagen, in constante tijd vergeleken. Rotatie zonder onderbreking: de oude sleutel blijft naar keuze 0 u tot 7 dagen geldig. Onmiddellijke intrekking.
- Geheimen (handtekening, webhook, Stripe) versleuteld met AES-256-GCM.
- Verplichte handtekening, venster van 5 minuten, rotatie van het geheim met overgangsperiode.
- Limieten: verzoeken per sleutel, bescherming tegen brute force per IP (429 +
Retry-After), body van maximaal 64 KB en JSON van maximaal 32 niveaus. - Geen CORS, geen cookies, headers
nosniffenno-store. - Noodstop: schakelt het endpoint met één klik uit (503 voor agenten).
- Rechten van de back-office worden gerespecteerd (bekijken / bewerken); in multistore zijn instellingen, sleutels, sessies en cijfers per winkel gescheiden.
Diagnose

De diagnose controleert vriendelijke URL’s, HTTPS, sleutels (oude sleutels die nog actief zijn, 1.0.0-compatibiliteit), handtekening, betaling, mislukte webhooks, de getoonde catalogus en de juridische pagina’s.
API-referentie
Met het standaardpad acp:
POST /acp/checkout_sessions: een sessie aanmakenGET /acp/checkout_sessions/{id}: opvragenPOST /acp/checkout_sessions/{id}: bijwerken (artikelen, adres, leveringsoptie, koper)POST /acp/checkout_sessions/{id}/complete: afronden en de bestelling aanmakenPOST /acp/checkout_sessions/{id}/cancel: annulerenGET /acp/feed?limit=200&after=…: productfeed (gepagineerde JSON);/acp/feed.jsonlin JSON Lines;?format=legacy&page=1voor het formaat van 1.0.0
Headers
Authorization: Bearer UW_API_SLEUTEL(verplicht).API-Version: 2026-04-17(of2026-01-30,2025-09-29). Ontbrekend of onbekend: 400 met de lijstsupported_versions.Idempotency-Key: verplicht bij elke POST. Zelfde sleutel en zelfde body: herhaald antwoord (Idempotent-Replayed: true); andere body: 422idempotency_conflict(409 in 2025-09-29 en 2026-01-30); lopend verzoek: 409 metRetry-After.Signature: t=<unix-tijdstempel>,v1=<HMAC-SHA256 hex van "t.ruwe body">. De ACP-specificatie definieert geen handtekening voor checkoutverzoeken: de module past de handtekening toe die ze voor webhooks definieert.Accept-Language: taal van de berichten die naar de koper gaan.
Voorbeeld: een sessie aanmaken
curl -X POST "https://uw-winkel.nl/acp/checkout_sessions" -H "Authorization: Bearer UW_API_SLEUTEL" -H "API-Version: 2026-04-17" -H "Idempotency-Key: 6f1c2a90-create-1" -H "Signature: t=1795000000,v1=…" -H "Content-Type: application/json" -d '{"currency":"eur","line_items":[{"id":"42-7","quantity":1}],"fulfillment_details":{"name":"Alex de Vries","address":{"name":"Alex de Vries","line_one":"Kerkstraat 12","city":"Utrecht","postal_code":"3511 LX","country":"NL"}}}'
Het antwoord bevat de volledige sessie: line_items, fulfillment_options, totals (in de kleinste munteenheid), messages, links (juridische pagina’s) en status. De agent kiest daarna een optie met selected_fulfillment_options en roept complete aan met buyer en payment_data (gedeeld token in instrument.credential). Bij succes bevat het antwoord een order-object.
Artikel-ID’s
42 voor een eenvoudig product, 42-7 voor combinatie 7 van product 42. De feed gebruikt dezelfde codering in item_id.
Productfeed
De feed gebruikt de veldnamen van de productfeed van OpenAI (item_id, title, description, url, brand, image_url, availability, price in het formaat „12.50 EUR”, gtin, mpn, sale_price, juridische pagina’s…). Hij toont alleen producten die de agent ook kan kopen. Met de header ETag volgt een 304-antwoord als er niets veranderd is.
Bekende beperkingen
- Gedelegeerde 3-D Secure wordt niet ondersteund (de agent krijgt
requires_3ds). - Kortingscodes van de agent worden niet toegepast (waarschuwing
discount_code_invalid). - Gesplitste leveringen over meerdere vervoerders worden niet aangeboden.
- De tussenliggende ACP-versies 2025-12-12 en 2026-01-16 worden expliciet geweigerd.
Probleemoplossing
503 service_unavailable
Het endpoint is niet geactiveerd of de noodstop staat aan. Rond de assistent af of activeer het endpoint opnieuw onder Beveiliging.
404 of HTML-pagina
Schakel vriendelijke URL’s in, leeg de PrestaShop-cache en controleer of het pad overeenkomt met de URL die aan het platform is gegeven.
401
Sleutel ontbreekt, is fout, ingetrokken of verlopen na rotatie, of de handtekening is ongeldig (geheim, tijdstempel buiten het venster van 5 minuten, gewijzigde body). Het logboek vermeldt de reden.
400 missing_api_version
De agent stuurt de header API-Version niet mee. Gaat het om een 1.0.0-integratie, laat de 1.0.0-compatibiliteit dan aan tijdens de migratie.
Product geweigerd of niet in de feed
Controleer of het actief, zichtbaar, bestelbaar en op voorraad is, in een getoonde categorie staat, toegankelijk is voor de gekozen groep en geleverd kan worden in het land van de koper.
De verbindingstest meldt „niet bereikbaar”
De server kan zijn eigen publieke URL niet bereiken (firewall, interne DNS, lokale omgeving). De tests van de ingebouwde agent blijven geldig; controleer de toegang van buitenaf.