Nordlet

← Põhitõed / SDK-d

Panga- ja maksete import

camt.053 väljavõtted, Stripe CSV, PSP arvelduste vastavusse viitamine ja kohandatud JSON-vood.

Kõik imporditud andmed jõuavad pangakontole pangatransaktsioonidena (bank/accounts/create). Transaktsioonidel on unikaalne externalId tunnus; sama faili korduv importimine on turvaline, sest read, mille (bankAccountId, externalId) on juba olemas, jäetakse vahele ja neist antakse teada skipped loenduris. Imporditud transaktsioonid saavad alguses oleku new ning kantakse pearaamatusse alles siis, kui need on vastavusse viidud (kasutades otseteed bank/transactions/match, kus kandidaatide leidmiseks saab kasutada päringut bank/transactions/suggest-matches).

Veebirakenduses on samad impordifunktsioonid saadaval menüüs Pank → Impordi fail (faili üleslaadimine, malli valija).

Valesti tehtud vastavusse viimise saab tagasi võtta päringuga bank/transactions/unmatch (rakenduses Pank → Transaktsioonid nupuga Eemalda vaste). Juba pearaamatusse kantud kandeid ei muudeta ega kustutata kunagi: kui makse on seotud arvega või kui impordimall on kandnud rea kontole, luuakse vastaskannetega paranduskanne (reversing journal transaction), kus kõik read on vastupidise märgiga ning mille kuupäevaks (date) märgitakse vaikimisi tänane päev (see ei saa olla varasem kui algne kande kuupäev). Arve tasutud summa ja makseolek vähenevad vastava pangarea summa võrra. Makseteenuse pakkuja (PSP) arveldusega seotud rida lahutatakse ainult seosest, kuna arvelduse kanne kuulub koondpaketti. Rida naaseb olekusse new ja seda saab uuesti siduda. Paranduskande kuupäev peab langema avatud raamatupidamisperioodi sisse.

Impordimallid

