Pankki- ja maksuantuet

camt.053-tiliotteet, Stripe CSV, PSP-tilitysten täsmäytys ja mukautetut JSON-syötteet.

Kaikki tuonnit tallentuvat pankkitapahtumina pankkitilille (bank/accounts/create). Tapahtumilla on externalId-tunniste, ja saman tiedoston uudelleentuonti on turvallista: rivit, joiden (bankAccountId, externalId) on jo olemassa, ohitetaan ja ilmoitetaan skipped-laskurissa. Tuodut tapahtumat saavat aluksi tilan new, ja ne kirjataan kirjanpitoon vasta, kun ne täsmäytetään (bank/transactions/match, ehdokkaat haetaan osoitteesta bank/transactions/suggest-matches).

Verkkosovelluksessa samat tuonnit löytyvät kohdasta Pankki → Tuo tiedosto (tiedoston lataus, mallipohjan valinta).

Virheellinen täsmäytys voidaan perua komennolla bank/transactions/unmatch (käyttöliittymässä Pankki → Tapahtumat ja Poista täsmäytys). Kirjattuja vientejä ei koskaan muokata tai poisteta: laskuun täsmäytetty maksu tai tuontimallin tilille kirjaama rivi saa oikaisukirjauksen, jossa kaikki viennit ovat vastakirjauksia. Oikaisun päivämääränä käytetään kenttää date (oletus: tänpäivä, ei kuitenkaan ennen alkuperäistä kirjausta). Laskun maksettu summa ja maksutila palautuvat kyseisen pankkirivin verran taaksepäin. Maksupalveluntarjoajan tilitykseen linkitetty rivi ainoastaan vapautetaan linkityksestä, koska tilityskirjaus kuuluu eräänä kokonaisuutena erään toiseen erään. Rivi palaa tilaan new ja se voidaan täsmäyttää uudelleen. Oikaisupäivän on osuttava avoimelle tilikaudelle.

Tuontipohjat

Tuontipohja määrittää tietolähteen, listaa lähteen tarjoamat kentät ja yhdistää rahaa siirtävät kentät kirjanpidon tileille. Pohjia hallitaan kohdassa Pankki → Tuontipohjat sekä rajapinnan kautta bank/import-templates/create|update|delete|get|list.

POST /v1/bank/import-templates/create
{
  "name": "Stripe payments export",
  "type": "stripe",
  "fields": [
    { "name": "id" },
    { "name": "Created date (UTC)" },
    { "name": "Amount" },
    { "name": "Fee", "accountCode": "6800" },
    { "name": "Amount Refunded" }
  ],
  "metaFields": ["order_id"]
}

