Nordlet

← Dokumentacija / Vadovai

Banko ir mokėjimų importai

„camt.053“ išrašai, „Stripe“ CSV, mokėjimo paslaugų teikėjų (PSP) atsiskaitymų derinimas ir pasirinktiniai JSON srautai.

Visi importuoti duomenys įrašomi kaip banko operacijos banko sąskaitoje (bank/accounts/create). Operacijos turi externalId; pakartotinai importuoti tą patį failą yra saugu — eilutės, kurių (bankAccountId, externalId) jau egzistuoja, yra praleidžiamos ir parodomos skipped skaitiklyje. Importuotos operacijos gauna pradinį statusą new ir į didžiąją knygą įtraukiamos tik tada, kai yra susiejamos (bank/transactions/match, o kandidatus susiejimui galima rasti per bank/transactions/suggest-matches).

Internetinėje programoje šiuos pačius importus galima rasti skiltyje Bankas → Importuoti failą (failo įkėlimas, šablono pasirinkimas).

Importo šablonai

Importo šablonas įvardija duomenų šaltinį, išvardija laukus, kuriuos tas šaltinis pateikia, ir susieja pinigus nešančius laukus su didžiosios knygos sąskaitomis. Šablonai tvarkomi skiltyje Bankas → Importo šablonai ir per bank/import-templates/create|update|delete|get|list.

POST /v1/bank/import-templates/create
{
  "name": "Stripe mokėjimų eksportas",
  "type": "stripe",
  "fields": [
    { "name": "id" },
    { "name": "Created date (UTC)" },
    { "name": "Amount" },
    { "name": "Fee", "accountCode": "6800" },
    { "name": "Amount Refunded" }
  ],
  "metaFields": ["order_id"]
}
  • type yra vienas iš stripe, iso20022 arba bank_connection.
  • Kiekvienas laukas turi name ir neprivalomą accountCode. Sąskaitą priima tik pinigus nešantys laukai: „Stripe“ Amount, Fee ir Amount Refunded; camt.053 Ntry/Amt; banko ryšio transaction_amount.amount. Sąskaita turi būti sąskaitų plane (sukuriama per ledger/accounts/create).
  • fields galima nenurodyti — tada naudojamas standartinis tipo laukų sąrašas: „Stripe“ Payments → Export failo stulpelių pavadinimai (be 19 Card … stulpelių, kuriuos forma pagal numatymą taip pat palieka nepažymėtus), camt.053 elementai, kuriuos turi kiekvienas išrašas (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt), arba atributai, kuriuos PSD2 banko ryšys grąžina kiekvienai operacijai. Įrašus pridėkite ar pašalinkite pagal savo failą: importas papildomai skaito neprivalomus camt.053 elementus 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 ir TxDtls/AddtlTxInf.
  • „Stripe“ laukas Customer Email gali turėti "createPartner": true. Tada importas kiekvienam failo el. pašto adresui, kurio neturi nė vienas esamas partneris, sukuria pirkėją (fizinio asmens tipo partnerį su pirkėjo žyma): pavadinimas imamas iš Customer Description (tuščią pakeičia el. paštas), adresas — iš Card Address … stulpelių, jei jie yra faile. Esami partneriai atpažįstami pagal el. paštą, neskiriant didžiųjų ir mažųjų raidžių. Atsakyme skaičius pateikiamas lauke customersCreated.
  • metaFields (tik „Stripe“) išvardija metaduomenų raktus, kuriuos turi jūsų mokėjimai. „Stripe“ kiekvieną raktą eksportuoja kaip stulpelį <raktas> (metadata); sąrašas yra laisvos formos ir gali būti ilgas.
  • invoiceMetaField (tik „Stripe“) nurodo vieną iš tų raktų, pavyzdžiui užsakymo numerį, o invoiceVatRatePercent — PVM tarifą pagal jį kuriamoms sąskaitoms. Importo metu kiekviena mokėjimo ir grąžinimo eilutė grupuojama pagal to rakto reikšmę:
    • reikšmė, atitinkanti esamą pardavimo sąskaitą — pardavimo užsakymą, kurio externalRef yra ta reikšmė (ecommerce/orders/create, bet kuris kanalas), arba sąskaitą, kurios fullNumber yra ta reikšmė — susieja grupę su ta sąskaita;
    • reikšmė be sąskaitos ją sukuria: partneris pagal Customer Email (sukuriamas, jei trūksta, kaip su createPartner), po vieną eilutę kiekvienam mokėjimui (Checkout Line Item Summary arba Description kaip tekstas, mokėjimo suma kaip kaina su PVM pagal invoiceVatRatePercent), išrašymo data — pirmojo mokėjimo data, PVM traktavimas pagal įmonę ir kortelės šalį. Sąskaita iš karto išrašoma ir įrašoma į didžiąją knygą, o pardavimo užsakymas su kanalu stripe ir ta reikšme kaip externalRef išsaugomas, kad vėlesni importai susietų, o ne kurtų iš naujo;
    • kiekvienas grupės mokėjimas susiejamas su sąskaita kaip apmokėjimas (įplauka įrašoma į didžiąją knygą); kiekvienas grąžinimas sukuria išrašytą kreditinę sąskaitą grąžintai sumai ir susieja grąžinimą su ja. Skaičiai grąžinami laukuose invoicesCreated, invoicesLinked, creditNotesCreated ir paymentsMatched; neapdorotos grupės (nėra pirkėjo el. pašto, skirtingos valiutos, susieta sąskaita dar juodraštis arba jau apmokėta) išvardijamos warnings ir lieka kaip new banko operacijos. Tame pačiame šablone nepriskirkite Amount didžiosios knygos sąskaitai: su sąskaita susietas mokėjimas antrą kartą neįrašomas, bet nesusietas būtų.
  • Šablonų pavadinimai įmonėje yra unikalūs.

