Nordlet

← Dokumenti / Gwidi

Importazzjonijiet bankarji u ta' pagamenti

Dikjarazzjonijiet camt.053, Stripe CSV, rikonċiljazzjoni ta' saldu ta' PSP u għalf (feeds) JSON personalizzat.

L-importazzjonijiet kollha jitniżżlu bħala tranżazzjonijiet bankarji f'kont bankarju (bank/accounts/create). It-tranżazzjonijiet ikollhom externalId; l-importazzjoni mill-ġdid tal-istess fajl hija sigura - ringieli li l-kombinazzjoni tagħhom (bankAccountId, externalId) diġà eżisti jinqabżu u jiġu rrappurtati fil-kontatur skipped. It-tranżazzjonijiet importati jibdew bl-istatus new u jiġu mibgħuta (posted) fil-ledger biss meta jiġu mqabbla (bank/transactions/match, flimkien ma' bank/transactions/suggest-matches għall-kandidati).

L-app web tesponi l-istess importazzjonijiet taħt Bank → Importa fajl (tlugħ tal-fajl, selettur tat-templates).

Tqabbil żbaljat jista' jiġi annullat permezz ta' bank/transactions/unmatch (Unmatch taħt Bank → Tranżazzjonijiet). Trattamenti li diġà ġew ippostjati qatt ma jiġu editjati jew imħassra: pagament imqabbel ma' fattura, jew linja li template tal-importazzjoni jkun ippostja f'kont, tirċievi tranżazzjoni ta' ġurnal b'lura (reversing journal transaction) b'kull entratura fuq in-naħa opposta, bid-data date (default: illum, u qatt qabel il-posting oriġinali). L-ammont imħallas tal-fattura u l-istatus tal-pagament jerġgħu lura bl-ammont ta' dik il-linja bankarja. Linja marbuta ma' saldu ta' fornitur ta' pagamenti (PSP) tiġi biss skonnettjata, minħabba li l-posting tas-saldu jappartjeni l-lott (batch). Il-linja terġa' lura għall-istatus new u tista' terġa' titqabbel. Id-data tal-qlib trid taqa' f'perjodu contabili miftuħ.

Templates tal-importazzjoni