Kenttä type on jokin arvoista stripe, iso20022, bank_connection tai revolut.
Jokaisella kentällä on name ja valinnainen accountCode. Vain rahaa siirtävät kentät hyväksyvät tilin: Stripen Amount, Fee ja Amount Refunded; camt.053:n Ntry/Amt; pankkiyhteyden transaction_amount.amount. Tilin on löydyttävä tilikartasta (luo se osoitteessa ledger/accounts/create).
Kenttä fields voidaan jättää pois, jolloin se oletusarvoisesti käyttää kyseisen tyypin vakiokenttäluetteloa: Stripen Payments → Export -tiedoston sarakkeita (lukuun ottamatta 19 Card … -saraketta, jotka myös lomake jättää oletuksena valitsematta), camt.053-elementtejä, jotka jokainen tiliote sisältää (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt), tai attribuutteja, jotka PSD2-pankkiyhteys palauttaa tapahtumaa kohti. Lisää tai poista rivejä tiedostoasi vastaavasti: tuontiohjelma lukee myös valinnaiset camt.053-elementit Ntry/ValDt, Ntry/NtryRef, Ntry/AcctSvcrRef, Ntry/AddtlNtryInf, TxDtls/Refs/EndToEndId, TxDtls/Refs/TxId, TxDtls/RltdPties/Dbtr/Nm, TxDtls/RltdPties/DbtrAcct/Id/IBAN, TxDtls/RltdPties/Cdtr/Nm, TxDtls/RltdPties/CdtrAcct/Id/IBAN, TxDtls/RmtInf/Ustrd ja TxDtls/AddtlTxInf.
Stripen Customer Email -kentässä voi olla asetus "createPartner": true. Tuonti luo tällöin asiakkaan (luonnollinen henkilö, asiakasroolissa) jokaiselle tiedostosta löytyvälle sähköpostiosoitteelle, jota ei vielä ole olemassa olevilla kumppaneilla. Nimenä käytetään kenttää Customer Description (tai sähköpostiosoitetta, jos se on tyhjä) ja osoitteena Card Address … -sarakkeita, jos tiedosto sisältää ne. Olemassa olevat kumppanit tunnistetaan sähköpostiosoitteen perusteella kirjainkoolla erottelematta. Vastaus ilmoittaa luotujen määrän kentässä customersCreated.
metaFields (vain Stripe) listaa maksuihisi liittyvät metatietoavaimet. Stripe vie jokaisen avaimen muodossa <key> (metadata); lista on vapaamuotoinen ja voi olla pitkä.
invoiceItemId (vain Stripe, valinnainen) on tuoteluettelon nimike. Kun tämä on asetettu, jokainen tuonnin luoma laskun ja hyvityslaskun rivi viittaa kyseiseen nimikkeeseen (sen kirjanpitotiliin ja, jos kenttä invoiceVatRatePercent on tyhjä, sen arvonlisäverokantaan). Rivin teksti tulee kuitenkin maksutapahtumasta.
companyMetaField (vain Stripe) nimeää yhden näistä avaimista yrityslipuksi. Kun maksussa on kyseisessä sarakkeessa arvo true, 1, yes, company, business tai b2b, sille luotu asiakas on henkilön sijaan yrityskumppani.
invoiceMetaField (vain Stripe) nimeää jonkin näistä avaimista (esimerkiksi tilausnumeron) ja invoiceVatRatePercent määrittää siitä luotujen laskujen alv-kannan. Tuonnissa jokainen maksu- ja hyvitystaparivi ryhmitellään kyseisen avaimen arvon mukaan:
- arvo, joka vastaa olemassa olevaa myyntilaskua (myyntitilaus, jonka externalRef on kyseinen arvo (ecommerce/orders/create, mikä tahansa kanava) tai lasku, jonka fullNumber on kyseinen arvo), linkittää ryhmän kyseiseen laskuun;
- arvo, jolla ei ole laskua, luo sellaisen: kumppani haetaan kentästä Customer Email (luodaan puuttuessa samalla tavalla kuin kohdassa createPartner), yksi rivi maksua kohden (Checkout Line Item Summary tai Description tekstinä, maksun summa alv:n sisältävänä hintana kriteerillä invoiceVatRatePercent), laskutuspäivä = ensimmäinen maksupäivä, arvonlisäverokäsittely yrityksen ja kortin maan mukaan. Lasku luodaan ja kirjataan heti, ja myyntitilaus kanavalla stripe ja kyseisellä arvolla kentässä externalRef tallennetaan, jotta tulevat tuonnit tekevät linkityksen uuden luomisen sijaan;
- jokainen ryhmän maksu täsmäytetään sitten laskuun suorituksena (kirjataan saapuneeksi); jokainen hyvitys luo annetulle hyvitetylle summakehitykselle hyvityslaskun laskua vastaan ja täsmäyttää hyvityksen siihen. Tuloksena palautuvat määrät invoicesCreated, invoicesLinked, creditNotesCreated ja paymentsMatched. Ryhmiä, joita ei voitu käsitellä (ei asiakkaan sähköpostia, eri valuuttoja, linkitetty lasku on vielä luonnos tai jo kokonaan maksettu), listataan varoituksissa (warnings) ja ne jätetään tilan new pankkitapahtumiksi. Älä myöskään yhdistä kenttää Amount kirjanpidon tilille samassa mallipohjassa: laskuun täsmäytettyä maksua ei kirjata toistamiseen, mutta täsmäyttämätön kirjattaisiin.
Pohjien nimet ovat yrityskohtaisesti ainutlaatuisia.
camt.053- ja pankkiyhteyspohjissa on samat valinnat, jotka luetaan tiliotteesta Stripen sarakkeiden sijaan:
- Luo puuttuvat kumppanit: Asetus createPartner velkojan nimirivillä (TxDtls/RltdPties/Dbtr/Nm, syötteessä debtor.name) luo asiakkaan jokaiselle tuntemattomalle saapuvan rahan maksajalle. Vastaavasti saajan nimirivillä (TxDtls/RltdPties/Cdtr/Nm, syötteessä creditor.name) luodaan toimittaja jokaiselle tuntemattomalle lähtevän rahan saajalle. Kumppanit tunnistetaan IBAN-numeron (tallennetaan kenttään partner_bank_accounts) ja sen jälkeen tarkan nimen perusteella. Uusi kumppani määritellään yritykseksi, jos nimessä on yhtiömuoto (UAB, MB, SIA, GmbH, Ltd jne.), muussa tapauksessa henkilöksi. Määrä palautuu nimellä customersCreated (tiedostotuonti) tai partnersCreated (syotesynkronointi).
- Linkitä laskut viitteen mukaan: Kun invoiceMetaField on asetettu viesti- tai viiteriville (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; syöte remittance_information, reference_number), se täsmäyttää jokaisen uuden pankkirivin, jonka viite, viesti tai kuvaus sisältää avoimen myyntilaskun (saapuva raha) tai rekisteröidyn ostolaskun (lähtevä raha) numeron, ja kirjaa suorituksen. Kun maksajan IBAN on tallennettu kumppanille tai maksajan nimi vastaa kumppanin nimeä tai koodia, laskun on kuuluttava kyseiselle kumppanille. Tuntemattoman maksajan maksu linkitetään vain, jos se vastaa laskun jäännössummaa ja laskun numerossa on sarjaliite, jotta pelkkää summaa tai vastaavaa ei koskaan tulkita viitteeksi. Jäännössummaa suurempaa maksua ei koskaan linkitetä. Nämä tarkistukset läpäisemättömät rivit pysyvät tilassa new manuaalista täsmäytystä varten ja ne listataan varoituksissa. Asetuksella advanceInvoices: true tunnetun kumppanin täsmäyttämätön saapuva maksu luo ennakkomaksulaskun (tyyppi advance) summalle käyttäen arvoa invoiceVatRatePercent tai kenttää invoiceItemId ja täsmäyttää maksun siihen. Kumppanin on oltava tiedossa, joten valitse myös velkojan rivi.
- Kirjaussäännöt tapahtumakoodin perusteella: Kentän Ntry/Amt / transaction_amount.amount lisäksi kenttäluettelossa on sääntörivit Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (syöte: bank_transaction_code=…, credit_debit_indicator=…). Rivi kirjataan sen säännön tilille, johon se ensimmäisenä täsmää: pankkitapahtumakoodiperhe, sitten suunta ja lopulta pelkkä summarivi. Sääntörivejä ei tarkisteta tiedostoa vasten.
- Pankkikulujen kumppani: Asetus createPartner sääntörivillä …=CHRG luo pankin nimisen toimittajan (tiliotteen Stmt/Acct/Svcr/FinInstnId/Nm, yhteyden pankin tai kirjanpidon pankkitilin nimen mukaan) ja kirjaa jokaisen kulun kyseiselle kumppanille.
- Pankkiyhteyspohjat valitaan syötetiliä kohden komennolla bank/feeds/accounts/configure (sovelluksen kohdassa Pankki → Yhteydet), jolla määritetään myös syncSchedule (manual, daily, weekly, monthly). Rajapinta synkronoi aikataulutetut tilit automaattisesti niiden kauden päätyttyä. Pohjia sovelletaan jokaisen bank/feeds/sync-kutsun yhteydessä, ja synkronointivastaus ilmoittaa lisäksi arvot posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched ja warnings.

