Stripeaccounting/en - Historique des versions

https://wiki.siladel.fr/index.php?action=history&feed=atom&title=Stripeaccounting%2Fen Stripeaccounting/en - Historique des versions 2026-08-02T22:48:20Z Historique des versions pour cette page sur le wiki MediaWiki 1.30.0 https://wiki.siladel.fr/index.php?title=Stripeaccounting/en&diff=553&oldid=prev Goldron le 2 août 2026 à 12:41 2026-08-02T12:41:00Z

<p></p> <table class="diff diff-contentalign-left" data-mw="interface"> <col class="diff-marker" /> <col class="diff-content" /> <col class="diff-marker" /> <col class="diff-content" /> <tr style="vertical-align: top;" lang="fr"> <td colspan="2" style="background-color: white; color:black; text-align: center;">← Version précédente</td> <td colspan="2" style="background-color: white; color:black; text-align: center;">Version du 2 août 2026 à 12:41</td> </tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l1" >Ligne 1 :</td> <td colspan="2" class="diff-lineno">Ligne 1 :</td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>{{DISPLAYTITLE:StripeAccounting — Technical documentation}}</div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>{{DISPLAYTITLE:StripeAccounting — Technical documentation}}</div></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr> <tr><td class='diff-marker'>−</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>[[Fichier:Fr.png|link=Stripeaccounting]]</div></td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>[[Fichier:Fr.png<ins class="diffchange diffchange-inline">|32px</ins>|link=Stripeaccounting<ins class="diffchange diffchange-inline">|Doc en Français</ins>]]</div></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr> </table>

Goldron https://wiki.siladel.fr/index.php?title=Stripeaccounting/en&diff=550&oldid=prev Goldron le 2 août 2026 à 12:36 2026-08-02T12:36:37Z

<p></p> <table class="diff diff-contentalign-left" data-mw="interface"> <col class="diff-marker" /> <col class="diff-content" /> <col class="diff-marker" /> <col class="diff-content" /> <tr style="vertical-align: top;" lang="fr"> <td colspan="2" style="background-color: white; color:black; text-align: center;">← Version précédente</td> <td colspan="2" style="background-color: white; color:black; text-align: center;">Version du 2 août 2026 à 12:36</td> </tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l1" >Ligne 1 :</td> <td colspan="2" class="diff-lineno">Ligne 1 :</td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>{{DISPLAYTITLE:StripeAccounting — Technical documentation}}</div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>{{DISPLAYTITLE:StripeAccounting — Technical documentation}}</div></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr> <tr><td class='diff-marker'>−</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #ffe49c; vertical-align: top; white-space: pre-wrap;"><div>[[Stripeaccounting]]</div></td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div>[[<ins class="diffchange diffchange-inline">Fichier:Fr.png|link=</ins>Stripeaccounting]]</div></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr> </table>

Goldron https://wiki.siladel.fr/index.php?title=Stripeaccounting/en&diff=546&oldid=prev Goldron le 2 août 2026 à 12:22 2026-08-02T12:22:42Z

<p></p> <table class="diff diff-contentalign-left" data-mw="interface"> <col class="diff-marker" /> <col class="diff-content" /> <col class="diff-marker" /> <col class="diff-content" /> <tr style="vertical-align: top;" lang="fr"> <td colspan="2" style="background-color: white; color:black; text-align: center;">← Version précédente</td> <td colspan="2" style="background-color: white; color:black; text-align: center;">Version du 2 août 2026 à 12:22</td> </tr><tr><td colspan="2" class="diff-lineno" id="mw-diff-left-l1" >Ligne 1 :</td> <td colspan="2" class="diff-lineno">Ligne 1 :</td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>{{DISPLAYTITLE:StripeAccounting — Technical documentation}}</div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div>{{DISPLAYTITLE:StripeAccounting — Technical documentation}}</div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div><ins style="font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div><ins style="font-weight: bold; text-decoration: none;">[[Stripeaccounting]]</ins></div></td></tr> <tr><td colspan="2"> </td><td class='diff-marker'>+</td><td style="color:black; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #a3d3ff; vertical-align: top; white-space: pre-wrap;"><div><ins style="font-weight: bold; text-decoration: none;"></ins></div></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"></td></tr> <tr><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div><div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;"></div></td><td class='diff-marker'> </td><td style="background-color: #f9f9f9; color: #333333; font-size: 88%; border-style: solid; border-width: 1px 1px 1px 4px; border-radius: 0.33em; border-color: #e6e6e6; vertical-align: top; white-space: pre-wrap;"><div><div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;"></div></td></tr> </table>

Goldron https://wiki.siladel.fr/index.php?title=Stripeaccounting/en&diff=545&oldid=prev Goldron : Page créée avec « {{DISPLAYTITLE:StripeAccounting — Technical documentation}} <div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1... » 2026-08-02T12:21:58Z