Impordimall määratleb andmeallika, loetleb allika pakutavad väljad ja seob rahasummasid kandvad väljad kontodega pearaamatus. Malle hallatakse menüüs Pank → Impordimallid ning API otspunktide kaudu 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"]
}
  • type väärtuseks peab olema stripe, iso20022, bank_connection või revolut.
  • Igal väljal on name ja valikuline accountCode. Kontot saab määrata ainult rahasummasid kandvatele väljadele: Stripe'i puhul Amount, Fee ja Amount Refunded; camt.053 puhul Ntry/Amt; pangakonto voo puhul transaction_amount.amount. Konto peab kontoplaanis olema loodud (selle saab luua päringuga ledger/accounts/create).
  • Väljade loendi (fields) võib ka ära jätta; sellisel juhul rakendatakse tüübi standardset väljade loendit: Stripe'i Payments → Export faili veergude nimed (ilma 19 Card … veeruta, mis jäetakse ka vormil vaikimisi märkimata); camt.053 elemendid, mis sisalduvad igas väljavõttes (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt); või atribuudid, mida PSD2 pangavoog iga transaktsiooni kohta tagastab. Failiga sobitamiseks saate kirjeid lisada või eemaldada: importija loeb ka valikulisi camt.053 elemente 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.
  • Stripe'i väli Customer Email võib sisaldada seadistust "createPartner": true. Sellisel juhul loob import failis leiduva iga e-posti aadressi jaoks, millel puudub vaste olemasolevate partnerite seas, uue kliendi (füüsilisest isikust partner, märgistatud kliendina). Nvena kasutatakse välja Customer Description väärtust (kui see puudub, siis e-posti aadressi) ning aadressina veerus Card Address … leiduvaid andmeid, kui fail neid sisaldab. Olemasolevate partneritega sobitatakse e-posti aadressi alusel (tõstutundetult). Vastus esitab loodud klientide arvu väljal customersCreated.
  • metaFields (ainult Stripe'i puhul) loetleb maksetega seotud metaandmete võtmed. Stripe ekspordib iga võtme veeruna <key> (metadata); see loend on vabas vormis ja võib olla pikk.
  • invoiceItemId (ainult Stripe'i puhul, valikuline) on kataloogi artikli ID. Kui see on määratud, viitab iga arve ja kreeditarve rida, mille import loob, sellele artiklile (selle kande kontole ja, kui invoiceVatRatePercent on täitmata, selle käibemaksumäärale); rea tekst pärineb endiselt tasult.
  • companyMetaField (ainult Stripe'i puhul) määrab ühe neist võtmetest ettevõtte tunnuseks. Kui laeng sisaldab selles veerus väärtust true, 1, yes, company, business või b2b, luuakse selle jaoks füüsilise isiku asemel juriidilisest isikust partner.
  • invoiceMetaField (ainult Stripe'i puhul) määrab ühe neist võtmetest (näiteks tellimuse numbri) ning invoiceVatRatePercent määrab sellest loodavate arvete käibemaksumäära. Impordil rühmitatakse iga laengu ja tagasimakse rida selle võtme väärtuse alusel:
    • väärtus, mis vastab olemasolevale müügiarvele (müügitellimus, mille externalRef on see väärtus (ecommerce/orders/create, mis tahes kanalist) või arve, mille fullNumber on see väärtus), seob rühma selle arvega;
    • väärtus, millel arvet pole, loob uue arve: partner leitakse välja Customer Email alusel (luuakse puudumisel samamoodi nagu createPartner puhul), luuakse üks rida tasu kohta (Checkout Line Item Summary või Description tekstina, tasu summa käibemaksumääraga sisaldava hinnana väljal invoiceVatRatePercent), väljastamise kuupäevaks määratakse esimese tasu kuupäev ning käibemaksu kohtlemine tuletatakse ettevõtte ja kaardi riigi põhjal. Arve väljastatakse ja kantakse pearaamatusse koheselt ning süsteemi salvestatakse müügitellimus kanaliga stripe ja vastava väärtusega väljal externalRef, et hilisemad impordid seoksid arved loomise asemel;
    • iga grupis olev tasu seotakse seejärel arvega maksetena (luuakse laekumise kanne); iga tagasimakse loob arve alusel väljastatud kreeditarve tagastatud summa ulatuses ja seob tagasimakse sellega. Arvud tagastatakse väljadel invoicesCreated, invoicesLinked, creditNotesCreated ja paymentsMatched; grupid, mida ei õnnestunud töödelda (puuduv kliendi e-posti aadress, segatud valuutad, seotud arve, mis on endiselt mustand või juba täielikult tasutud), loetletakse väljal warnings ja jäetakse töötlemata pangatransaktsioonidena (olekus new). Ärge samas mallis siduge välja Amount täiendavalt pearaamatu kontoga: arvega seotud tasu ei kanta pearaamatusse teist korda, kuid sidumata tasu kantaks.
  • Mallide nimed on ettevõtte siseselt unikaalsed.
  • camt.053 ja pangaliidese mallidel on samad valikud, mida loetakse väljavõttest Stripe'i veergude asemel:
    • Loo puuduvad partnerid: valik createPartner deebetpoole nime real (TxDtls/RltdPties/Dbtr/Nm, voos debtor.name) loob kliendi iga tundmatu sissetuleva raha maksja kohta; kreeditori nime real (TxDtls/RltdPties/Cdtr/Nm, voos creditor.name) luuakse tarnija iga tundmatu väljamineva raha saaja kohta. Partnereid tuvastatakse IBAN-i (salvestatakse tabelisse partner_bank_accounts) ja seejärel täpse nime järgi. Uus partner on ettevõte, kui nimi sisaldab õiguslikku vormi (UAB, MB, SIA, GmbH, Ltd jne), vastasel juhul füüsiline isik. Tulemus tagastatakse väljal customersCreated (faili import) või partnersCreated (voo sünkroonimine).
    • Seo arved viitenumbri järgi: valik invoiceMetaField, mis on seatud selgituse või viite reale (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; voos remittance_information, reference_number), seob iga uue pangarea, mille viide, selgitus või kirjeldus sisaldab avatud väljastatud müügiarve (laekumine) või registreeritud ostuarve (väljamakse) numbrit, ning kannab makse sisse. Kui maksja IBAN on partneri juures salvestatud või maksja nimi ühtib partneri nime või koodiga, peab arve kuuluma sellele partnerile. Tundmatu maksja makse seotakse ainult juhul, kas see katab täpselt arve järelejäänud saldo ja arve number sisaldab seeria eesliidet, tagades, et pelgalt numbrit või summat ei võeta viitena. Järelejäävast saldost suuremat makset ei seota kunagi. Read, mis neid tingimusi ei läbi, jäävad käsitsi sidumiseks olekusse new ja neid loetletakse hoiatustes. Seadistusega advanceInvoices: true tekitab tundmatu partneri sidumata sissetulev makse väljastatud ettemaksuarve (tüüp advance) vastavale summale invoiceVatRatePercent või invoiceItemId määraga ning seob makse sellega; partner peab seejuures olema teada, mistõttu tuleb märkida ka deebetrea valik.
    • Kandereeglid transaktsioonikoodi alusel: lisaks väljadele Ntry/Amt / transaction_amount.amount on väljade loendis reegliread Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (voos: bank_transaction_code=…, credit_debit_indicator=…). Rida kantakse esimese vastava reegli kontole: esmalt kontrollitakse pangatransaktsiooni koodi perekonda, seejärel suunda ja lõpuks üldist summarida. Reeglireasid ei kontrollita faili olemasolu suhtes.
    • Pangatasude partner: valik createPartner reeglirea …=CHRG juures loob panga nimega tarnija (väljavõtte element Stmt/Acct/Svcr/FinInstnId/Nm, ühenduse pank või pearaamatu pangakonto nimi) ja seob iga teenustasu selle partneriga.
    • Pangaliidese mallid valitakse iga voo konto jaoks päringuga bank/feeds/accounts/configure (rakenduses Pank → Ühendused), kus määratakse ka syncSchedule (manual, daily, weekly, monthly): API sünkroniseerib graafikuga kontod ise pärast perioodi möödumist. Malle rakendatakse iga bank/feeds/sync käivitamisel; sünkroonimise vastus annab seejärel teada ka väljad posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched ja warnings.

Parameetri format asemel andke päringule bank/statements/import kaasa templateId: malli tüüp valib parsija ning fail peab sisaldama kõiki mallis loetletud välju - kui mõni neist puudub, lükatakse fail tagasi HTTP koodiga 422 ja tagastatakse puuduvate veergude või elementide nimed. Metaandmete väljad ei pea failis kohustuslikud olema. Pangaliidese mallid kirjeldavad reaalajas toimuvat PSD2 voogu ja neid ei saa kasutada faili importimiseks.

ISO 20022 mall loeb ka MT940 faile: fail, mis algab märkidega {1: või :20: (või mis saadetakse parameetriga "format": "mt940"), parsitakse MT940 formaadis ning malli viidete sobitamise ja kande reegleid rakendatakse selle ridadele. MT940 puhul jäetakse elementide kontroll vahele ning reegleid Ntry/BkTxCd=… ei rakendata kunagi MT940 ridadele, kuna MT940 ei sisalda ISO 20022 pangatransaktsiooni koodi; kasutage selle asemel reegleid Ntry/CdtDbtInd=….

Pangakonto hoiab ühes valuutas. Teises valuutas esitatud väljavõte lükatakse tagasi HTTP koodiga 422 (camt.053 faili puhul, mis sisaldab sama IBAN-i jaoks väljavõtteid mitmes valuutas, imporditakse ainult konto valuutas olev väljavõte); sama kehtib ka päringuga bank/transactions/import saadetud rea kohta, mille valuuta erineb kontol olevast.

Iga liikumine, mis pärineb väljalt, millele on määratud accountCode, kantakse impordi hetkel raamatupidamisse ühe liitkandena: laekumine debiteerib pangakonto pearaamatu kontot ja krediteerib seotud kontot; väljamakse debiteerib seotud kontot ja krediteerib pangakonto pearaamatu kontot. Summad konverteeritakse baasvaluutasse liikumise kuupäeva kursiga. Pangatransaktsioon seotakse (matched) seejärel selle kande-tüüpi dokumendiga (matchedDocumentType = journal_transaction) ning seda ei pakuta enam arvete sidumiseks. Vastus esitab selliste kannete arvu väljal posted. Sidumata väljadest pärit liikumised jäävad olekusse new ja neid seotakse arvete laekumistega nagu varem - näiteks saate siduda välja Fee PSP teenustasude kulukontoga ja jätta välja Amount sidumata, nii et tasud seotakse endiselt müügiarvetega.

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

ISO 20022 camt.053 (avatud panganduse XML)

Leedu pangad (Swedbank, SEB, Luminor, Šiaulių bankas jne) võimaldavad konto väljavõtteid alla laadida ISO 20022 camt.053 XML-failina oma internetipangast – tavaliselt väljavõtete ekspordi või allalaadimise alt vormingus "ISO XML" või "camt.053". Sama vormingut tagastavad ka PSD2 konto teabe API-d.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Fail võib sisaldada mitut väljavõtet; iga väljavõtte IBAN peab vastama pangakonto IBAN-ile (IBAN-ita väljavõtted või ilma IBAN-ita kontod aktsepteeritakse sellisena, nagu nad on).
  • Kirjete viited (AcctSvcrRef/NtryRef, mille puudumisel kasutatakse sisu räsi) muutuvad tunnuseks externalId.
  • Vastus tagastab iga väljavõtte metaandmed: väljavõtte ID, periood, alg- ja lõppsaldod, transaktsioonide arv.
  • Vastaspoole nimi, IBAN ja makse selgitus eraldatakse vastavusse viimiseks iga kirje kohta.

Makseid vastupidises suunas eksporditakse pain.001 formaadis päringu bank/payments/export kaudu.

Revolut Business CSV

Laadige Revolut Business kontolt tehingute väljavõte CSV-failina ja importige see sisseehitatud malliga Revolut Business (templateId: "builtin-revolut"). Igal ettevõttel on see mall olemas ilma seda eraldi loomata: bank/import-templates/list-builtin loetleb selle, bank/import-templates/get tagastab selle ning päringud bank/import-templates/update ja bank/import-templates/delete lükkavad selle tagasi HTTP koodiga 400. Rakenduses on see loetletud esimesena menüüs Pank → Impordimallid; selle avamisel kuvatakse selle seaded ning salvestamisel luuakse teie enda ettevõtte mall, mida saate soovi korral muuta.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "builtin-revolut",
  "content": "Date started (UTC),Date completed (UTC),ID,Type,State,…"
}
  • Imporditakse ainult read, mille State on COMPLETED. Muud read (näiteks PENDING) jäetakse vahele ja loetletakse väljal warnings; need imporditakse hilisema faili impordiga, kui nende olek on muutunud lõplikuks.
  • Iga rida muutub pangatransaktsiooniks, mille kuupäev võetakse väljalt Date completed (UTC), summa väljalt Total amount, valuuta väljalt Payment currency, ID muutub tunnuseks externalId ja Description kirjelduseks.
  • Väljamineva raha vastaspool on Beneficiary name ja Beneficiary IBAN; ilma saajata kaardimakse puhul on saajaks kaupmees väljalt Description. Sissetuleva raha vastaspool on Sender name ja Sender account.
  • Read rühmitatakse konto ja valuuta järgi. International account number peab vastama pangakonto IBAN-ile ning imporditakse ainult pangakonto valuutas olevad read.
  • Iga rea puhul kontrollib importija, et eelmise rea saldo ja Total amount summa võrdub veerus Balance toodud väärtusega, ning märgib kõik read, kus see ei klapi, väljale warnings.
  • Fail peab sisaldama veerge Date completed (UTC), ID, Type, State, Description, Payment currency, Total amount, Reference, Sender name ja Beneficiary name.

Igal impordil sisseehitatud mall:

  • loob kliendi iga tundmatu sissetuleva raha saatja jaoks ja tarnija iga tundmatu saaja või kaardikaupmehe jaoks, nagu on kirjeldatud punktis Loo puuduvad partnerid eespool;

  • seob iga rea, mille Reference või Description sisaldab avatud müügi- või ostuarve numbrit, ning kannab makse sisse vastavalt punktis Seo arved viitenumbris järgi toodud kontrollidele;

  • kannab arvega sidumata read nende Type alusel vastava kandereegli kontole:

    Type Kandereegel Vaikimisi konto Rumeenia kontoplaan Kanne
    FEE bank.fees 6800 627 debiteerib reegli kontot, krediteerib pangakonto pearaamatu kontot; partner: pangakonto järgi nime saanud tarnija
    CARD_PAYMENT bank.cardPayments 6209 628 debiteerib reegli kontot, krediteerib pangakonto pearaamatu kontot, ilma käibemaksuta
    TOPUP bank.topUps 3010 1012 debiteerib pangakonto pearaamatu kontot, krediteerib reegli kontot

    Muud tüüpi read, näiteks TRANSFER, jäävad sidumiseks olekusse new.

Kontosid saate muuta päringuga ledger/posting-rules/update; sisseehitatud mall kasutab uusi kontosid alates järgmisest impordist. Kandereeglit ei saa täielikult välja lülitada: kaardimaksete või laadimiste importimiseks ilma neid raamatupidamisse kandmata looge tüüpi revolut ettevõtte mall ilma reegliridadeta Type=CARD_PAYMENT või Type=TOPUP ning importige selle abil. Sel viisil pearaamatusse kantud kaardimakset ei seotud hiljem registreeritava tarnija arvuga; kandke sisse üks kahest, aga mitte mõlemad.

Tüüpi revolut ettevõtte mall kasutab samu veerge ja saab kanda ridu tüübi alusel reegliridade Type=FEE, Type=CARD_PAYMENT, Type=TRANSFER ja Type=TOPUP kaudu. Importimine parameetriga "format": "revolut-csv" ilma mallita impordib read ilma ühegi eelnimetatud sammuta.

Stripe CSV

Eksprot Stripe'i töölaualt – sobib kumb tahes aruanne:

  • Reports → Balance → Itemized balance change from activity (soovitatav): veerud balance_transaction_id, created_utc, currency, gross, fee, net, reporting_category, description.
  • Payments → Export: veerud 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,…"
}

Looge Stripe'i jaoks eraldi pangakonto (nt nimega "Stripe", pearaamatu konto 2710 või selle oma alamkonto) – Stripe'i saldo käitub nagu pangakonto: maksed laekuvad, teenustasud arvestatakse maha ja väljamaksed kannavad saldo teie päris pangakontole.

Impordi käitumine:

  • Iga saldotehing muutub üheks pangatransaktsiooniks brutobumma ulatuses (externalId = saldotehingu id).
  • Nullist erinev teenustasu (fee) muutub teiseks vastupidise märgiga transaktsiooniks (externalId = <id>:fee, vastaspool "Stripe"), mis võimaldab teenustasusid tuludest eraldi kuluna siduda ja kanda. Tagasimaksetega tagastatud tasud tulevad sisse positiivsete summadena.
  • Väljamakse (Payout) read imporditakse ühe negatiivse transaktsioonina; siduge need oma päris pangakonto väljavõttel oleva vastava sissetuleva tehinguga.
  • Nullsummalised read jäetakse vahele; kuupäev võetakse väljalt created_utc (UTC).
  • Maksete ekspordi read, millega raha ei liikunud, jäetakse vahele: Captured = false (autoriseerimised / viivitatud broneeringud) ning Status on Failed või Canceled.
  • Nullist erinev tagastatud summa (Amount Refunded) muutub kolmandaks negatiivseks transaktsiooniks (externalId = <id>:refund), mille kuupäevaks on Refunded date (UTC) – tänu sellele ei lähe makseridades sisalduvad osalised ja täielikud tagasimaksed kaotsi.

PSP arvelduste vastavusse viitamine (Stripe'i väljamaksete aruanded)

Kogu summana laekunud väljamakse jaotamiseks selle aluseks olevateks tellimusteks, tagasimakseteks, teenustasudeks ja tagasinõueteks (chargeback) kasutage tavalise väljavõtte impordi asemel arvelduste otstpunte. Aktsepteeritakse kahte Stripe'i eksporti (tuvastatakse automaatselt):

  • Reports → Payouts → Payout reconciliation, itemized (aruande tüübid payout_reconciliation.itemized.* või payout_reconciliation.by_id.itemized.*) – täpne, üks rida saldotehingu kohta; eelistatud reaalsetel kontodel.
  • Payments → Export (unified payments) – laengu tasemel eksport; toimib test- ja liivakastirežiimil (sandbox), kus arvelduste vastavusse viitamine pole saadaval. Kinnitatud laengud rühmitatakse väljamakse ID järgi veerus Transfer; kinnitamata / ebaõnnestunud read jäetakse vahele (skippedNotSettled); nullist erinev tagasimakse summa (Amount Refunded) muutub sünteetiliseks tagasimakse reaks laengu väljamaksepaketis – tegemist on ligikaudse lähenemisega, kuna tagasimakse võis tegelikult arvelduda hilisemas väljamakses. Vastavusse viimise viited leitakse laengu ID, PaymentIntent ID, arve numbri (Invoice Number), kliendi viitenumbri (Client Reference ID) ja kõigi … (metadata) veergude (nt tellimuse number metaandmetes) kaudu.

Üks CSV fail võib hõlmata mitut väljamakset. Stripe laadib üksikasjaliku aruande alla üks fail sektsiooni kohta (…_charge_…, …_refund_…, …_fee_…); importige need kõik – juba imporditud väljamakse read liituvad olemasoleva paketiga (millest antakse teada loenduris updated), eeldusel et seda pole veel pearaamatusse kantud, ning paketi kogusummad arvutatakse uuesti.

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

Impordi käitumine:

  • Read rühmitatakse välja automatic_payout_id alusel arvelduspakettideks – üks pakett väljamakse kohta, millel on bruto-, tasu- ja netosummad (ridade net-summade kogusumma = teie panka laekuv summa). Väljamakse korduv import jäetakse vahele (skipped loendur). Veel väljamaksele määratlemata read ja payout read ise jäetakse vahele ja neid loetletakse eraldi.
  • Iga laengu, tagasimakse ja vaidluse rida seotakse automaatselt müügiarvega, kasutades järgmises järjekorras: e-kaubanduse tellimuse externalRef (mis tahes väärtus väljadest order_id, payment_intent_id, source_id, charge_id või mis tahes *_metadata[...] veerg), nendes veergudes esinev arve fullNumber ning tagasimaksete ja vaidluste puhul varem seotud laengu charge_id (samast failist või varasematest importidest).
  • Kontrollige tulemusi päringutega bank/settlements/list / bank/settlements/get; parandage ülejäägid päringuga bank/settlements/match { lineId, invoiceId } (või invoiceId: null seose eemaldamiseks).

Päring POST /v1/bank/settlements/post { id, date?, commissionPercent? } kannab terve paketi pearaamatusse ühe tasakaalus liitkandena ja lahendab seotud arved (paidAmount/paymentStatus, veebikonksud sale_invoice.paid):

  • Debiteerige pangakonto pearaamatu kontot netoväljamakse ulatuses; debiteerige PSP teenustasusid (settlements.fees, vaikimisi 6800) kinnipeetud tasude ja tasuridade osas.
  • Krediteerige nõudeid seotud laengute kaupa; tagasimaksed ja vaidlused pööravad selle ümber. Summa on piiratud iga arve järelejääva saldoga – iga ülejääk maandub hoiatusega vahekontol.
  • Sidumata laengud: kui määratud on commissionPercent, jaotatakse need vahendustasuks (settlements.commissionRevenue, vaikimisi 5001) ja müüja kohustuseks (settlements.sellerPayable, vaikimisi 4499) – see on turuplatsi (marketplace) voog, kus sissenõutud raha kuulub enamasti müüjatele. Ilma selle protsendita pargitakse summad kontole settlements.suspense (vaikimisi 4440, saadud ettemaksud).
  • Väljad platform_earning (Stripe Connecti vahendustasud) kantakse vahendustasude tuludesse; transfer read (väljamaksed seotud müüjatele) vähendavad müüja kohustust.
  • Kõiki nelja kontot saab ettevõttepõhiselt üle kirjutada kandereeglite kaudu (ledger/posting-rules).
  • Rida, mille tasu, teenustasu või tagasimakse imporditi varem Stripe'i maksete ekspordi kaudu mõnele teisele pangakontole (bank/statements/import), ei kanta tasude, nõuete ega vahekonto kuludesse. Selle asemel krediteeritakse selle net-summat selle pangakonto pearaamatu kontole, nii et Stripe'i pangakonto tasub end väljamakse haaval. summary.clearedAmount on sel viisil liigutatud kogusumma; rida, mille summa erineb sellele kontole kantust, tuuakse ära hoiatustes (warnings). Kui raamatupidamisse kandmiseks midagi ei jää, postitatakse pakett tühise journalTransactionId väärtusega.

Päringud bank/settlements/list ja /get tagastavad iga paketi kohta näitajad clearedNet, clearingDifference (väljamakse read miinus teise pangakonto poolt nende eest hoitavad summad; null, kui need klapivad) ja clearingOpenCount (read, millel on erinevus või postitamata liikumine); /get tagastab sama rea kaupa väljadel clearingBankAccountId, clearingBooked, clearingDifference ja clearingUnposted. Ühe laengu tagasimakse ridu võrreldakse koos, kuna maksete eksport hoiab ainult tagastatud kogusummat. Pärast väljamakse pearaamatusse kandmist imporditud Stripe'i maksete eksport jätab selle väljamakse liikumised vahele ja märgib selle hoiatustesse (warnings).

Vahendustasu käibemaks arveldatakse eraldi (väljastage müüjale vahendustasu arve); jaotus eraldab vaid sissenõutud raha.

Väljamaksed teises valuutas

Pearaamatu kanne koostatakse alati ettevõtte baasvaluutas, kuid teises valuutas tehtud väljamakse kantakse sisse automaatselt – käsitsi sisestust pole vaja:

  • Pakett konverteeritakse kande kuupäeva kursiga (date, mille puudumisel kasutatakse väljamakse kuupäeva ja viimasel juhul tänast päeva). Kursiks on ettevõtte enda kurss sellele valuutale (reference/exchange-rates/set), kui see on vähemalt sama ajakohane kui ametlik kurst, vastasel juhul kasutatakse viimast ametlikku kurssi sellel kuupäeval või enne seda. Kui vastaval kuupäeval või varem kurss puudub, ebaõnnestub päring veakoodiga 422 ja viitab päringule reference/exchange-rates/sync.
  • Iga konto konverteeritakse selle paketi kursiga välja arvatud nõuded klientidele (accounts receivable), mis vabastatakse kursiga fxRate, millega iga arve omal ajal väljastati. Nende kahe kursi vahe kantakse realiseeritud kursivahena kontole bank.fxGain (vaikimisi 5803) või bank.fxLoss (vaikimisi 6803), nii et kanne püsib tasakaalus.
  • Vastuse kokkuvõte summary tagastab kasutatud kursi fxRate ja sellest tuleneva kursivahe exchangeDifference ning pakett säilitab kursi, millega see kanti pearaamatusse. Seotud arvet, mille valuuta erineb paketi valuutast, ei lahendata: selle summa suunatakse hoiatusega vahekontole.
  • Alles jääb üks impordipiirang: üksik väljamakse, mille read segavad mitut valuutat, lükatakse tagasi veakoodiga 422, samuti korduv import, mille valuuta erineb selle väljamakse jaoks juba salvestatud paketi omast.

Käsitsi lisamine / kohandatud vood

Kõike muud saab sisse saata tavalise JSON-ina:

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

Tagage korduvate imporditööde idempotentseks muutmiseks igale transaktsioonile unikaalne ja stabiilne externalId.