Välitä templateId osoitteeseen bank/statements/import parametrin format sijaan: pohjan tyyppi määrittää jäsennysosan, ja tiedoston on sisällettävä kaikki pohjassa luetellut kentät. Tiedosto, josta puuttuu jokin niistä, hylätään HTTP-tilakoodilla 422, ja puuttuvat sarake- tai elementtinimet ilmoitetaan. Metatietokenttien ei tarvitse olla läsnä. Pankkiyhteyspohjat kuvaavat reaaliaikaista PSD2-syötettä, eikä niitä voi käyttää tiedostotuontiin.

ISO 20022 -pohja lukee myös MT940-tiedostoja: tiedosto, joka alkaa merkkijonolla {1: tai :20: (tai lähetetään arvolla "format": "mt940"), jäsennetään MT940-muodossa, ja pohjan viitetäsmäystystä sekä kirjaussääntöjä sovelletaan sen riveihin. Elementtitarkistus ohitetaan MT940-tiedostojen osalta, eivätkä säännöt Ntry/BkTxCd=… koskaan päde MT940-riveihin, koska MT940 ei sisällä ISO 20022 -pankkitapahtumakoodia. Käytä sen sijaan sääntöjä Ntry/CdtDbtInd=….

Pankkitilillä voi olla vain yksi valuutta. Eri valuutassa oleva tiliote hylätään HTTP-tilakoodilla 422 (camt.053-tiedostossa, joka sisältää tiliotteita useissa valuutoissa samalle IBANille, tuodaan vain tilitilin valuuttaa vastaava tiliote). Sama koskee riviä, joka lähetetään osoitteeseen bank/transactions/import muulla kuin tilin omalla valuutalla.

Jokainen liike, joka on peräisin accountCode-määritteen sisältävästä kentästä, kirjataan tuontihetkellä yhtenä tositteena: saapuva raha debitoi pankkitilin kirjanpitotiliä ja kreditoi kohdetiliä; lähtevä raha debitoi kohdetiliä ja kreditoi pankkitilin kirjanpitotiliä. Summat muunnetaan perusvaluuttaan liiketapahtuman päivänä. Pankkitapahtuma täsmäytetään (matched) tähän tositteeseen (matchedDocumentType = journal_transaction), eikä sitä enää tarjota laskujen täsmäyttämiseen. Vastaus ilmoittaa lukumäärän kentässä posted. Liikkeet, jotka tulevat yhdistämättömistä kentistä, pysyvät tilassa new ja ne täsmäytetään laskuihin kuten ennenkin. Esimerkiksi kenttä Fee voidaan yhdistää PSP-kulujen tulos tilille ja jättää Amount yhdistämättä, jolloin maksut täsmäytyvät edelleen myyntilaskuihin.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "…",
  "content": "id,Created date (UTC),Amount,…"
}