<p>Page créée avec « {{DISPLAYTITLE:StripeAccounting — Technical documentation}} <div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1... »</p> <p><b>Nouvelle page</b></p><div>{{DISPLAYTITLE:StripeAccounting — Technical documentation}}<br /> <br /> <div style="border:1px solid #c8ccd1; background:#f8f9fa; border-radius:4px; padding:1em 1.2em; margin:0 0 1.5em 0;"><br /> '''StripeAccounting''' is a Dolibarr module for '''Stripe accounting reconciliation'''.<br /> <br /> It reads the Stripe API (or a CSV export), identifies the movements the official Stripe module does not post — fees, refunds, disputes, payouts — and creates the missing accounting entries.<br /> <br /> : '''Compatibility''' — Dolibarr 17+, PHP 7.2 → 8.5<br /> : '''Depends on''' — Stripe, Bank and Double-entry Accounting modules<br /> : '''See also''' — [[README|Installation and user guide]]<br /> </div><br /> <br /> __TOC__<br /> <br /> == 1. Design principles ==<br /> <br /> Four rules govern the whole module.<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:22%;" | Principle !! What it means<br /> |-<br /> | '''Complementary''' || The module creates no payment, no invoice, no webhook. It reads Stripe and completes the books, nothing more.<br /> |-<br /> | '''Idempotent''' || Each Stripe object is processed once only, no matter how many times the sync is re-run.<br /> |-<br /> | '''Never guess''' || If an operation cannot be matched with certainty, nothing is posted: the row goes to <code>error</code> for manual review.<br /> |-<br /> | '''Configuration is blocking''' || As long as the minimum configuration is incomplete, no sync runs at all (no button, no cron, no import).<br /> |}<br /> <br /> == 2. Requirements ==<br /> <br /> === Required Dolibarr modules ===<br /> <br /> {| class="wikitable"<br /> ! Module !! What it provides<br /> |-<br /> | '''Stripe''' (<code>modStripe</code>) || API key, test/live mode, Stripe financial account<br /> |-<br /> | '''Bank''' (<code>modBanque</code>) || <code>llx_bank</code> and <code>llx_bank_account</code> tables<br /> |-<br /> | '''Double-entry accounting''' (<code>modAccounting</code>) || <code>llx_accounting_bookkeeping</code> table<br /> |}<br /> <br /> === Mandatory Dolibarr setting ===<br /> <br /> <code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code> must be set under '''Accounting → Setup → Miscellaneous accounts'''. Without it, the internal transfer generated by payouts cannot be transferred to accounting (a Dolibarr limitation, not a module one).<br /> <br /> === Notes ===<br /> <br /> * The Stripe PHP SDK is not re-vendored: the module reuses the core copy (<code>includes/stripe/stripe-php/</code>).<br /> * The code deliberately avoids any PHP syntax newer than 7.2 (no <code>match</code>, <code>?-></code>, enums, typed properties, <code>str_contains</code>…) so it runs across the whole 7.2 → 8.5 range.<br /> <br /> == 3. File tree ==<br /> <br /> <pre><br /> custom/stripeaccounting/<br /> ├── core/modules/modStripeAccounting.class.php Module descriptor (permissions, menus, cron, constants)<br /> ├── class/<br /> │ ├── StripeApi.class.php Stripe SDK wrapper (read-only)<br /> │ ├── StripeRepository.class.php SQL access + idempotency<br /> │ ├── StripeLogger.class.php Logging<br /> │ ├── StripeAccounting.class.php Accounting entry generation<br /> │ ├── StripePayout.class.php Payout reconciliation<br /> │ ├── StripeSync.class.php Orchestrator (cron entry point)<br /> │ ├── StripeCsvImporter.class.php CSV import<br /> │ └── actions_stripeaccounting.class.php 'bankcard' hook<br /> ├── admin/setup.php Configuration<br /> ├── import.php CSV import<br /> ├── dashboard.php Dashboard<br /> ├── transaction_list.php Transaction list<br /> ├── cron/stripe_sync.php CLI entry point<br /> ├── lib/stripeaccounting.lib.php<br /> ├── sql/<br /> ├── langs/{fr_FR,en_US,es_ES,it_IT,de_DE}/<br /> └── css/<br /> </pre><br /> <br /> === Dependency direction ===<br /> <br /> : pages and hook → <code>StripeSync</code> → (<code>StripeApi</code>, <code>StripeRepository</code>, <code>StripeAccounting</code>, <code>StripePayout</code>) → <code>StripeLogger</code><br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:26%;" | Class !! Role<br /> |-<br /> | <code>StripeApi</code> || Queries the Stripe SDK (balance transactions, charges, refunds, disputes, payouts) with automatic pagination. No database access, no accounting entries.<br /> |-<br /> | <code>StripeRepository</code> || All SQL for the module's two tables. <code>upsertTransaction()</code> is the idempotency anchor.<br /> |-<br /> | <code>StripeLogger</code> || Writes to <code>llx_stripeaccounting_log</code> and mirrors to <code>dol_syslog()</code>.<br /> |-<br /> | <code>StripeAccounting</code> || Builds accounting entries (refund, dispute, reverse-charge VAT) or bank movements (fees). Exposes <code>checkConfig()</code>.<br /> |-<br /> | <code>StripePayout</code> || Creates the internal bank transfer between the Stripe account and the real bank account.<br /> |-<br /> | <code>StripeSync</code> || Orchestrator: one method per flow, plus <code>reconcileStripeAccount()</code> which chains them all.<br /> |-<br /> | <code>StripeCsvImporter</code> || Feeds the same pipeline from a Stripe CSV export.<br /> |-<br /> | <code>ActionsStripeAccounting</code> || <code>bankcard</code> hook: dashboard link on the Stripe account record.<br /> |}<br /> <br /> == 4. Synchronisation and idempotency ==<br /> <br /> Every flow (<code>syncFees</code>, <code>syncRefunds</code>, <code>syncDisputes</code>, <code>syncPayouts</code>, <code>syncTransactions</code>) always follows the same steps:<br /> <br /> # '''Check the configuration''' — if incomplete: <code>ERROR</code> log, immediate stop, no API call at all.<br /> # '''List Stripe objects''' over a rolling window of '''35 days'''.<br /> # '''Filter''' — an object is skipped only if it already exists ''and'' its status is <code>reconciled</code> or <code>ignored</code>. A row in <code>pending</code> or <code>error</code> is '''retried''' on this run.<br /> # '''Record''' it as <code>pending</code>, then generate the accounting entry or bank movement.<br /> # '''Conclude''' — success: status <code>reconciled</code>. Failure: status <code>error</code> with the message, and '''the batch carries on''' with the next object.<br /> <br /> <div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;"><br /> '''Automatic retry''' — a row in <code>error</code> becomes eligible again on the next run. Once the cause is fixed (a fiscal year created late, for instance), no manual action is needed.<br /> </div><br /> <br /> === Why duplicates are impossible ===<br /> <br /> * '''Unique database key''' on <code>(stripe_object_id, entity)</code> — protects even against two concurrent cron executions.<br /> * '''Explicit check before processing''' — avoids even attempting to post an entry for an already-finalised object.<br /> <br /> === Special cases: <code>adjustment</code> and <code>payment_failure_refund</code> ===<br /> <br /> These are balance corrections Stripe makes on its own (reversal after a dispute is resolved, automatic refund of a payment that ultimately failed). The module '''records''' them — otherwise they would stay invisible — but '''never''' posts them automatically: the sign of the amount and the underlying cause vary too much. They are created directly in <code>error</code>, with an explicit message, to be handled manually.<br /> <br /> == 5. Accounting entries ==<br /> <br /> All lines of a single Stripe event share the same <code>doc_type='stripeaccounting'</code>, <code>fk_doc</code> and <code>doc_ref</code> triplet: Dolibarr automatically groups them under one piece number, so the module needs no numbering scheme of its own.<br /> <br /> === Overview ===<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! Event !! What the module does !! Resulting entry<br /> |-<br /> | Stripe fee ''(VAT mode <code>none</code> or <code>autoliquidation</code>)'' || <code>PaymentVarious</code> bank movement || 627xxx / 517xxx entry generated later by Dolibarr<br /> |-<br /> | Stripe fee ''(<code>autoliquidation</code> mode)'' || Plus: VAT pair posted immediately || Debit deductible VAT, credit reverse-charge VAT ''(net impact nil)''<br /> |-<br /> | Stripe fee ''(<code>french</code> mode)'' || Full direct entry || Debit fee account excl. VAT + deductible VAT, credit Stripe account incl. VAT<br /> |-<br /> | Subscription / service fees ''(Radar, Billing, Connect…)'' || <code>PaymentVarious</code> bank movement || Entry generated later by Dolibarr, on the Stripe supplier account<br /> |-<br /> | Payout || Internal bank transfer between the two accounts || Entry generated later by Dolibarr<br /> |-<br /> | Refund ''(invoice found)'' || Direct entry || Debit customer account 411xxx, credit Stripe account 517xxx<br /> |-<br /> | Refund ''(invoice not found)'' || Nothing || Status <code>error</code>, handle manually<br /> |-<br /> | Dispute / chargeback || Direct entry || Debit dispute loss 658xxx, credit Stripe account 517xxx ''(+ fee account if fees apply)''<br /> |}<br /> <br /> === Why fees and payouts produce no direct entry ===<br /> <br /> The historical problem: when a Stripe-paid invoice is transferred to accounting through Dolibarr's standard workflow, the payment is posted at its '''gross''' amount — fees are ignored at that stage.<br /> <br /> If the module posted its own entry ''and'' its own bank line on top of that, this line would stay invisible to <code>bankjournal.php</code> — which only recognises lines attached to <code>doc_type='bank'</code>. An administrator transferring the bank account to accounting "normally" would then create a '''second''' entry for the very same movement.<br /> <br /> '''The chosen solution:''' for fees, subscription fees and payouts, the module now creates only the '''real bank movement''', using Dolibarr's native mechanisms. The native ''"Transfer to accounting"'' button then produces the entry, exactly as for any other bank movement. In those three cases, the module no longer touches <code>llx_accounting_bookkeeping</code> at all.<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:22%;" | Case !! Native mechanism used<br /> |-<br /> | Fees and subscription fees || <code>PaymentVarious</code> (bank movement with an explicit counterpart account, no third party or invoice), carrying its own <code>accountancy_code</code>, which <code>bankjournal.php</code> reads directly.<br /> |-<br /> | Payouts || Dolibarr internal transfer: <code>Account::addline()</code> on both sides, plus <code>add_url_line(…, 'banktransfert')</code>. The counterpart is posted to <code>ACCOUNTING_ACCOUNT_TRANSFER_CASH</code>.<br /> |}<br /> <br /> In both cases the status becomes <code>reconciled</code> — the module's job is done — but '''<code>piece_num</code> stays empty''': the entry does not exist yet, only <code>fk_bank</code> is set. After the manual transfer, it can be found with <code>doc_type='bank'</code> and <code>fk_doc</code> equal to the row's <code>fk_bank</code>.<br /> <br /> <div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;"><br /> '''Worth knowing''' — the payout entry only balances to zero on the transfer account once '''both''' bank accounts (Stripe ''and'' the real bank) have been transferred to accounting, not just one of them.<br /> </div><br /> <br /> <div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;"><br /> '''⚠ <code>STRIPE_AUTO_RECORD_PAYOUT</code> must stay disabled'''<br /> <br /> Once this module handles payouts, untick "Enable automatic recording of Stripe payments" in <code>stripe/admin/stripe.php</code> — despite its wording, that checkbox only concerns payouts.<br /> <br /> Otherwise the official module's webhook and this module would each create their own bank movement for the same payout, unaware of each other.<br /> <br /> The core webhook keeps '''no''' trace of the payout id it has processed: should Stripe deliver the event twice (delivery is guaranteed "at least once"), nothing stops it from duplicating on its own either. This module has real idempotency and automatically catches up any missed payout within 35 days.<br /> </div><br /> <br /> === The "Stripe transfers" page is hidden ===<br /> <br /> On activation, <code>modStripeAccounting::init()</code> disables the <code>stripe/payout.php</code> menu entry: that page queries the API live without recording anything, and having it alongside this module would only create confusion about which one is authoritative for payouts. <code>remove()</code> restores the original condition. '''This is the only core table the module modifies''' — deliberate, and documented here for that reason.<br /> <br /> === Per-transaction fees or subscription fees? ===<br /> <br /> Stripe bills two distinct things under the generic word "fees":<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! !! Per-transaction fees !! Subscription / service fees<br /> |-<br /> ! Example<br /> | Commission on each payment || Radar, Billing, Connect<br /> |-<br /> ! Where to find it<br /> | The <code>.fee</code> field of a <code>charge</code> balance transaction || A dedicated balance transaction, type <code>stripe_fee</code> or <code>application_fee</code> ''(its <code>.fee</code> is always 0, the amount sits in <code>.amount</code>)''<br /> |-<br /> ! Account used<br /> | The configured fee account (627xxx) || The supplier accounting code of the configured Stripe third party<br /> |-<br /> ! Type in database<br /> | <code>fee</code> || <code>subscription_fee</code><br /> |}<br /> <br /> === Limitation of the <code>french</code> VAT mode ===<br /> <br /> This mode has to split the gross amount into net + VAT, something <code>PaymentVarious</code> cannot express. It therefore keeps the previous behaviour: a full direct entry, with no bank movement created. No duplicate risk (precisely because no bank line is produced), but the <code>llx_bank</code> balance of the Stripe account will never reflect the fees while this mode is active.<br /> <br /> == 6. CSV import ==<br /> <br /> The import covers the case of a Stripe account '''different''' from the one configured in the official module — another PrestaShop shop with its own merchant account, for example. The API has no access to it: its contents are exported to CSV from the Stripe dashboard, then imported.<br /> <br /> === Starting assumption ===<br /> <br /> The invoices and payments of that shop are '''already''' posted in Dolibarr through some other process, and the collection (debit 517, credit 411) is already booked. Only the '''fees''', '''refunds''' and '''payouts''' are missing — which is exactly what the import handles.<br /> <br /> === Interface: a single field ===<br /> <br /> <code>import.php</code> now exposes only one upload field, '''General history''', wired to <code>importGeneralHistory()</code>. That file alone covers every movement type.<br /> <br /> <code>importPayments()</code> and <code>importPayouts()</code> are still implemented and functional, but no longer reachable from the interface; they are documented below for reference.<br /> <br /> Like the "Sync now" button, the import is blocked — warning banner, disabled button, server-side guard — while the configuration is incomplete.<br /> <br /> === The three methods ===<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:24%;" | Method !! Stripe export read !! Processing<br /> |-<br /> | <code>importGeneralHistory()</code><br />''(the only one exposed)'' || Balance history || Dispatch on the <code>Type</code> column, see table below<br /> |-<br /> | <code>importPayments()</code> || Payments || Fee → fee movement. Amount refunded → <code>refund</code> row, always in <code>error</code>.<br /> |-<br /> | <code>importPayouts()</code> || Payouts || Exactly the same processing as a payout coming from the API<br /> |}<br /> <br /> General history dispatch, by <code>Type</code> column:<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:30%;" | Stripe type !! Processing<br /> |-<br /> | <code>payout</code> || Internal bank transfer, as via the API<br /> |-<br /> | <code>charge</code> / <code>payment</code> with a fee || Fee movement<br /> |-<br /> | <code>stripe_fee</code> / <code>application_fee</code> || Subscription fee, on the Stripe supplier account<br /> |-<br /> | <code>refund</code> || Recorded, '''always''' in <code>error</code><br /> |-<br /> | <code>payout_minimum_balance_hold</code> / <code>…_release</code> || '''Ignored''' — Stripe rolling reserve, no real cash movement, nothing to post<br /> |-<br /> | any other type || Recorded as <code>type='other'</code>, status <code>error</code>, raw Stripe type kept in the description. No guessed entry.<br /> |}<br /> <br /> Columns are matched '''by name''': their order does not matter, and extra unused columns are ignored.<br /> <br /> === Import idempotency ===<br /> <br /> The unique key protects against any double import: re-importing the same CSV, or one overlapping a previous import, creates no duplicate.<br /> <br /> An important detail: in the general history, <code>payout</code> and <code>charge</code>/<code>payment</code> rows are indexed by their '''<code>Source</code>''' column (<code>po_…</code>, <code>ch_…</code>), not by the row's own <code>id</code> (<code>txn_…</code>) — the very same key the dedicated imports use. Importing the general history '''on top of''' the specific exports therefore never posts the same entry twice, in any order.<br /> <br /> Since Stripe identifiers are unique platform-wide, mixing rows from the API account and from several CSV-imported accounts in the same table carries no collision risk.<br /> <br /> === Practical details ===<br /> <br /> * '''Source label''' — a free-text field entered at import time (e.g. "DRM shop") is stored on every created row and serves as a column and filter in the list, to tell several shops apart side by side.<br /> * '''Amount format''' — Stripe CSVs use the French decimal comma, converted through <code>price2num()</code>. Dates marked <code>(UTC)</code> are interpreted as such.<br /> <br /> == 7. Configuration ==<br /> <br /> The API key and test/live mode are '''not''' re-entered here: they are read, read-only, from the official Stripe module.<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:26%;" | Field !! Constant !! Purpose<br /> |-<br /> | Stripe financial account || <code>STRIPE_BANK_ACCOUNT_FOR_PAYMENTS</code> ''(official module constant)'' || Bank account selector. No local copy, hence no risk of divergence.<br /> |-<br /> | Main bank account || <code>STRIPE_BANK_ACCOUNT_FOR_BANKTRANSFERS</code> ''(official module constant)'' || Same selector. See the box below.<br /> |-<br /> | Fee account || <code>STRIPEACCOUNTING_COMPTE_FRAIS</code> || Account number, e.g. 627xxx<br /> |-<br /> | Dispute account || <code>STRIPEACCOUNTING_COMPTE_LITIGES</code> || Account number, e.g. 658xxx. '''Required''' — used as soon as a dispute occurs, whatever the VAT mode.<br /> |-<br /> | Stripe supplier third party || <code>STRIPEACCOUNTING_FOURNISSEUR_STRIPE_ID</code> || A third party flagged as supplier; its supplier accounting code is what gets used. Optional, unless subscription fees exist.<br /> |-<br /> | VAT mode || <code>STRIPEACCOUNTING_VAT_MODE</code> || <code>none</code>, <code>french</code> or <code>autoliquidation</code><br /> |-<br /> | Deductible VAT account (intra-EU) || <code>STRIPEACCOUNTING_COMPTE_TVA_DEDUCTIBLE</code> || Required when the VAT mode is not <code>none</code>. Stripe always invoices from a non-French EU entity, so the deductible VAT is intra-EU in every case.<br /> |-<br /> | VAT due account (intra-EU) || <code>STRIPEACCOUNTING_COMPTE_TVA_AUTOLIQUIDATION</code> || Required in <code>autoliquidation</code> mode only — never used in <code>french</code> mode.<br /> |-<br /> | VAT rate || <code>STRIPEACCOUNTING_VAT_RATE</code> || Percentage, 20 by default<br /> |-<br /> | Sync frequency || <code>STRIPEACCOUNTING_SYNC_UNITFREQUENCY</code> || Applied to the scheduled job (in seconds)<br /> |}<br /> <br /> <div style="border-left:4px solid #36c; background:#eaf3ff; padding:0.6em 1em; margin:1em 0;"><br /> '''Why redefine the main bank account here?'''<br /> <br /> The official Stripe module's setup page only renders that field when <code>STRIPE_AUTO_RECORD_PAYOUT</code> is enabled — and its own save handler resets the value to 0 on every save while the field is not rendered. Yet that setting must stay disabled once this module handles payouts. The field is therefore re-exposed here, writing the core constant directly, so the value stays configurable and stable.<br /> <br /> Both account selectors only write their constant when a real account was submitted: saving the page for some unrelated field never overwrites a correct value.<br /> </div><br /> <br /> === Configuration check ===<br /> <br /> <code>StripeAccounting::checkConfig()</code> returns the list of missing constants. It is called both by the setup page (information banner) and by every sync entry point (the real guard that blocks all processing).<br /> <br /> === Pitfall with accounting account selectors ===<br /> <br /> The four fields using <code>FormAccounting::select_account()</code> (fees, disputes, both VAT accounts) have a "nothing selected" option whose value is '''<code>-1</code>''' — a non-empty string, therefore truthy in PHP. A field left blank and saved literally stores <code>-1</code>.<br /> <br /> <code>StripeAccounting::getAccountConst()</code> normalises that value to an empty string on read, everywhere these constants are read. No entry can therefore land on the non-existent account <code>-1</code>.<br /> <br /> == 8. User interface ==<br /> <br /> === Dashboard ===<br /> <br /> Stripe balance (live API call), number of unreconciled transactions, total fees for the month, pending payouts, and a '''Sync now''' button — disabled, with a banner listing the missing constants, while the configuration is incomplete.<br /> <br /> === Transaction list ===<br /> <br /> A paginated, sortable, filterable list built with the same mechanism as native Dolibarr lists: the icon at the top right of the table lets each user pick their columns, and the preference is stored per user.<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:20%;" | Column !! Content<br /> |-<br /> | Amount, Fee, Total || The fee popup shows the VAT on the fee whenever a reverse-charge pair or French VAT was posted<br /> |-<br /> | Type, Description || Popup with the Stripe ID, the event or source ID, and the full untruncated description<br /> |-<br /> | Third party || The customer resolved through the invoice, or through the source charge for its related fee, or the configured Stripe supplier for a subscription fee<br /> |-<br /> | Entry || A "Piece no. X" link to the accounting entry, and/or a link to the related bank movement — see the caveat below<br /> |-<br /> | Source, Status || The <code>error</code> badge opens a popup with the full error message: no need to query the database to understand a failure<br /> |}<br /> <br /> <div style="border-left:4px solid #fc3; background:#fef6e7; padding:0.6em 1em; margin:1em 0;"><br /> '''Reading the "Entry" column''' — on a <code>fee</code>, <code>subscription_fee</code> or <code>payout</code> row, the link points to the '''bank movement''', not to an accounting piece. The module's <code>piece_num</code> is never the 627/517 entry for the fee: it is only the reverse-charge VAT pair. The fee entry itself is generated later, by Dolibarr's native button, and is never reported back onto this row.<br /> </div><br /> <br /> The page is '''purely informational''': no manual posting is offered there. The module posts automatically, and the actual transfer to accounting for fees and payouts happens through the native "Transfer to accounting" button.<br /> <br /> === <code>charge</code> and <code>fee</code> rows ===<br /> <br /> Each payment produces '''two rows''' in the database:<br /> <br /> * a <code>charge</code> row, always in status <code>ignored</code>, fee 0, never processed — present solely for idempotency;<br /> * a <code>fee</code> row for the same payment, linked to the first one.<br /> <br /> Both appear separately in the list, but the <code>fee</code> row also carries the link to the payment and the invoice, resolved through a join.<br /> <br /> === Test mode banner ===<br /> <br /> While live mode is off, the dashboard, the setup page and the transaction list all display the same warning as the official Stripe module. It is impossible to forget you are working in test mode.<br /> <br /> === Menus ===<br /> <br /> Everything sits under '''Banks and cash → Stripe account''' (the official module's menu), flat, as three entries at the same level:<br /> <br /> # Stripe dashboard<br /> # Stripe transactions<br /> # CSV import ''(administrators only)''<br /> <br /> A dashboard link is also added automatically on the bank account record configured as the Stripe account.<br /> <br /> == 9. Scheduled job ==<br /> <br /> There are two ways to run the sync, both idempotent and safe to re-run. In both cases the code executed is strictly the same: no behavioural difference between the two triggers.<br /> <br /> <div style="border-left:4px solid #d33; background:#fee7e6; padding:0.6em 1em; margin:1em 0;"><br /> '''⚠ Neither of them starts on its own.'''<br /> <br /> Activating the module creates the <code>StripeAccountingSync</code> job, but '''disabled by default'''. And even once enabled, the Dolibarr scheduler is triggered by nothing until a system crontab calls it. Without both steps, the sync only happens when "Sync now" is clicked manually.<br /> </div><br /> <br /> === Step 1 — enable the job ===<br /> <br /> Under '''Home → Setup → Modules → Scheduled jobs'''. Since <code>llx_cronjob</code> is a core table, this setting is made through the interface only, never by direct SQL from the module.<br /> <br /> === Step 2 — a system trigger ===<br /> <br /> Pick either option.<br /> <br /> '''Option A — Dolibarr scheduler''' ''(recommended when several Dolibarr scheduled jobs coexist)''. Runs every due job, not just this one. Requires step 1.<br /> <br /> <syntaxhighlight lang="bash"><br /> */15 * * * * curl "https://your-dolibarr/public/cron/cron_run_jobs_by_url.php?securitykey=YOUR_KEY&userlogin=YOUR_LOGIN"<br /> </syntaxhighlight><br /> <br /> The security key is generated on the scheduled jobs page, "Security of job execution by URL" button.<br /> <br /> '''Option B — the module's CLI script.''' Standalone, refuses to run from a browser, and independent of whether the Dolibarr job is enabled.<br /> <br /> <syntaxhighlight lang="bash"><br /> */15 * * * * php /path/to/htdocs/custom/stripeaccounting/cron/stripe_sync.php >> /var/log/stripeaccounting.log 2>&1<br /> </syntaxhighlight><br /> <br /> == 10. Logging and permissions ==<br /> <br /> === Logging ===<br /> <br /> Every API call, generated entry, warning or error is traced in <code>llx_stripeaccounting_log</code>, readable in the database or through the standard Dolibarr log file. Levels: <code>DEBUG</code> < <code>INFO</code> < <code>WARNING</code> < <code>ERROR</code>. The <code>context</code> column holds the structured detail as JSON (API payload, computed amounts…).<br /> <br /> === Permissions ===<br /> <br /> {| class="wikitable"<br /> ! Right !! Controls<br /> |-<br /> | <code>read</code> || Access to the dashboard and the transaction list<br /> |-<br /> | <code>write</code> || Declared for configuration, but not checked in the code today<br /> |-<br /> | <code>reconcile</code> || Manual sync triggering<br /> |}<br /> <br /> In practice, <code>admin/setup.php</code> and <code>import.php</code> only check '''Dolibarr administrator''' status, not the <code>write</code> right: only administrators can configure the module or import a CSV, whatever is ticked in the module permissions.<br /> <br /> == 11. Database schema ==<br /> <br /> === <code>llx_stripeaccounting_transaction</code> ===<br /> <br /> One row per processed Stripe object — charge, fee, refund, dispute or payout — all in the same table, distinguished by the <code>type</code> column.<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:24%;" | Column !! style="width:16%;" | Type !! Role<br /> |-<br /> | <code>rowid</code> || int AI || Primary key<br /> |-<br /> | <code>entity</code> || int || Dolibarr multi-company<br /> |-<br /> | <code>stripe_object_id</code> || varchar(80) || Stripe identifier — '''idempotency anchor'''<br /> |-<br /> | <code>stripe_event_id</code> || varchar(80) || Event identifier, informational only<br /> |-<br /> | <code>type</code> || varchar(20) || <code>charge</code>, <code>fee</code>, <code>subscription_fee</code>, <code>refund</code>, <code>dispute</code>, <code>payout</code>, <code>other</code><br /> |-<br /> | <code>stripe_source_id</code> || varchar(80) || Source Stripe object (e.g. the charge behind a refund)<br /> |-<br /> | <code>source_label</code> || varchar(80) || Free-text label entered at CSV import; empty for API rows<br /> |-<br /> | <code>description</code> || varchar(255) || Stripe label<br /> |-<br /> | <code>amount</code>, <code>fee</code>, <code>net</code> || decimal(24,8) || Amounts already converted from Stripe cents<br /> |-<br /> | <code>currency</code> || varchar(3) || ISO currency code<br /> |-<br /> | <code>date_created</code>, <code>date_available_on</code> || datetime || Stripe-side dates<br /> |-<br /> | <code>fk_facture</code>, <code>fk_paiement</code> || int || Resolved Dolibarr invoice and payment, if found<br /> |-<br /> | <code>fk_bank</code> || int || Generated <code>llx_bank</code> line ''(empty for a fee in <code>french</code> VAT mode)''<br /> |-<br /> | <code>piece_num</code> || varchar(20) || Generated accounting piece number, where there is one<br /> |-<br /> | <code>status</code> || varchar(16) || <code>pending</code>, <code>reconciled</code>, <code>error</code>, <code>ignored</code><br /> |-<br /> | <code>error_message</code> || text || Detail on failure<br /> |-<br /> | <code>date_creation</code>, <code>date_processed</code> || datetime || Technical timestamps<br /> |-<br /> | <code>fk_user_creat</code> || int || User who triggered the processing<br /> |}<br /> <br /> '''Unique key''' on <code>(stripe_object_id, entity)</code> — this is what guarantees the same Stripe object can never be inserted twice, even with concurrent executions.<br /> <br /> === <code>llx_stripeaccounting_log</code> ===<br /> <br /> {| class="wikitable"<br /> ! Column !! Role<br /> |-<br /> | <code>level</code> || <code>DEBUG</code>, <code>INFO</code>, <code>WARNING</code>, <code>ERROR</code><br /> |-<br /> | <code>message</code> || Short message<br /> |-<br /> | <code>context</code> || Structured context as JSON<br /> |-<br /> | <code>fk_stripeaccounting_transaction</code> || Related transaction, where applicable<br /> |-<br /> | <code>datec</code> || Timestamp<br /> |}<br /> <br /> == 12. Troubleshooting ==<br /> <br /> {| class="wikitable" style="width:100%;"<br /> ! style="width:26%;" | Symptom !! Likely cause !! Action<br /> |-<br /> | The "Sync now" button is disabled || Minimum configuration incomplete || Fill in the fields listed in the setup page banner<br /> |-<br /> | A transaction stays in <code>error</code> || Entry rejected by Dolibarr (non-existent account, closed period), or refund not matched || Read <code>error_message</code> on the row, then the detail in the log table<br /> |-<br /> | The Stripe balance is not displayed || API key missing or invalid in the official Stripe module || Check <code>stripe/admin/stripe.php</code><br /> |-<br /> | A refund is never reconciled || The original payment was not found through <code>ext_payment_id</code> || Check that the Stripe payment was recorded by the official module with that identifier<br /> |-<br /> | A <code>subscription_fee</code> stays in <code>error</code> || Stripe supplier third party not set, or has no supplier accounting code || Fill the field in setup, and complete the third party record<br /> |-<br /> | A CSV-imported refund stays in <code>error</code> || '''Normal and expected''' — that account is not linked to <code>ext_payment_id</code> || Handle the invoice and refund manually in accounting<br /> |}<br /> <br /> == 13. Pitfalls encountered ==<br /> <br /> Development notes, kept so nobody falls into them again.<br /> <br /> * '''<code>PaymentVarious::create()</code>''' only updates <code>fk_bank</code> in the database, never on the PHP object. A <code>fetch()</code> after <code>create()</code> is required to get the real value.<br /> * '''<code>select_comptes()</code>''' prints its own HTML ''and'' returns the number of accounts. Call it as a bare statement: wrapping it in <code>print</code> would display that number right after the select tag.<br /> * '''<code>master.inc.php</code>, not <code>main.inc.php</code>''' for the CLI script. The latter expects an HTTP session and, in pure CLI, exits silently — no output, no log, return code 0 — inside its redirect to the login page. This gives the misleading impression that the script "does nothing" rather than a real error.<br /> * '''Core libraries''' — <code>master.inc.php</code> does not load everything <code>main.inc.php</code> loads for the web (e.g. <code>core/lib/date.lib.php</code>, required by <code>BookKeeping</code>). Include them explicitly if the CLI script evolves.<br /> * '''The "nothing selected" option is <code>-1</code>''' in accounting account selectors — see the Configuration section.<br /> <br /> == 14. Known limitations ==<br /> <br /> * '''Zero-decimal currencies''' (JPY, KRW…) are not handled: amounts are divided by 100 assuming two decimals. Intended use: EUR.<br /> * '''The 35-day window''' is not configurable. A sync interrupted for longer must be caught up manually.<br /> * '''Refund matching''' — relies on <code>ext_payment_id</code> and <code>ext_payment_site</code> in <code>llx_paiement</code>, filled in by the standard Stripe payment flow. A payment recorded any other way cannot be matched automatically. Matching goes through the '''PaymentIntent id''', never the charge id: the core Stripe module never stores the latter ''(it stores either the raw PaymentIntent, or a composite value, depending on the payment path taken)''.<br /> * '''CSV import assumes French notation''': an export with a decimal point would not be parsed correctly.<br /> * '''The "Transfer" column of the Payments CSV''' is stored for information only: it is not used to check that the sum of payments matches the imported payout amount.<br /> * '''CSV-imported refunds always land in <code>error</code>''' — intended behaviour, not a bug.<br /> * '''<code>french</code> VAT mode''' — the Stripe account's bank balance does not reflect the fees, see section 5.<br /> <br /> [[Category:Dolibarr]]<br /> [[Category:Modules]]<br /> [[Category:Accounting]]</div>

Goldron