Template tal-importazzjoni jsemmi s-sors tad-dejta, elenka l-kampijiet li s-sors iwassal, u jimmappja l-kampijiet li jġorru l-flus għall-kontijiet tal-ledger. It-templates huma mmaniġġjati taħt Bank → Templates tal-importazzjoni u permezz ta' 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"]
}
  • It-tip type huwa wieħed minn stripe, iso20022, bank_connection jew revolut.
  • Kull kamp għandu name u accountCode fakultattiv. Il-kampijiet li jġorru l-flus biss jaċċettaw kont: Amount, Fee u Amount Refunded ta' Stripe; Ntry/Amt ta' camt.053; transaction_amount.amount tal-għalf bankarju. Il-kont irid jeżisti fil-pjan tal-kontijiet (oħloqu b'ledger/accounts/create).
  • Il-kampijiet fields jistgħu jitħallew barra; f'dak il-każ jinżel awtomatikament għal-lista standard tal-kampijiet tat-tip: l-ismijiet tal-kolonni tal-fajl Payments → Export ta' Stripe (mingħajr id-19-il kolonna Card …, li l-formola wkoll tħalli mhux immarkati awtomatikament), l-elementi camt.053 li kull dikjarazzjoni ġġorr (Stmt/Id, Stmt/Acct/Id/IBAN, Stmt/Bal/…, Ntry/Amt, Ntry/CdtDbtInd, Ntry/Sts, Ntry/BookgDt), jew l-attributi li għalf bankarju PSD2 jirritorna għal kull tranżazzjoni. Żied jew neħħi entrati biex jaqblu mal-fajl tiegħek: l-importatur jaqra wkoll l-elementi camt.053 fakultattivi 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 u TxDtls/AddtlTxInf.
  • Kamp Customer Email ta' Stripe jista' jkollu "createPartner": true. L-importazzjoni mbagħad oħloq klijent (sieħeb tat-tip persuna, immarkat biex ikun klijent) għal kull email fil-fajl li l-ebda sieħeb eżistenti m'għandu, billi tuża Customer Description bħala l-isem (l-email meta jkun vojt) u l-kolonni Card Address … bħala l-indirizz meta l-fajl ikun fihom. Imsieħba eżistenti jitqabblu bl-email, irrispettivament mill-kapietaliżmu tal-ittri (case-insensitively). Ir-rispons jirrapporta l-għadd f'customersCreated.
  • metaFields (għal Stripe biss) jelenka ċ-ċwievet tal-metadata li l-ħlasijiet tiegħek iġorru. Stripe jesporta kull ċwievet bħala kolonna <key> (metadata); il-lista hija libera u tista' tkun twila.
  • invoiceItemId (għal Stripe biss, fakultattiv) huwa oġġett tal-katalgu. Meta jkun issettjat, kull linja ta' fattura u nota ta' kreditu li toħloq l-importazzjoni tirreferi għal dak l-oġġett (il-posting tiegħu u, meta invoiceVatRatePercent ikun vojt, ir-rata tal-VAT tiegħu); it-test tal-linja xorta jibqa' ġej mill-ħlas.
  • companyMetaField (għal Stripe biss) isemmi waħda minn dawk iċ-ċwievet bħala l-bandiera tal-kumpanija. Meta ħlas ikollu true, 1, yes, company, business jew b2b f'dik il-kolonna, il-klijent maħluq għalih ikun sieħeb tat-tip kumpanija minflok persuna.
  • invoiceMetaField (għal Stripe biss) isemmi waħda minn dawk iċ-ċwievet, pereżempju numru ta' ordni, u invoiceVatRatePercent ir-rata tal-VAT għall-fatturi maħluqa minnha. Mal-importazzjoni, kull ringiela ta' ħlas u rimborż tiġi miġbura skont il-valur ta' dik iċ-ċwievet:
    • valur li jaqbel ma' fattura ta' bejgħ eżistenti - ordni ta' bejgħ li l-externalRef tagħha huwa dak il-valur (ecommerce/orders/create, kwalunkwe kanal) jew fattura li l-fullNumber tagħha huwa dak il-valur - jorbot il-grupp ma' dik il-fattura;
    • valur mingħajr fattura joħloq waħda: sieħeb mill-Customer Email (maħluq meta jkun nieqes, bħal għal createPartner), linja waħda għal kull ħlas (Checkout Line Item Summary jew Description bħala t-test, l-ammont tal-ħlas bħala prezz inkluż il-VAT f'invoiceVatRatePercent), data tal-ħruġ = l-ewwel data tal-ħlas, trattament tal-VAT mill-kumpanija u l-pajjiż tal-kard. Il-fattura tinħareġ u tiġi ppostjata f'daqqa, u ordni ta' bejgħ bil-kanal stripe u dak il-valur bħala externalRef tiġi rreġistrata sabiex importazzjonijiet futuri jorbtu minflok ma joħolqu;
    • kull ħlas fil-grupp imbagħad jitqabbel mal-fattura bħala pagament (bl-ippostjar tad-dħul); kull rimborż joħloq nota ta' kreditu maħruġa kontra l-fattura għall-ammont rimborżat u jqabbel ir-rimborż magħha. L-għadd jirritorna bħala invoicesCreated, invoicesLinked, creditNotesCreated u paymentsMatched; gruppi li ma setgħux jiġu pproċessati (l-ebda email tal-klijent, muniti mħallta, fattura marbuta li għadha abbozz jew diġà mħallsa kollha) huma elenkati f'warnings u jitħallew bħala tranżazzjonijiet bankarji new. M'għandekx timmappja wkoll Amount f'kont tal-ledger fl-istess template: ħlas imqabbel ma' fattura ma jiġix ippostjat darba oħra, iżda wieħed li ma jkunx imqabbel jiġi.
  • L-ismijiet tat-templates huma uniċi għal kull kumpanija.
  • It-templates ta' camt.053 u tal-konnessjoni bankarja jġorru l-istess għażliet, moqgħija mid-dikjarazzjoni minflok mill-kolonni ta' Stripe:
    • Oħloq imsieħba neqsin: createPartner fuq ir-ringiela tal-isem tad-debitur (TxDtls/RltdPties/Dbtr/Nm, l-għalf debtor.name) joħloq klijent għal kull min ikun qed iħallas u mhux magħruf għal flus li dħalin; fuq ir-ringiela tal-isem tal-kreditur (TxDtls/RltdPties/Cdtr/Nm, l-għalf creditor.name) fornitur għal kull min qed jirċievi u mhux magħruf għal flus li huma ħerġin. L-imsieħba jiġu rikonoxxuti bl-IBAN (maħżun f'partner_bank_accounts), imbagħad bl-isem eżatt; sieħeb ġdid ikun kumpanija meta l-isem ikollok forma legali (UAB, MB, SIA, GmbH, Ltd, …), inkella persuna. L-għadd jirritorna bħala customersCreated (importazzjoni ta' fajl) jew partnersCreated (sinkronizzazzjoni tal-għalf).
    • Orbot fatturi b'referenza: invoiceMetaField issettjat għal ringiela ta' rimessa jew referenza (TxDtls/RmtInf/Ustrd, TxDtls/RmtInf/Strd/CdtrRefInf/Ref, TxDtls/Refs/EndToEndId; l-għalf remittance_information, reference_number) jqabbel kull linja bankarja ġdida li r-referenza, ir-rimessa jew id-deskrizzjoni tagħha fiha n-numru ta' fattura miftuħa maħruġa ta' bejgħ (flus ġewwa) jew fattura tax-xiri reġistrata (flus barra), u jippostja l-pagament. Meta l-IBAN ta' min qed iħallas ikun salvat fuq sieħeb, jew l-isem ta' min qed iħallas ikun ugwali għall-isem jew il-kodiċi ta' sieħeb, il-fattura trid tappartjeni lil dak is-sieħeb. Pagament minn min qed iħallas u li mhux magħruf jiġi marbut biss meta jkun ugwali għall-bilanċ li fadal tal-fattura u n-numru tal-fattura jkollu l-prefiss tas-serje tiegħu, sabiex numru vojt bħal ammont qatt ma jittieħed bħala referenza. Pagament akbar mill-bilanċ li fadal qatt ma jiġi marbut. Linji li jfallu dawn il-verifiki jibqgħu ġodda għal tqabbil manwali u huma elenkati fit-twissijiet (warnings). B'advanceInvoices: true, pagament dħuli mhux imqabbel minn sieħeb magħruf joħloq fattura ta' avvanz maħruġa (tip advance) għall-ammont fir-rata ta' invoiceVatRatePercent jew l-oġġett invoiceItemId u jqabbel il-pagament magħha; is-sieħeb irid ikun magħruf, għalhekk immarka r-ringiela tad-debitur ukoll.
    • Regoli tal-posting skont il-kodiċi tat-tranżazzjoni: minbarra Ntry/Amt / transaction_amount.amount, il-lista tal-kampijiet għandha ringieli ta' regoli Ntry/BkTxCd=CHRG, =INTR, =TAXE, Ntry/CdtDbtInd=DBIT, =CRDT (l-għalf: bank_transaction_code=…, credit_debit_indicator=…). Linja tiġi ppostjata fil-kont tal-ewwel regla li taqbel magħha: il-familja tal-kodiċi tat-tranżazzjoni bankarja tagħha, imbagħad id-direzzjoni tagħha, imbagħad ir-ringiela tal-ammont sempliċi. Ir-ringieli tar-regoli ma jiġux iċċekkjati mal-fajl.
    • Sierħeb tal-ispejjeż bankarji: createPartner fuq ir-ringiela tar-regola …=CHRG joħloq fornitur imsemmi wara l-bank (id-dikjarazzjoni Stmt/Acct/Svcr/FinInstnId/Nm, jew il-bank tal-konnessjoni, jew l-isem tal-kont bankarju tal-ledger) u jirreġistra kull spejjeż ma' dak is-sieħeb.
    • It-templates tal-konnessjoni bankarja huma magħżula għal kull kont tal-għalf permezz ta' bank/feeds/accounts/configure (Bank → Konnessjonijiet fl-app), li jissettja wkoll syncSchedule (manual, daily, weekly, monthly): l-API tissinkronizza l-kontijiet bi skeda waħedha ladarba l-perjodu tagħhom ikun għadda. It-templates huma applikati f'kull bank/feeds/sync; ir-rispons tas-sinkronizzazzjoni mbagħad jirrapporta wkoll posted, partnersCreated, invoicesLinked, invoicesCreated, paymentsMatched u warnings.

Għaddi templateId lil bank/statements/import minflok format: it-tip tat-template jagħżel il-parser, u l-fajl irid ikun fih kull kamp elenkat fit-template - fajl li jkun nieqes xi wieħed minnhom jiġi miċħud b'HTTP 422 u bl-ismijiet tal-kolonni jew l-elementi nieqsa. Il-kampijiet tal-metadata mhumiex meħtieġa li jkunu preżenti. It-templates tal-konnessjoni bankarja jiddeskrivu għalf PSD2 ħaj u ma jistgħux jintużaw għall-importazzjoni tal-fajls.

Template ISO 20022 jaqra wkoll fajls MT940: fajl li jibda b'{1: jew :20: (jew jintbagħat b'"format": "mt940") jiġi analizzat bħala MT940 u r-regoli tat-tqabbil tar-referenzi u l-posting tat-template jiġu applikati għal-linji tiegħu. Il-kontroll tal-elementi jinqabeż għal MT940, u r-regoli Ntry/BkTxCd=… qatt ma japplikaw għal linji MT940 minħabba li l-MT940 ma jġorr l-ebda kodiċi tat-tranżazzjoni bankarja ISO 20022; uża r-regoli Ntry/CdtDbtInd=… minflok.

Kont bankarju jżomm munita waħda. Dikjarazzjoni f'munita oħra tiġi miċħuda b'HTTP 422 (f'fajl camt.053 b'dikjarazzjonijiet f'diversi muniti għall-istess IBAN, id-dikjarazzjoni fil-munita tal-kont biss tiġi importata), u hekk ukoll linja mibgħuta lil bank/transactions/import b'currency li ma tkunx dik tal-kont.

Kull moviment prodott minn kamp li jkollu accountCode jiġi ppostjat fil-ħin tal-importazzjoni bħala tranżazzjoni ta' ġurnal waħda: flus ġewwa jiddebitaw il-kont tal-ledger tal-kont bankarju u jikkreditaw il-kont immappjat; flus barra jiddebitaw il-kont immappjat u jikkreditaw il-kont tal-ledger tal-kont bankarju. L-ammonti jiġu konvertiti għall-munita bażi fid-data tal-moviment. It-tranżazzjoni bankarja mbagħad tiġi mqabbla (matched) ma' dik it-tranżazzjoni ta' ġurnal (matchedDocumentType = journal_transaction) u ma tibqgħux tiġi offruta għat-tqabbil tal-fatturi. Ir-rispons jirrapporta l-għadd f'posted. Movimenti minn kampijiet mhux immappjati jibqgħu new u jitqabblu mal-fatturi bħal qabel - pereżempju immappja Fee mal-kont tal-ispejjeż tal-miżati tal-PSP u ħalli Amount mhux immappjat sabiex il-ħlasijiet xorta jitqabblu mal-fatturi tal-bejgħ.

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

ISO 20022 camt.053 (XML tal-banking miftuħ)

Il-banek Litwani (Swedbank, SEB, Luminor, Šiaulių bankas, …) jippermettulek tniżżel id-dikjarazzjonijiet tal-kontijiet bħala ISO 20022 camt.053 XML mill-internet banking tagħhom - normalment taħt l-esportazzjoni/tniżżil tad-dikjarazzjonijiet, bil-format "ISO XML" jew "camt.053". L-istess format jiġi rritornat mill-APIs tal-informazzjoni tal-kontijiet PSD2.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "format": "camt053",
  "content": "<?xml version=\"1.0\"…>…"
}
  • Fajl jista' jkun fih diversi dikjarazzjonijiet; l-IBAN ta' kull dikjarazzjoni irid jaqbel mal-IBAN tal-kont bankarju (dikjarazzjonijiet mingħajr IBAN, jew kontijiet mingħajr wieħed, jiġu aċċettati kif inhuma).
  • Ir-referenzi tal-entrati (AcctSvcrRef/NtryRef, li jaqgħu lura għal hash tal-kontenut) isiru externalId.
  • Ir-rispons jirripeti l-metadata għal kull dikjarazzjoni: l-id tad-dikjarazzjoni, il-perjodu, il-bilanċi tal-ftuħ/għeluq, l-għadd tat-tranżazzjonijiet.
  • L-isem tal-kontroparti, l-IBAN u l-iskop tal-pagament jiġu estratti għal kull entrati għat-tqabbil.

Pagamenti fid-direzzjoni l-oħra jiġu esportati bħala pain.001 permezz ta' bank/payments/export.

Revolut Business CSV

Niżżel id-dikjarazzjoni tat-tranżazzjonijiet ta' kont ta' Revolut Business bħala CSV u importaha bit-template integrat Revolut Business (templateId: "builtin-revolut"). Kull kumpanija għandha dan it-template mingħajr ma jkollha għalfejn toħloqu: bank/import-templates/list-builtin elenkah, bank/import-templates/get jirritornah, u bank/import-templates/update u bank/import-templates/delete jiċħduh b'HTTP 400. Fl-app huwa elenkat l-ewwel taħt Bank → Templates tal-importazzjoni; jekk tiftaħu juri l-issettjar tiegħu, u jekk issalvaw toħloq template tal-kumpanija tiegħek stess li tista' tibdel.

POST /v1/bank/statements/import
{
  "bankAccountId": "…",
  "templateId": "builtin-revolut",
  "content": "Date started (UTC),Date completed (UTC),ID,Type,State,…"
}
  • Ringieli bl-istatus State = COMPLETED biss jiġu importati. Ringieli oħra (pereżempju PENDING) jitħallew barra u jingħaddu fit-twissijiet (warnings); dawn jiġu importati b'importazzjoni aktar tard ta' fajl li fih ikunu tlestew.
  • Kull ringiela ssir tranżazzjoni bankarja bid-data minn Date completed (UTC), l-ammont minn Total amount, il-munita minn Payment currency, ID bħala externalId u Description bħala d-deskrizzjoni.
  • Il-kontroparti għal flus li huma ħerġin hija Beneficiary name u Beneficiary IBAN; għal pagament b'kard mingħajr benefiċjarju, in-negozjant f'Description. Il-kontroparti għal flus li huma dħulin hija Sender name u Sender account.
  • Ir-ringieli huma miġbura skont il-kont u l-munita. International account number irid jaqbel mal-IBAN tal-kont bankarju, u ringieli fil-munita tal-kont bankarju biss jiġu importati.
  • Għal kull ringiela l-importatur jiċċekkja li l-bilanċ tar-ringiela preċedenti flimkien ma' Total amount ikun ugwali għal Balance, u elenka kull ringiela fejn dan ma jkunx il-każ fit-twissijiet (warnings).
  • Il-fajl irid ikun fih il-kolonni Date completed (UTC), ID, Type, State, Description, Payment currency, Total amount, Reference, Sender name u Beneficiary name.

F'kull importazzjoni t-template integrat:

  • joħloq klijent għal kull mittent mhux magħruf ta' flus li huma dħulin, u fornitur għal kull benefiċjarju jew negozjant tal-kard mhux magħruf ta' flus li huma ħerġin, kif deskritt taħt Oħloq imsieħba neqsin hawn fuq;

  • jqabbel kull ringiela li r-referenza Reference jew id-deskrizzjoni Description tagħha fiha n-numru ta' fattura miftuħa ta' bejgħ jew xiri, u jippostja l-pagament, bil-verifiki ta' Orbot fatturi b'referenza hawn fuq;

  • jippostja r-ringieli li l-ebda fattura ma qablet magħhom skont it-tip tagħhom Type, fil-kont ta' regola tal-posting:

    Type Regola tal-posting Kont implicitu (Default) Pjan Rumen Posting
    FEE bank.fees 6800 627 iddebita l-kont tar-regola, ikkredita l-kont tal-ledger tal-kont bankarju; sieħeb: fornitur imsemmi wara l-kont bankarju
    CARD_PAYMENT bank.cardPayments 6209 628 iddebita l-kont tar-regola, ikkredita l-kont tal-ledger tal-kont bankarju, mingħajr VAT
    TOPUP bank.topUps 3010 1012 iddebita l-kont tal-ledger tal-kont bankarju, ikkredita l-kont tar-regola

    Ringieli ta' tipi oħra, bħal TRANSFER, jibqgħu new għat-tqabbil.

Ibdel il-kontijiet permezz ta' ledger/posting-rules/update; it-template integrat juża l-kontijiet il-ġodda mill-importazzjoni li jmiss. Regola tal-posting ma tistax tintefa: biex timporta pagamenti b'kard jew top-ups mingħajr ma tppostjahom, oħloq template tal-kumpanija tat-tip revolut mingħajr ir-ringiela Type=CARD_PAYMENT jew Type=TOPUP u importa biha. Pagament b'kard ippostjat b'dan il-mod ma jitqabbel ma' l-ebda fattura tal-fornitur meta dik il-fattura tiġi rreġistrata aktar tard; ippostja waħda mit-tnejn, mhux it-tnejn.

Template tal-kumpanija tat-tip revolut juża l-istess kolonni u jista' jippostja ringieli skont it-tip bir-ringieli tar-regoli Type=FEE, Type=CARD_PAYMENT, Type=TRANSFER u Type=TOPUP. L-importazzjoni b'"format": "revolut-csv" u mingħajr template timporta r-ringieli mingħajr l-ebda wieħed minn dawn il-passi.

Stripe CSV

Esporta mid-dashboard ta' Stripe - kwalunkwe rapport jaħdem:

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

Oħloq kont bankarju ddedikat għal Stripe (eż. bl-isem "Stripe", kont tal-GL 2710 jew is-subkont tiegħu stess) - il-bilanċ ta' Stripe iġib ruħu bħala kont bankarju: il-ħlasijiet jidħlu, il-miżati jitnaqqsu, il-payouts jittrasferixxu l-bilanċ lejn il-kont bankarju reali tiegħek.

Imġiba tal-importazzjoni:

  • Kull tranżazzjoni tal-bilanċ issir tranżazzjoni bankarja waħda għall-ammont gross (externalId = l-id tat-tranżazzjoni tal-bilanċ).
  • Miżata (fee) li ma tkunx żerijiet issir it-tieni tranżazzjoni bis-sinjal oppost (externalId = <id>:fee, kontroparti "Stripe") - sabiex il-miżati jkunu jistgħu jitqabblu/jiġu ppostjati bħala spejjeż separatament mid-dħul. Miżati rritornati fuq rimborżi jidħolu bħala ammonti pożittivi.
  • Ringieli ta' Payout jiġu importati b'tranżazzjonijiet negattivi singoli; qabbelhom mat-tranżazzjoni dħulja korrispondenti fid-dikjarazzjoni tal-kont bankarju reali tiegħek.
  • Ringieli b'ammont ta' żero jinqabżu; id-data tittieħed minn created_utc (UTC).
  • Ringieli tal-esportazzjoni tal-pagamenti li ma mċaqalqu l-ebda flus jinqabżu: Captured = false (awtorizzazzjonijiet/qbid ittardjat) u Status Failed/Canceled.
  • Amount Refunded li ma jkunx żero isir it-tielet tranżazzjoni negattiva (externalId = <id>:refund) bid-data Refunded date (UTC) - sabiex rimborżi parzjali u sħaħ inkorporati fil-linji tal-pagament ma jintilfux.

Rikonċiljazzjoni ta' saldu ta' PSP (rapporti ta' payouts ta' Stripe)

Għat-tqassim ta' payout f'somma waħda fl-ordnijiet sottostanti tiegħu, rimborżi, miżati u chargebacks, uża l-endpoints tas-saldu minflok l-importazzjoni tad-dikjarazzjoni sempliċi. Żewġ esportazzjonijiet ta' Stripe huma aċċettati (skoperti awtomatikament):

  • Reports → Payouts → Payout reconciliation, itemized (tipi ta' rapport payout_reconciliation.itemized.* jew payout_reconciliation.by_id.itemized.*) - eżatti, ringiela waħda għal kull tranżazzjoni tal-bilanċ; preferuti fuq kontijiet ħajjin.
  • Payments → Export (unified payments) - l-esportazzjoni fil-livell tal-ħlas; taħdem fil-modalità tat-test/sandbox fejn ir-rikonċiljazzjoni tal-payout mhijiex disponibbli. Ħlasijiet maqbudin huma miġbura bl-id tal-payout fil-kolonna Transfer; ringieli mhux maqbudin/falluti jinqabżu (skippedNotSettled); Amount Refunded li ma jkunx żero isir linja ta' rimborż sintetika fil-lott tal-payout tal-ħlas - approssimazzjoni, peress li r-rimborż jista' fil-verità jkun issettja f'payout aktar tard. Ir-referenzi tat-tqabbil jiġu mill-id tal-ħlas, PaymentIntent ID, Invoice Number, Client Reference ID u kull kolonna … (metadata) (eż. numru tal-ordni fil-metadata).

Fajl CSV wieħed jista' jkopri ħafna payouts. Stripe iniżżel ir-rapport dettaljat fajl wieħed għal kull taqsima (…_charge_…, …_refund_…, …_fee_…); importahom kollha - ringieli għal payout li diġà ġie importat jingħaqdu fil-lott eżistenti (irrappurtati fil-kontatur updated) sakemm ma jkunx diġà ġie ppostjat, u t-totals tal-lott jiġu kkalkulati mill-ġdid.

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

Imġiba tal-importazzjoni:

  • Ir-ringieli huma miġbura bi automatic_payout_id f'lottijiet ta' saldu - lott wieħed għal kull payout, b'totals gross/miżata/nettor (is-somma tan-nettor tar-ringiela net = l-ammont li jolqot il-bank tiegħek). L-importazzjoni mill-ġdid ta' payout tinqabeż (kontatur skipped). Ringieli li għadhom ma ġewx assenjati lil payout u r-ringieli payout infushom jinqabżu u jingħaddu separatament.
  • Kull ringiela ta' ħlas/rimborż/disputa tiġi mqabbla awtomatikament ma' fattura ta' bejgħ billi tuża, fl-ordni: l-externalRef ta' ordni ta' kummerċ elettroniku (kwalunkwe valur minn order_id, payment_intent_id, source_id, charge_id jew kwalunkwe kolonna *_metadata[...]), fullNumber ta' fattura li jidher f'dawk il-kolonni, u - għal rimborżi u chargebacks - il-charge_id ta' ħlas imqabbel qabel (l-istess fajl jew importazzjonijiet preċedenti).
  • Irrevedi bi bank/settlements/list / bank/settlements/get; rranġa l-fdalijiet bi bank/settlements/match { lineId, invoiceId } (jew invoiceId: null b'mod li l-iskonnettja).

POST /v1/bank/settlements/post { id, date?, commissionPercent? } jippostja l-lott kollu bħala tranżazzjoni ta' ġurnal ibbilanċjata waħda u jassigura s-saldu tal-fatturi mqabbla (paidAmount/paymentStatus, webhooks ta' sale_invoice.paid):

  • Iddebita il-kont tal-GL tal-bank għan-nettor tal-payout; iddebita il-miżati tal-PSP (settlements.fees, default 6800) għall-miżati miżmuma lura u r-ringieli tal-miżati.
  • Kredita l-kontijiet dovuti (accounts receivable) għal kull ħlas imqabbel; ir-rimborżi u ċ-chargebacks jqlibuhom. L-applikazzjoni hija limitata għall-ammont li fadal ta' kull fattura - kwalunkwe eċċess jinżel fuq il-kont tas-sospensjoni bi twissija.
  • Ħlasijiet mhux imqabbla: b'commissionPercent issettjat huma mqassmin f'dħul minn kummissjonijiet (settlements.commissionRevenue, default 5001) u responsabbiltà lejn il-bejjiegħ (settlements.sellerPayable, default 4499) - il-fluss tas-suq (marketplace) fejn il-flus miġbura l-aktar jappartjenu lill-bejjiegħa. Mingħajr dan huma pparkjati fuq settlements.suspense (default 4440, avvanzi riċevuti).
  • Ringieli ta' platform_earning (miżati tal-applikazzjoni ta' Stripe Connect) jiġu ppostjati fid-dħul minn kummissjonijiet; ringieli ta' transfer (payouts lill-bejjiegħa konnessi) inaqqsu r-responsabbiltà lejn il-bejjiegħ.
  • L-erba' kontijiet kollha jistgħu jiġu ssostitwiti għal kull kumpanija permezz tar-regoli tal-posting (ledger/posting-rules).
  • Linja li l-ħlas, il-miżata jew ir-rimborż tagħha kienu diġà ġew importati fuq kont bankarju ieħor mill-esportazzjoni tal-pagamenti ta' Stripe (bank/statements/import) ma tiġix irreġistrata fil-miżati, id-dovuti jew is-sospensjoni. In-nettor tagħha net jiġi kkreditat fil-kont tal-ledger ta' dak il-kont bankarju minflok, sabiex il-kont bankarju ta' Stripe jitnaddaf payout b'payout. summary.clearedAmount huwa t-total imċaqalq bdan il-mod; linja li l-ammont tagħha jkun differenti minn dak li dak il-kont iżżomm hija msemmija fit-twissijiet (warnings). Jekk ma jibqa' xejn x'jirregistra, il-lott jiġi ppostjat b'journalTransactionId null.

bank/settlements/list u /get jirritornaw, għal kull lott, clearedNet, clearingDifference (linji tal-payout nieqes l-ammonti li l-kont bankarju l-ieħor iżżomm għalihom; żero meta jaqblu) u clearingOpenCount (linji b'differenza jew moviment mhux ippostjat); /get jirritorna l-istess għal kull linja bħala clearingBankAccountId, clearingBooked, clearingDifference u clearingUnposted. Linji ta' rimborż ta' ħlas wieħed huma mqabbla flimkien, minħabba li l-esportazzjoni tal-pagamenti fiha biss it-total rimborżat. Esportazzjoni tal-pagamenti ta' Stripe importata wara li l-payout tiegħu jkun ġie ippostjat taqbeż il-movimenti ta' dak il-payout u jsemmih fit-twissijiet (warnings).

Il-VAT fuq il-kummissjoni stess tiġi fatturata separatament (oħroġ fattura ta' kummissjoni lill-bejjiegħ); it-tqassim talloka biss il-flus kontanti miġbura.

Payouts f'munita oħra

Il-ġurnal dejjem jikteb bil-munita bażi tal-kumpanija, iżda payout f'munita differenti jiġi ppostjat awtomatikament - m'hemmx bżonn ta' dħul manwali:

  • Il-lott jikkonverti bir-rata għad-data tal-posting (date, li taqa' lura għad-data tal-payout, imbagħad illum). Ir-rata hija r-rata tal-kumpanija stess għal dik il-munita (reference/exchange-rates/set) meta tkun mill-inqas ġdida daqs dik uffiċjali, inkella l-aħħar rata uffiċjali dakinhar jew qabel dik id-data. Mingħajr rata dakinhar jew qabel id-data, is-sejħa tfalli b'422 u tissemmi reference/exchange-rates/sync.
  • Kull kont jikkonverti b'dik ir-rata tal-lott ħlief il-kontijiet dovuti (accounts receivable), li jiġu meħlusa bir-rata tal-kambju fxRate li kull fattura nħarġet biha. Id-differenza bejn iż-żewġ rati tiġi ppostjata f'bank.fxGain (default 5803) jew bank.fxLoss (default 6803) bħala differenza tal-kambju realizzata, sabiex il-ġurnal xorta jibbilanċja.
  • Ir-rispons summary jirritorna l-fxRate użat u d-differenza tal-kambju li tirriżulta exchangeDifference, u l-lott iżżomm ir-rata li ġie ppostjat biha. Fattura mqabbla li l-munita tagħha hija differenti mill-munita tal-lott ma tiġix issedjata: l-ammont tagħha jmur fil-kont tas-sospensjoni bi twissija.
  • Limitu wieħed tal-importazzjoni jibqa': payout wieħed li r-ringieli tiegħu jħalltu diversi muniti jiġi miċħud b'422, u hekk ukoll importazzjoni mill-ġdid li l-munita tagħha tkun differenti mill-lott li diġà huwa maħżun għal dak il-payout.

Għalf manwali / personalizzat

Kwalunkwe ħaġa oħra tista' tiġi mbuttata bħala JSON sempliċi:

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

Ipprovdi externalId stabbli għal kull tranżazzjoni sabiex iżżomm l-importazzjonijiet mill-ġdid idententi (idempotent).