ISO 20022 camt.053 (avoimen pankkitoiminnan XML)

Liettualaiset pankit (Swedbank, SEB, Luminor, Šiaulių bankas jne.) mahdollistavat tiliotteiden lataamisen ISO 20022 camt.053 -XML-muodossa verkkopankistaan (yleensä tiliotteiden viennin/latauksen kautta muodossa "ISO XML" tai "camt.053"). Sama muoto palautetaan myös PSD2-tilitietorajapinnoista.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}

Tiedosto voi sisältää useita tiliotteita. Jokaisen tiliotteen IBAN-numeron on vastattava pankkitilin IBAN-numeroa (tiliotteet ilman IBAN-numeroa tai tilit ilman sitä hyväksytään sellaisenaan).
Kirjausviitteet (AcctSvcrRef/NtryRef, varajärjestelmänä sisällön tiiviste) toimivat tunnisteena externalId.
Vastaus palauttaa tiliotekohtaiset metatiedot: tiliotteen tunniste, ajanjakso, alku- ja loppusaldot sekä tapahtumien määrä.
Vastapuolen nimi, IBAN ja maksun selite poimitaan kirjauskohtaisesti täsmäytystä varten.

Maksut vastakkaiseen suuntaan viedään muodossa pain.001 rajapinnan bank/payments/export kautta.

