# Tekninen dokumentaatio Tältä sivulta löydät työkalujen kuvaukset ja kirjautumisen tekniset tiedot. --- ## Työkalut Paytrail MCP kutsuu näitä työkaluja automaattisesti pyyntöjesi perusteella. Sinun ei tarvitse tietää niiden nimiä — voit esittää pyyntöjä assistentillesi selkokielisesti. ### list_merchants **Kuvaus:** Listaa kaikki kauppiaat, joihin käyttäjällä on oikeudet. Tämä työkalu on yleensä ensimmäinen kutsu — sen palauttama `id`-arvo tarvitaan muiden työkalujen `merchantId`-kentässä. **Syötteet:** Ei syötteitä. **Esimerkkivastaus:** ```json [ { "id": 375917, "name": "Testkauppa Oy" }, { "id": 695861, "name": "Demomyymälä" } ] ``` | Kenttä | Tyyppi | Kuvaus | | ------ | ------ | -------------------------------------------------------------------------------- | | `id` | number | Kauppiaan sisäinen tunniste. Käytä tätä muiden työkalujen `merchantId`-kentässä. | | `name` | string | Kauppiaan nimi. | ### create_payment **Kuvaus:** Luo uuden maksupyynnön valitulle kauppiaalle. Palauttaa maksutapahtuman tunnisteen (`transactionId`) ja linkin maksusivulle. **Syötteet:** | Kenttä | Pakollinen | Tyyppi | Kuvaus | | -------------------- | ---------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `merchantId` | Kyllä | number | Kauppiaan tunniste. Saadaan `list_merchants`-työkalulta. | | `amount` | Kyllä | integer | Maksun summa **senteissä**. Esimerkiksi 1999 tarkoittaa 19,99 €. | | `reference` | Kyllä | string | Kauppiaan oma viitenumero maksulle. | | `customerEmail` | Kyllä | string | Asiakkaan sähköpostiosoite. | | `currency` | Ei | string | Valuuttakoodi ISO 4217 -muodossa. Oletusarvo: `"EUR"`. | | `description` | Ei | string | Vapaamuotoinen kuvaus maksusta (näkyy tiliotteella ja kirjanpidossa). | | `vatPercentage` | Ei | number (0–100) | Maksuun sovellettava ALV-prosentti. Oletusarvo: `25.5` (Suomen yleinen ALV-kanta). | | `sendPaymentLink` | Ei | boolean | Jos `true`, maksulinkki lähetetään sähköpostilla `customer.email`-osoitteeseen maksun luonnin jälkeen. Vaatii `customer.email`-kentän. | | `paymentLinkComment` | Ei | string (≤200) | Vapaamuotoinen kommentti, joka näytetään maksulinkin sähköpostiviestissä. Käytetään vain kun `sendPaymentLink` on `true`. Linkit (URL-osoitteet tai verkkotunnukset) hylätään. | **Esimerkkivastaus:** ```json { "transactionId": "4b300af6-9a22-11e8-9184-abb6de7fd2d0", "href": "https://pay.paytrail.com/pay/4b300af6-9a22-11e8-9184-abb6de7fd2d0" } ``` | Kenttä | Tyyppi | Kuvaus | | --------------- | ------ | ------------------------------------------------------------------------------------------- | | `transactionId` | string | Maksutapahtuman yksilöivä tunniste. Tallenna tämä — tarvitset sitä `get_payment`-kutsuissa. | | `href` | string | URL-osoite, johon asiakas ohjataan suorittamaan maksu. | ### get_payment **Kuvaus:** Hakee olemassa olevan maksutapahtuman tilan ja perustiedot tunnisteen perusteella. **Syötteet:** | Kenttä | Pakollinen | Tyyppi | Kuvaus | | --------------- | ---------- | ------ | --------------------------------------------------------------- | | `transactionId` | Kyllä | string | Maksutapahtuman tunniste. Palautettu `create_payment`-kutsusta. | | `merchantId` | Kyllä | number | Maksun omistavan kauppiaan tunniste. | **Esimerkkivastaus:** ```json { "transactionId": "4b300af6-9a22-11e8-9184-abb6de7fd2d0", "status": "ok", "amount": 1999, "currency": "EUR", "stamp": "29858472953", "reference": "9187445", "createdAt": "2018-08-08T10:10:10+03:00", "href": "https://pay.paytrail.com/pay/4b300af6-9a22-11e8-9184-abb6de7fd2d0", "provider": "nordea" } ``` | Kenttä | Tyyppi | Kuvaus | | --------------- | ------- | ----------------------------------------------------------------------------------------------- | | `transactionId` | string | Maksutapahtuman tunniste. | | `status` | string | Maksun tila (katso alla). | | `amount` | integer | Summa senteissä. | | `currency` | string | Valuuttakoodi. | | `stamp` | string | Palvelimen luoma yksilöivä leima. Paytrail käyttää tätä päällekkäisten maksujen tunnistamiseen. | | `reference` | string | Kauppiaan oma viitenumero. | | `createdAt` | string | Luontiaikaleima ISO 8601 -muodossa. | | `href` | string | Linkki maksusivulle. Maksetuilla tapahtumilla kenttä on tyhjä tai puuttuu. | | `provider` | string | Käytetty maksuntarjoaja, esim. `"nordea"` tai `"visa"` (voi puuttua). | **Mahdolliset tila-arvot (`status`):** | Arvo | Merkitys | | -------------------- | ------------------------------------------------------------ | | `new` | Maksu on luotu, asiakas ei ole vielä siirtynyt maksusivulle. | | `ok` | Maksu suoritettu onnistuneesti. | | `fail` | Maksu epäonnistui tai asiakas peruutti. | | `pending` | Maksu käsittelyssä (odottaa vahvistusta). | | `delayed` | Maksun käsittely viivästynyt. | | `authorization-hold` | Korttivaraus tehty, lopullinen veloitus odottaa. | ### list_payment_providers **Kuvaus:** Listaa kauppiaan käytettävissä olevat maksutavat. Käytä tätä, jos haluat tarkistaa mitkä maksutavat ovat käytössä ennen maksupyynnön luomista. Tuloksia voi rajata summan tai maksutaparyhmän mukaan. **Syötteet:** | Kenttä | Pakollinen | Tyyppi | Kuvaus | | ------------ | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------- | | `merchantId` | Kyllä | number | Kauppiaan tunniste. | | `amount` | Ei | integer | Rajaa tulokset tarjoajiin, jotka tukevat kyseistä summaa (senteissä). | | `groups` | Ei | array | Rajaa tulokset yhteen tai useampaan ryhmään. Sallitut arvot: `"creditcard"`, `"bank"`, `"mobile"`, `"credit"`, `"other"`. | **Esimerkkivastaus:** ```json [ { "id": "nordea", "name": "Nordea", "icon": "https://resources.paytrail.com/images/payment-method-logos/nordea.png", "svg": "https://resources.paytrail.com/images/payment-method-logos/nordea.svg", "group": "bank" } ] ``` | Kenttä | Tyyppi | Kuvaus | | ------- | ------ | ----------------------------------------------------------------------------------- | | `id` | string | Maksuntarjoajan tekninen tunniste. | | `name` | string | Maksuntarjoajan näyttönimi. | | `icon` | string | URL PNG-muotoiseen logoon. | | `svg` | string | URL SVG-muotoiseen logoon. | | `group` | string | Ryhmä, johon tarjoaja kuuluu: `bank`, `creditcard`, `mobile`, `credit` tai `other`. | --- ## Kirjautuminen ?> Kirjaudut kerran Paytrailin omaan kirjautumispalveluun — yhteys on turvallinen ja väliaikainen. Tekoälyassistentti ei koskaan näe salasanaasi. Kirjautuminen perustuu OAuth 2.0 PKCE -virtaan (Proof Key for Code Exchange). Se on vakiotapa tunnistautua sovelluksissa, jotka eivät voi säilyttää salaista avainta. Käytännössä MCP-asiakas (esim. Claude Desktop) hoitaa kirjautumisen automaattisesti — käyttäjän tarvitsee vain syöttää kauppiaspaneelin tunnukset avautuvaan kirjautumisikkunaan. Tunnistuspalveluna toimii AWS Cognito, johon Paytrailin Kauppiaspaneelin käyttäjät on rekisteröity. ### Istunnon elinkaari Istunto on voimassa 14 vuorokautta viimeisimmästä pyynnöstä lukien.