Stripe ACP suomalaiselle verkkokaupalle: käyttöönotto
Stripe ACP otetaan käyttöön neljässä vaiheessa: varmistetaan Stripe-yhteys, avataan tuotteet agentille, toteutetaan ACP-ostoendpoint ja testataan koko maksuvirtaus testitilassa. ACP (Agentic Commerce Protocol) on OpenAI:n ja Stripen yhteinen malli jossa tekoälyagentti, kuten ChatGPT, tekee oston kaupan olemassa olevan Stripe-yhteyden läpi ilman että asiakas siirtyy erilliselle maksusivulle. Jos Stripe on jo maksunvälittäjäsi, agenttimaksu avautuu ilman uutta maksuintegraatiota.
Tämä ohje näyttää oikeat vaiheet, endpointit ja havainnollistavat payloadit suomalaiselle verkkokaupalle. Agenttimaksu rakentuu löydettävyyden ja rakenteisen tuotedatan päälle, ei niiden tilalle, joten oleta että kaupalla on jo MCP-palvelin (Model Context Protocol) tai vastaava tuotehaku ennen kuin avaat maksun.
Vaihe 1: Varmista Stripe-yhteys ja tili
Ensimmäinen vaihe on varmistaa että kaupalla on toimiva Stripe-tili ja API-avaimet, koska ACP nojaa Stripen maksuvirtaukseen. Tarkista Stripe Dashboardista että tili on aktiivinen, että sinulla on sekä testitilan (sk_test_...) että tuotannon avaimet, ja että maksutavat jotka haluat agentille ovat käytössä. Jos Stripe ei ole vielä maksunvälittäjänäsi, ACP:n käyttöönotto vaatii ensin Stripe-integraation, ja se on oma projektinsa.
Pidä testitilan avain erillään tuotannosta koko käyttöönoton ajan. Kaikki tämän ohjeen testaus tehdään testiavaimilla, ja tuotantoavain otetaan käyttöön vasta kun virtaus on todettu toimivaksi.
Vaihe 2: Avaa tuotteet agentille rakenteisesti
Toinen vaihe on varmistaa että agentti saa tuotteet, hinnat ja saldot rakenteisesti, koska maksu voi koskea vain tuotetta jonka agentti on ensin löytänyt oikein. Tämä tapahtuu MCP-palvelimen tai vastaavan tuotehaun kautta. Agentti hakee tuotteen, saa sen tunnisteen ja hinnan, ja vasta sitten kokoaa tilauksen.
Havainnollistava esimerkki tuotehaun vastauksesta, josta agentti poimii ostettavan nimikkeen:
{
"tuotteet": [
{
"sku": "villasukat-harmaa",
"nimi": "Villasukat, harmaa",
"hinta_eur": 24.90,
"saatavuus": "varastossa"
}
]
}Tärkeä yksityiskohta on että hinta ja saldo ovat oikeat samalla hetkellä kun agentti tekee oston. Jos tuotehaku palauttaa vanhan hinnan, agentti tekee tilauksen väärällä summalla. Kytke tuotehaku kaupan todelliseen tuotetietoon, ei erilliseen kopioon.
Vaihe 3: Toteuta ACP-ostoendpoint
Kolmas vaihe on toteuttaa endpoint jonka agentti kutsuu tehdäkseen oston, ja joka luo Stripe-maksun kaupan puolella. ACP-virtauksessa agentti kokoaa tilauksen ja välittää maksun Stripen kautta, ja kaupan endpoint ottaa tilauksen vastaan, tarkistaa sen ja luo Stripe-veloituksen. Endpoint vastaa yleensä POST-kutsuun.
Havainnollistava esimerkki agentin lähettämästä tilauspyynnöstä:
{
"protocol": "acp",
"order": {
"items": [{ "sku": "villasukat-harmaa", "quantity": 1 }],
"currency": "EUR"
},
"payment": { "provider": "stripe", "token": "<agentin_maksutoken>" }
}Kaupan endpoint tarkistaa tilauksen ja luo Stripe-veloituksen. Pelkistetty esimerkki palvelinlogiikasta Node-ympäristössä:
// POST /api/acp/order
app.post("/api/acp/order", async (req, res) => {
const { order, payment } = req.body;
// 1. Tarkista tuotteet ja laske summa kaupan omasta datasta,
// älä luota agentin lähettämään hintaan.
const summaEur = await laskeSummaKaupanDatasta(order.items);
// 2. Luo Stripe-maksu agentin toimittamalla tokenilla.
const maksu = await stripe.paymentIntents.create({
amount: Math.round(summaEur * 100), // sentteinä
currency: "eur",
payment_method: payment.token,
confirm: true
});
// 3. Vahvista tilaus vasta kun maksu on onnistunut.
if (maksu.status === "succeeded") {
const tilaus = await tallennaTilaus(order, maksu.id);
return res.json({ status: "confirmed", order_id: tilaus.id });
}
return res.status(402).json({ status: "payment_failed" });
});Kaksi kohtaa ratkaisee turvallisuuden. Ensinnäkin laske summa aina kaupan omasta datasta, älä agentin lähettämästä hinnasta, jotta väärä tai muokattu hinta ei mene läpi. Toiseksi vahvista tilaus vasta kun Stripe palauttaa onnistuneen maksun, ei aiemmin.
Vaihe 4: Testaa maksuvirtaus testitilassa
Neljäs vaihe on ajaa koko ostopolku läpi Stripen testitilassa ennen kuin avaat maksun oikeille agenteille. Käytä testiavaimia ja Stripen testikortteja, ja aja virtaus kuten agentti sen ajaisi: tuotehaku, tilauspyyntö ostoendpointille, Stripe-veloitus ja tilausvahvistus. Tarkista että väärä summa tai epäonnistunut maksu tuottaa oikean virhevastauksen, ei vahvistettua tilausta.
Voit testata ostoendpointin elossaolon suoraan komentoriviltä:
curl -X POST https://kauppasi.fi/api/acp/order \
-H "Content-Type: application/json" \
-d '{
"protocol": "acp",
"order": { "items": [{ "sku": "villasukat-harmaa", "quantity": 1 }], "currency": "EUR" },
"payment": { "provider": "stripe", "token": "tok_visa" }
}'Testitilassa vastauksen pitäisi olla joko vahvistettu tilaus tai selkeä virhe. Vasta kun jokainen haara toimii oikein, vaihda tuotantoavaimeen ja avaa maksu agenteille. Väärin konfiguroitu maksuvirtaus on liiketoimintariski, ei kokeilu.
Vaatiiko Stripe ACP jatkuvaa ylläpitoa?
Stripe ACP vaatii jatkuvaa ylläpitoa, koska protokolla, Stripen rajapinta ja kaupan tuotedata muuttuvat. ACP:n spec elää, Stripe päivittää maksurajapintojaan, ja tuotteiden hinnat ja saldot muuttuvat päivittäin. Ostoendpoint pitää päivittää näiden mukana, ja testivirtaus kannattaa ajaa uudelleen aina kun jotain muuttuu. Kertaasennus ei riitä, koska agenttikaupan standardit ovat vasta muotoutumassa.
Onko kauppasi valmis Stripe ACP:hen?
Agentic Commerce -valmiusskanneri katsoo maksukäsittelysi ja rakenteisen tuotedatasi ja kertoo mitä ACP-käyttöönotto kaupaltasi vaatii.