Revolut Business CSV

Lataa Revolut Business -tilin tiliote CSV-muodossa ja tuo se sisäänrakennetulla pohjalla Revolut Business (templateId: "builtin-revolut"). Jokaisella yrityksellä on tämä pohja ilman erillistä luontia: bank/import-templates/list-builtin listaa sen, bank/import-templates/get hakee sen, ja komennot bank/import-templates/update sekä bank/import-templates/delete hylkäävät sen virheellä HTTP 400. Sovelluksessa se näkyy ensimmäisenä kohdassa Pankki → Tuontipohjat; sen avaaminen näyttää sen asetukset, ja sen tallentaminen luo oman yrityskohtaisen pohjan, jota voit muokata.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "builtin-revolut",
  "content": "Date started (UTC),Date completed (UTC),ID,Type,State,…"
}

Vain rivit, joiden tila on State = COMPLETED, tuodaan. Muut rivit (esimerkiksi PENDING) jätetään pois ja lasketaan mukaan varoituksiin (warnings); ne tuodaan myöhemmällä tuonnilla, kun niiden tila on valmis.
Jokaisesta rivistä tulee pankkitapahtuma, jossa päivämääränä käytetään kenttää Date completed (UTC), summana kenttää Total amount, valuuttana kenttää Payment currency, tunnisteena ID (externalId) ja kuvauksena kenttää Description.
Lähtevän rahan vastapuolena käytetään kenttiä Beneficiary name ja Beneficiary IBAN; korttimaksussa ilman edunsaajaa käytetään kuvauksen Description mukaista kauppiasta. Saapuvan rahan vastapuolena käytetään kenttiä Sender name ja Sender account.
Rivit ryhmitellään tilin ja valuutan mukaan. Kentän International account number on vastattava pankkitilin IBAN-numeroa, ja vain pankkitilin valuutassa olevat rivit tuodaan.
Tuontiohjelma tarkistaa jokaisen rivin osalta, että edellisen rivin saldo lisättynä summalla Total amount vastaa kenttää Balance, ja ilmoittaa kaikki rivit, joissa näin ei ole, varoituksissa (warnings).
Tiedoston on sisällettävä sarakkeet Date completed (UTC), ID, Type, State, Description, Payment currency, Total amount, Reference, Sender name ja Beneficiary name.

Sisäänrakennettu pohja tekee jokaisella tuonnilla seuraavat toimet:

luo asiakkaan jokaiselle tuntemattomalle saapuvan rahan lähettäjälle ja toimittajan jokaiselle tuntemattomalle edunsaajalle tai korttikauppiaalle kohdan Luo puuttuvat kumppanit mukaisesti;
täsmäyttää jokaisen rivin, jonka viite Reference tai kuvaus Description sisältää avoimen myynti- tai ostolaskun numeron, ja kirjaa maksun kohdan Linkitä laskut viitteen mukaan mukaisesti;

kirjaa rivit, joita mikään lasku ei täsmännyt, tyypin Type perusteella kirjaussäännön tilille:

`Type`	Kirjaussääntö	Oletustili	Romanialainen tilikartta	Kirjaus
`FEE`	`bank.fees`	6800	627	debitoi säännön tiliä, kreditoi pankkitilin kirjanpitotiliä; kumppani: pankkitilin mukaan nimetty toimittaja
`CARD_PAYMENT`	`bank.cardPayments`	6209	628	debitoi säännön tiliä, kreditoi pankkitilin kirjanpitotiliä, ilman arvonlisäveroa
`TOPUP`	`bank.topUps`	3010	1012	debitoi pankkitilin kirjanpitotiliä, kreditoi säännön tiliä

Muun tyyppiset rivit, kuten TRANSFER, jäävät tilaan new täsmäytettäviksi.