Užklausoje bank/statements/import vietoj format perduokite templateId: šablono tipas parenka apdorojimo būdą, o faile turi būti visi šablone išvardyti laukai — failas be kurio nors iš jų atmetamas su HTTP 422 ir trūkstamų stulpelių ar elementų pavadinimais. Metaduomenų laukų buvimas netikrinamas. Banko ryšio šablonai aprašo tiesioginį PSD2 srautą ir failų importui nenaudojami.

Kiekviena operacija, gauta iš lauko su accountCode, importo metu įrašoma kaip viena didžiosios knygos operacija: įplaukos debetuoja banko sąskaitos DK sąskaitą ir kredituoja susietą sąskaitą; išmokos debetuoja susietą sąskaitą ir kredituoja banko sąskaitos DK sąskaitą. Sumos konvertuojamos į bazinę valiutą operacijos dienos kursu. Banko operacija tampa matched su ta DK operacija (matchedDocumentType = journal_transaction) ir daugiau nesiūloma susieti su sąskaitomis faktūromis. Atsakyme skaičius pateikiamas lauke posted. Operacijos iš nesusietų laukų lieka new ir susiejamos su sąskaitomis faktūromis kaip anksčiau — pavyzdžiui, Fee susiekite su mokėjimo paslaugų mokesčių sąnaudų sąskaita, o Amount palikite nesusietą, kad mokėjimai ir toliau būtų siejami su pardavimo sąskaitomis.

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

ISO 20022 camt.053 (atvirosios bankininkystės XML)

Lietuvos bankai (Swedbank, SEB, Luminor, Šiaulių bankas ir kt.) leidžia atsisiųsti sąskaitų išrašus ISO 20022 camt.053 XML formatu iš savo interneto bankų — dažniausiai išrašų eksporto / atsisiuntimo skiltyje, pasirinkus formatą „ISO XML“ arba „camt.053“. Tokį patį formatą grąžina ir PSD2 sąskaitų informacijos API.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Faile gali būti keli išrašai; kiekvieno išrašo IBAN turi sutapti su banko sąskaitos IBAN (išrašai be IBAN arba sąskaitos, neturinčios nurodyto IBAN, priimami tokie, kokie yra).
  • Įrašų nuorodos (AcctSvcrRef/NtryRef, arba turinio maiša, jei nuorodų nėra) tampa externalId.
  • Atsakyme pateikiami kiekvieno išrašo metaduomenys: išrašo ID, laikotarpis, pradinis / galutinis likutis, operacijų skaičius.
  • Kontragento pavadinimas, IBAN ir mokėjimo paskirtis išskiriami iš kiekvieno įrašo ir naudojami susiejimui.

