Korttimaksulinkit

Korttimaksulinkit mahdollistavat laskujen maksamisen kortilla. Voit luoda maksulinkin mille tahansa laskulle ja jakaa sen asiakkaallesi.

Huomio

Korttimaksulinkit vaativat Yrittäjä-paketin tai ylemmän. Tilaukset ja hinnoittelu →

Toimintaperiaate

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Kirjapro       │────▶│  create-payment- │────▶│   Stripe API    │
│   (luo linkki)  │     │  link            │     │  (payment link) │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                         │
         ┌───────────────────────────────────────────────┘
         ▼
┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   Asiakas        │────▶│   Stripe         │────▶│  stripe-invoice- │
│   (maksaa)      │     │   Checkout       │     │  webhook        │
└─────────────────┘     └──────────────────┘     └─────────────────┘
                                                         │
                                                         ▼
                                                  ┌─────────────────┐
                                                  │  Lasku merkitään │
                                                  │  maksetuksi      │
                                                  └─────────────────┘

1. Luo maksulinkki — Avaa lasku ja klikkaa “Luo maksulinkki”
2. Jaa linkki — Kopioi linkki ja lähetä asiakkaallesi (sähköposti, chat, jne.)
3. Asiakas maksaa — Asiakas avaa linkin ja maksaa kortilla Stripen turvallisella maksusivulla
4. Automaattinen päivitys — Maksun jälkeen lasku merkitään automaattisesti maksetuksi

Käyttöliittymässä

Maksulinkki luodaan laskun tiedot -sivulla:

1. Avaa lasku kohdasta Laskut → valitse lasku
2. Klikkaa Luo maksulinkki -painiketta
3. Linkki kopioidaan automaattisesti leikepöydälle
4. Jos linkki on jo luotu, näet Kopioi maksulinkki -painikkeen

Vinkki

Jos laskulle on jo aktiivinen maksulinkki, järjestelmä palauttaa olemassa olevan linkin uuden luomisen sijaan. Näin vältetään päällekkäiset maksulinkit.

API-rajapinta

Maksulinkin luominen

const response = await fetch(
  `${SUPABASE_URL}/functions/v1/create-payment-link`,
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${accessToken}`,
      'apikey': SUPABASE_ANON_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      companyId: 'uuid',
      invoiceId: 'uuid',
      amount: 1240.00,
      invoiceNumber: '2025-001',
      customerName: 'Asiakas Oy'
    }),
  }
);

const { paymentUrl, paymentToken } = await response.json();

Request

Kenttä	Tyyppi	Pakollinen	Kuvaus
companyId	UUID	Kyllä	Yrityksen ID
invoiceId	UUID	Kyllä	Laskun ID
amount	number	Kyllä	Summa euroina (min. 0.50, max. 999 999.99)
invoiceNumber	string	Kyllä	Laskun numero (näytetään maksusivulla)
customerName	string	Kyllä	Asiakkaan nimi (näytetään maksusivulla)

Response

{
  "success": true,
  "paymentUrl": "https://buy.stripe.com/...",
  "paymentToken": "abc123...",
  "existing": false
}

Kenttä	Kuvaus
paymentUrl	Stripen maksulinkin URL — jaa tämä asiakkaalle
paymentToken	Uniikki tunniste maksulinkin seurantaan
existing	true jos palautettiin olemassa oleva aktiivinen linkki

Maksulinkin tila

Tila	Merkitys
active	Linkki on aktiivinen ja odottaa maksua
paid	Asiakas on maksanut — lasku päivitetty automaattisesti
expired	Linkki on vanhentunut (30 päivää luomisesta)
cancelled	Linkki on peruutettu

Webhook-käsittely

Maksulinkkien maksutapahtumat käsitellään erillisellä stripe-invoice-webhook -endpointilla (eri kuin tilausten webhook). Webhook:

1. Vastaanottaa checkout.session.completed -tapahtuman
2. Yhdistää maksun invoice_payment_links -taulun tietoihin
3. Päivittää maksulinkin tilan (active → paid)
4. Merkitsee laskun maksetuksi (status: 'paid', paid_date)
5. Tallentaa Stripe Payment Intent ID:n

Rajoitukset

• Minimisumma: 0,50 EUR
• Maksimisumma: 999 999,99 EUR
• Linkin voimassaolo: 30 päivää
• Peruutettuja (cancelled) tai maksettuja (paid) laskuja ei voi linkittää
• Vaatii Yrittäjä-paketin tai ylemmän

Virhekoodit

Koodi	Viesti	Ratkaisu
INVOICE_NOT_FOUND	Laskua ei löydy	Tarkista laskun ID
INVOICE_ALREADY_PAID	Lasku on jo maksettu	Ei voi luoda maksulinkkiä
INVOICE_CANCELLED	Lasku on peruutettu	Ei voi luoda maksulinkkiä
AMOUNT_TOO_LOW	Summa alle 0,50 EUR	Nosta summaa
AMOUNT_TOO_HIGH	Summa yli 999 999,99 EUR	Laske summaa
FEATURE_NOT_AVAILABLE	Paketti ei riitä	Päivitä Yrittäjä-pakettiin

Turvallisuus

• Maksulinkin token generoidaan kryptografisesti (URL-safe base64, 24 tavua)
• Yrityksen jäsenyys tarkistetaan ennen linkin luomista
• Laskun omistajuus varmistetaan (lasku kuuluu yritykselle)
• Stripe-maksusivu on PCI DSS -yhteensopiva — korttitiedot eivät kulje Kirjapron kautta

Seuraavaksi

• Stripe-integraatio — Tilaukset ja webhook-käsittely
• API-referenssi — Kaikki endpointit
• Virhekoodit — Virhekäsittely