Muuta tilejä komennolla ledger/posting-rules/update. Sisäänrakennettu pohja käyttää uusia tilejä seuraavasta tuonnista alkaen. Kirjaussääntöä ei voi poistaa käytöstä: jos haluat tuoda korttimaksuja tai latauksia ilman kirjausta, luo revolut-tyyppinen yrityspohja ilman sääntörivejä Type=CARD_PAYMENT tai Type=TOPUP ja tuo tiedosto sillä tavalla. Tällä tavalla kirjatulla korttimaksulla ei täsmäytetä toimittajan laskua, kun kyseinen lasku rekisteröidään myöhemmin. Kirjaa jompikumpi, älä molempia.

Tyypin revolut yrityspohja käyttää samoja sarakkeita ja voi kirjata rivejä tyypin mukaan sääntöriveillä Type=FEE, Type=CARD_PAYMENT, Type=TRANSFER ja Type=TOPUP. Tuonti komennolla "format": "revolut-csv" ilman pohjaa tuo rivit ilman mitään näistä vaiheista.

Stripe CSV

Vie tiedot Stripen hallintapaneelista – kumpi tahansa raportti käy:

Reports → Balance → Itemized balance change from activity (suositeltu): sarakkeet balance_transaction_id, created_utc, currency, gross, fee, net, reporting_category, description.
Payments → Export: sarakkeet id, Created (UTC), Amount, Fee, Currency, Description, Customer Description.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "stripe-csv",
  "content": "balance_transaction_id,created_utc,currency,gross,fee,net,…"
}

Luo Stripelle oma pankkitili (esimerkiksi nimellä "Stripe", pääkirjanpitotili 2710 tai oma alitili). Stripen saldo toimii kuten pankkitili: maksut virtaavat sisään, kulut vähennetään ja tilitykset siirtävät saldon oikealle pankkitilillesi.

Tuonnin toiminta:

Jokaisesta saldotapahtumasta tulee yksi pankkitapahtuma bruttosummalle (externalId = saldotapahtuman tunniste).
Nollasta poikkeavasta kulusta tulee toinen tapahtuma vastakkaisella etumerkillä (externalId = <id>:fee, vastapuolena "Stripe"), jotta kulut voidaan täsmäyttää ja kirjata kuluina erillään myynnistä. Hyvitysten yhteydessä palautetut kulut tulevat sisään positiivisina summina.
Tilitysrivit (Payout) tuodaan yksittäisinä negatiivisina tapahtumina; täsmäytä ne oikean pankkitilisi tiliotteen vastaavaan saapuvaan tapahtumaan.
Nollasummaiset rivit ohitetaan; päivämäärä otetaan kentästä created_utc (UTC).
Payments-vientirivit, jotka eivät siirtäneet rahaa, ohitetaan: Captured = false (katevaraukset / myöhästyneet veloitukset) ja Status Failed/Canceled.
Nollasta poikkeavasta palautetusta summasta (Amount Refunded) tulee kolmas, negatiivinen tapahtuma (externalId = <id>:refund), jonka päivämääränä on Refunded date (UTC). Näin maksuriveille upotetut osittaiset ja täydelliset hyvitykset eivät katoa.

PSP-tilitysten täsmäytys (Stripen tilitysraportit)

Jos haluat jakaa könttäsummatilityksen sen taustalla oleviin tilauksiin, hyvityksiin, kuluihin ja takaisinveloityksiin, käytä pelkän tiliotetuonnin sijaan tilitysrajapintoja. Hyväksyttyjä Stripe-vientitiedostoja on kaksi (tunnistetaan automaattisesti):

Reports → Payouts → Payout reconciliation, itemized (raporttityypit payout_reconciliation.itemized.* tai payout_reconciliation.by_id.itemized.*) – tarkka, yksi rivi per saldotapahtuma; suositeltava tuotantotileillä.
Payments → Export (unified payments) – veloitustason vienti; toimii testielementti-/hiekkalaatikkotilassa, jossa tilitysten täsmäytys ei ole käytettävissä. Veloitetut maksut ryhmitellään tilitystunnuksen mukaan sarakkeessa Transfer; veloittamattomat/epäonnistuneet rivit ohitetaan (skippedNotSettled); nollasta poikkeava Amount Refunded luo synteettisen hyvitysrivin maksun tilityserään – arvio, koska hyvitys on saattanut todellisuudessa realisoitua myöhemmässä tilityksessä. Täsmäytysviitteet tulevat maksun tunnuksesta, PaymentIntent ID:stä, laskun numerosta (Invoice Number), asiakkaan viitetunnuksesta (Client Reference ID) ja jokaisesta sarakkeesta … (metadata) (esimerkiksi metatiedoissa olevasta tilausnumerosta).