Mokėjimai į kitą pusę eksportuojami pain.001 formatu per bank/payments/export.

Stripe CSV

Eksportuokite iš „Stripe“ valdymo skydelio — tinka bet kuri iš ataskaitų:

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

Sukurkite atskirą banko sąskaitą sistemai „Stripe“ (pvz., pavadinimas „Stripe“, didžiosios knygos sąskaita 2710 ar kita atskira subsąskaita) — „Stripe“ likutis veikia kaip banko sąskaita: įplaukos kaupiasi, mokesčiai atskaitomi, o išmokėjimai perveda likutį į jūsų tikrąjį banką.

Importavimo elgsena:

  • Kiekviena likučio operacija tampa viena banko operacija su bruto (gross) suma (externalId = likučio operacijos ID).
  • Nelygus nuliui mokestis (fee) tampa antra operacija su priešingu ženklu (externalId = <id>:fee, kontragentas „Stripe“) — taip mokesčius galima susieti / įtraukti į apskaitą kaip sąnaudas atskirai nuo pajamų. Grąžinamų pinigų metu sugrįžę mokesčiai pateikiami kaip teigiamos sumos.
  • Išmokėjimų (payout) eilutės importuojamos kaip atskiros neigiamos operacijos; susiekite jas su atitinkama įeinančia operacija savo tikrojo banko išraše.
  • Nulinės sumos eilutės yra praleidžiamos; data imama iš created_utc (UTC laiku).
  • Mokėjimų eksporto eilutės, kuriose nebuvo pinigų judėjimo, yra praleidžiamos: Captured = false (autorizacijos / atidėti nuskaitymai) ir Status reikšmė Failed / Canceled.
  • Nelygi nuliui grąžinta suma (Amount Refunded) tampa trečia, neigiama operacija (externalId = <id>:refund), kurios data yra Refunded date (UTC) — taigi mokėjimo eilutėse esantys daliniai ir visiški grąžinimai neprarandami.

Mokėjimo paslaugų teikėjų (PSP) atsiskaitymų derinimas („Stripe“ išmokėjimų ataskaitos)

Norėdami išskaidyti vienkartinio išmokėjimo sumą į atitinkamus užsakymus, grąžinimus, mokesčius ir atšauktus mokėjimus (chargebacks), naudokite atsiskaitymų galinius punktus (endpoints) užuot paprastai importavę išrašą. Priimami du „Stripe“ eksporto formatai (aptinkami automatiškai):

  • Reports → Payouts → Payout reconciliation, itemized (ataskaitų tipai payout_reconciliation.itemized.* arba payout_reconciliation.by_id.itemized.*) — tikslus, viena eilutė vienai likučio operacijai; rekomenduojamas dirbant su veikiančiomis paskyromis (live accounts).
  • Payments → Export (unified payments) — nuskaitymų (charge) lygio eksportas; veikia testavimo (sandbox) režimu, kai išmokėjimų derinimo ataskaitos (payout reconciliation) nėra. Įvykdyti nuskaitymai grupuojami pagal išmokėjimo ID Transfer stulpelyje; neįvykdytos / nepavykusios eilutės praleidžiamos (skippedNotSettled); nelygi nuliui reikšmė stulpelyje Amount Refunded tampa sintetine grąžinimo eilute to nuskaitymo išmokėjimų partijoje — tai tik apytikslis duomenų atvaizdavimas, nes grąžinimas iš tikrųjų galėjo būti apdorotas vėlesniame išmokėjime. Susiejimo nuorodos imamos iš nuskaitymo ID, PaymentIntent ID, Invoice Number, Client Reference ID bei visų … (metadata) stulpelių (pvz., užsakymo numerio metaduomenyse).

Vienas CSV failas gali apimti kelis išmokėjimus. Iš „Stripe“ detali ataskaita atsiunčiama po vieną failą kiekvienai sekcijai (…_charge_…, …_refund_…, …_fee_…); importuokite juos visus — eilutės, priklausančios jau importuotam išmokėjimui, susilieja su esama partija (rodoma updated skaitiklyje), jeigu ji dar neįtraukta į didžiąją knygą, o partijos bendrosios sumos perskaičiuojamos.

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