Yksi CSV-tiedosto voi kattaa useita tilityksiä. Stripe lataa eritellyn raportin yhtenä tiedostona osiota kohden (…_charge_…, …_refund_…, …_fee_…). Tuo ne kaikki: jo tuodun tilityksen rivit sulautuvat olemassa olevaan erään (mistä ilmoitetaan laskurissa updated), kun sitä ei ole vielä kirjattu, ja erän kokonaissummat lasketaan uudelleen.

POST /v1/bank/settlements/import
{
  "bankAccountId": "…",
  "provider": "stripe",
  "content": "balance_transaction_id,created_utc,…,reporting_category,…,automatic_payout_id,…"
}

Tuonnin toiminta:

Rivit ryhmitellään sarakkeen automatic_payout_id perusteella tilityseriksi – yksi erä per tilitys, sisältäen brutto-, kulu- ja nettosummat (sarakkeen net summa = pankkiisi saapuva summa). Tilityksen uudelleentuonti ohitetaan (skipped-laskuri). Vielä tilitykseen liittymättömät rivit ja itse payout-rivit ohitetaan ja lasketaan erikseen.
Jokainen veloitus-, hyvitys- ja riitarivi täsmäytetään automaattisesti myyntilaskuun käyttämällä seuraavia tietoja järjestyksessä: verkkokauppatilauksen externalRef (mikä tahansa arvo kentistä order_id, payment_intent_id, source_id, charge_id tai mikä tahansa *_metadata[...]-sarake), kyseisissä sarakkeissa esiintyvä laskun fullNumber sekä – hyvitysten ja takaisinveloitysten osalta – aiemmin täsmäytetyn maksun charge_id (samasta tiedostosta tai aiemmista tuonneista).
Tarkista tiedot osoitteessa bank/settlements/list / bank/settlements/get; korjaa jäljelle jääneet tapaukset komennolla bank/settlements/match { lineId, invoiceId } (tai invoiceId: null, jos poistat täsmäytyksen).

Kutsu POST /v1/bank/settlements/post { id, date?, commissionPercent? } kirjaa koko erän yhtenä tasapainotettuna tositteena ja suorittaa täsmäytetyt laskut (paidAmount/paymentStatus, verkkohälytykset sale_invoice.paid):

Debitoi pankkitilin pääkirjanpitotiliä nettotilityksestä; debitoi PSP-kuluja (settlements.fees, oletus 6800) pidätetyistä kuluista ja kuluriveistä.
Kreditoi myyntisaamisia kutakin täsmäytettyä maksua kohden; hyvitykset ja takaisinveloitykset kääntävät tämän. Kohdistus on rajoitettu kunkin laskun jäännössummaan – ylimenevä osuus ohjautuu selvittelytilille varoituksen kera.
Täsmäyttämättömät maksut: kun commissionPercent on määritetty, ne jaetaan komissiotuloon (settlements.commissionRevenue, oletus 5001) ja myyjän velkaan (settlements.sellerPayable, oletus 4499) – markkinapaikkamalliin, jossa kerätyt varat kuuluvat pääasiassa myyjille. Ilman tätä määritystä ne sijoitetaan tilille settlements.suspense (oletus 4440, saadut ennakot).
Rivit platform_earning (Stripe Connect -sovellusmaksut) kirjataan komissiotuloon; rivit transfer (tilitykset liitetyille myyjille) vähentävät myyjän velkaa.
Kaikki neljä tiliä voidaan korvata yrityskohtaisesti kirjaussääntöjen kautta (ledger/posting-rules).
Rivi, jonka maksu, kulu tai hyvitys on jo tuodulle toiselle pankkitilille Stripe-maksuviennistä (bank/statements/import), ei kirjata kuluihin, saamisiin tai selvittelytiliin. Sen net-summa hyvitetään sen sijaan kyseisen pankkitilin kirjanpitotilille, jotta Stripen pankkitili nollautuu tilitys tilitykseltä. summary.clearedAmount on tällä tavalla siirretty kokonaissumma; rivi, jonka summa poikkeaa kyseisen tilin pitämästä summasta, nimetään kohdassa warnings. Jos mitään kirjaamatta ei jää, erä kirjataan ilman kirjaustunnistetta (journalTransactionId on null).

Komennot bank/settlements/list ja /get palauttavat erää kohden arvot clearedNet, clearingDifference (tilitysrivit miinus summat, joita toinen pankkitili pitää niille; nolla kun ne vastaavat toisiaan) ja clearingOpenCount (rivit, joissa on ero tai kirjaamaton liike); /get palauttaa saman rivikohtaisesti kenttinä clearingBankAccountId, clearingBooked, clearingDifference ja clearingUnposted. Yhden maksun hyvitysrivit verrataan yhdessä, koska maksuvienti sisältää vain hyvitetyn kokonaissumman. Stripe-maksuvienti, joka tuodaan sen jälkeen, kun sen tilitys on kirjattu, ohittaa kyseisen tilityksen liikkeet ja mainitsee sen kohdassa warnings.

Komission arvonlisävero laskutetaan erikseen (lähetä komissiolasku myyjälle); jako kohdistaa vain kerätyn käteisen.

Tilitykset muussa valuutassa

Kirjanpito tositteineen laaditaan aina yrityksen perusvaluutassa, mutta eri valuutassa oleva tilitys kirjataan automaattisesti ilman manuaalisia kirjauksia:

Erä muunnetaan kirjauspäivän kurssilla (date, varalla tilityspäivä, sitten tämä päivä). Kurssina käytetään yrityksen omaa kyseisen valuutan kurssia (reference/exchange-rates/set), jos se on vähintään yhtä tuore kuin virallinen kurssi, muussa tapauksessa viimeisintä virallista kurssia kyseisenä päivänä tai ennen sitä. Jos kurssia ei ole saatavilla, kutsu epäonnistuu tilakoodilla 422 ja kehottaa suorittamaan komennon reference/exchange-rates/sync.
Jokainen tili muunnetaan kyseisellä erän kurssilla lukuun ottamatta myyntisaamisia, jotka kuitataan sillä valuuttakurssilla (fxRate), jolla kukin lasku on alun perin laskutettu. Näiden kahden kurssin välinen erotus kirjataan tilille bank.fxGain (oletus 5803) tai bank.fxLoss (oletus 6803) toteutuneena kurssierona, jotta tosite pysyy tasapainossa.
Vastauksen yhteenveto (summary) palauttaa käytetyn kurssin fxRate ja siitä johtuvan kurssieron exchangeDifference, ja erä säilyttää kurssin, jolla se on kirjattu. Täsmäytettyä laskua, jonka oma valuutta poikkeaa erän valuutasta, ei kuitata: sen summa ohjautuu varoituksen kera selvittelytilille.
Yksi tuontirajoitus säilyy: yksittäinen tilitys, jonka rivit sekoittavat useita valuuttoja, hylätään tilakoodilla 422. Samoin hylätään uudelleentuonti, jonka valuutta poikkeaa kyseiselle tilitykselle jo tallennetusta.

Manuaaliset / mukautetut syötteet

Mitkä tahansa muut tiedot voidaan lähettää sellaisenaan JSON-muodossa:

POST /v1/bank/transactions/import
{
  "bankAccountId": "…",
  "transactions": [
    { "date": "2026-07-01", "amount": "-25.00", "currency": "EUR",
      "counterpartyName": "…", "description": "…", "externalId": "unique-ref-1" }
  ]
}

Anna kullekin tapahtumalle vakaa externalId-tunniste, jotta uudelleentuonnit pysyvät idempotentteina.