Importavimo elgsena:

  • Eilutės sugrupuojamos pagal automatic_payout_id į atsiskaitymų partijas — po vieną partiją kiekvienam išmokėjimui su priskaičiuotomis bruto / mokesčių / neto sumomis (eilutės net suma = suma, kuri patenka į jūsų banką). Pakartotinis to paties išmokėjimo importavimas praleidžiamas (skipped skaitiklis). Eilutės, dar nepriskirtos išmokėjimui, bei pačios payout eilutės yra praleidžiamos ir skaičiuojamos atskirai.
  • Kiekviena nuskaitymo, grąžinimo ar ginčo eilutė yra automatiškai susiejama su pardavimo sąskaita faktūra, eilės tvarka naudojant: el. prekybos užsakymo externalRef (bet kokia reikšmė iš order_id, payment_intent_id, source_id, charge_id arba bet kurio *_metadata[...] stulpelio), tuose stulpeliuose esantį sąskaitos faktūros fullNumber, o grąžinimams ir atšauktiems mokėjimams — anksčiau susieto nuskaitymo (tame pačiame faile arba ankstesniuose importuose) charge_id.
  • Peržiūrėkite atsiskaitymus su bank/settlements/list / bank/settlements/get; nesusietus likučius pataisykite naudodami bank/settlements/match { lineId, invoiceId } (arba naudokite invoiceId: null, kad atsietumėte).

POST /v1/bank/settlements/post { id, date?, commissionPercent? } įtraukia į apskaitą visą partiją kaip vieną subalansuotą dvejybinį įrašą ir padengia susietas sąskaitas faktūras (paidAmount/paymentStatus, sale_invoice.paid iškviečiamieji adresai („webhooks“)):

  • Debetuojama banko sąskaita didžiojoje knygoje neto išmokėjimo sumai; debetuojamos PSP mokesčių sąnaudos (settlements.fees, numatytoji sąskaita 6800) už išskaitytus mokesčius ir mokesčių eilutes.
  • Kredituojamos pirkėjų skolos (accounts receivable) už kiekvieną susietą nuskaitymą; grąžinimai ir atšaukti mokėjimai šį įrašą stornuoja. Dengimas ribojamas pagal kiekvienos sąskaitos faktūros likusią nesumokėtą sumą — bet koks perviršis su įspėjimu nukreipiamas į tarpinę sąskaitą (suspense account).
  • Nesusieti nuskaitymai: nustačius commissionPercent, jie išskaidomi į komisinių pajamas (settlements.commissionRevenue, numatytoji sąskaita 5001) ir įsipareigojimą pardavėjui (settlements.sellerPayable, numatytoji 4499) — tai prekyvietės (marketplace) modelis, kur surinkti pinigai dažniausiai priklauso pardavėjams. Nenurodžius šio procento, sumos perkeliamos į tarpinę settlements.suspense sąskaitą (numatytoji 4440, gauti avansai).
  • platform_earning eilutės („Stripe Connect“ taikomieji mokesčiai) įtraukiamos į komisinių pajamas; transfer eilutės (išmokos prijungtiems pardavėjams) mažina įsipareigojimą pardavėjui.
  • Visas keturias sąskaitas galima perrašyti kiekvienai įmonei atskirai, naudojant registravimo taisykles (ledger/posting-rules).

PVM nuo pačių komisinių sąskaitose faktūrose išrašomas atskirai (išrašykite pardavėjui komisinių sąskaitą faktūrą); skaidant tik paskirstomi surinkti pinigai. Atsiskaitymai registruojami įmonės bazine valiuta — išmokėjimai užsienio valiuta šiuo metu turi būti įtraukiami rankiniu būdu.

Rankiniai / pasirinktiniai duomenų srautai

Bet kokius kitus duomenis galima persiųsti kaip paprastą JSON formato struktūrą:

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

Kiekvienai operacijai priskirkite pastovų externalId, kad pakartotiniai importai išliktų idempotentiniai.