Payouts i conciliació bancària

Com Factuarea ingereix els payouts de Stripe, els vincula amb els cobraments que agrupen, els concilia contra el teu extracte Norma 43 i emet l'esdeveniment payout.reconciled.

Quan connectes Stripe via Stripe Connect, Stripe no transfereix cada cobrament al teu banc d'un en un: agrupa molts cobraments, resta les seves comissions i envia un únic payout (po_xxx) al teu compte. La línia que apareix al teu extracte diu STRIPE PAYOUT 1.234,56 € i és el net de N cobraments menys comissions, així que mai casa amb el total d'una sola factura.

Factuarea tanca aquest cicle. Ingereix cada payout, el vincula amb els cobraments que el componen i concilia la línia bancària contra el payout, no contra una factura. Quan confirmes el match, el payout, la transacció bancària i tots els cobraments subjacents queden marcats com a conciliats en un únic pas atòmic.

Els payouts són de només lectura a l'API pública: pots llistar-los i inspeccionar-los juntament amb el seu estat de conciliació, però la conciliació en si es fa al Dashboard contra el teu extracte Norma 43 importat. Dos endpoints v1 els exposen:

Llistar payouts de Stripe (payouts:read).
Obtenir un payout de Stripe (payouts:read).

Ingesta d'un payout

Cada vegada que Stripe completa un payout envia un webhook payout.paid al teu endpoint de Connect. Factuarea hi reacciona:

Registra el payout — connected_account_id (acct_xxx), stripe_payout_id (po_xxx), els imports net, comissions i brut, la divisa i la data d'arribada prevista — amb status: ingested.
Llegeix les balance transactions del payout en el teu nom (una crida de només lectura i paginada a Stripe) per descobrir quins cobraments agrupa el payout i el total de comissions. Aquest desglossament es guarda com la composition informativa.

La ingesta és idempotent en dos nivells: per l'event.id de Stripe (un payout.paid reentregat es processa com a màxim una vegada) i pel stripe_payout_id (dos esdeveniments diferents del mateix po_xxx mai creen una fila duplicada — la unicitat està garantida a la base de dades, fins i tot amb webhooks concurrents).

Si el desglossament no es pot llegir (un error transitori de Stripe després dels reintents), el payout no queda ingerit a mitges: es reintenta el pas complet, i l'event.id només es marca com a processat quan la ingesta acaba amb èxit. Mai hi ha una fila de payout sense els seus imports.

Per ingerir payouts has d'habilitar l'esdeveniment payout.paid al teu endpoint de webhook de Connect al Stripe Dashboard. Com sempre, valida el flux primer amb una clau fact_test_ — al sandbox la ingesta corre contra una empresa aïllada amb tots els efectes externs desactivats.

Vinculació dels cobraments amb el payout

Les balance transactions diuen a Factuarea quins cobraments componen el payout. Cada component porta el seu payment_intent (pi_xxx) de Stripe — el mateix identificador que Factuarea va estampar al Payment que va registrar quan el cobrament es va auto-facturar (vegeu Auto-facturació Stripe).

Amb aquest identificador, Factuarea troba els Payment corresponents de la teva empresa i estampa l'id del payout a cadascun. Així els cobraments d'un payout queden vinculats als cobraments que els van produir — la relació que més tard permet que la conciliació baixi en cascada fins a cada cobrament.

La vinculació és best-effort i idempotent: tornar a vincular el mateix payout no és un error, i un component sense Payment corresponent (un cobrament rebut abans que existís l'auto-facturació, o per una altra eina) es registra al log d'integració sense bloquejar la resta. El payout s'ingereix igualment — la conciliació casa pel import net, mai exigeix un desglossament complet dels cobraments.

Conciliació contra l'extracte bancari

La conciliació corre sobre el teu extracte bancari Norma 43 importat, al Dashboard. Quan puges un extracte, Factuarea proposa matches per a cada línia d'abonament. Abans d'intentar casar un abonament contra una factura pendent, comprova si la línia és un payout:

Senyal	Regla
Import	L'abonament bancari equival a l'import net del payout (dins d'una petita tolerància d'arrodoniment). Aquesta és la senyal dura.
Finestra d'arribada	La data valor del banc cau dins de ±3 dies de l'`arrival_date` del payout (els bancs liquiden amb un petit desfasament).
Descripció	Una menció `STRIPE` suma confiança però mai és requisit — la redacció varia entre bancs.

El resultat depèn de quants payouts ingested encaixin:

Exactament un → un match de payout automàtic.
Més d'un → un suggeriment amb els candidats, perquè triïs.
Cap → la línia continua al matching ordinari per factura (un abonament que no és un payout ha de seguir casant amb una factura).

Una transacció casada contra un payout queda exclosa del matching per factura, i viceversa, de manera que la mateixa línia bancària mai es concilia dues vegades.

El matching és per divisa. El payout s'ingereix en la seva divisa real i només casa amb línies bancàries en la mateixa divisa — no hi ha conversió (això és conciliació comptable, no una operació fiscal, així que mai emet ni altera una factura).

Confirmació del match

Quan confirmes un match de payout al Dashboard, Factuarea executa una única transacció atòmica:

La transacció bancària es marca conciliada (amb tipus de match payout).
El payout transiciona a reconciled (un estat terminal) i registra la referència de la transacció bancària a bank_transaction_ref.
Cada Payment vinculat al payout queda estampat amb el seu reconciled_at i la referència de la transacció bancària.

Hi ha guards que protegeixen cada pas: la transacció bancària ha de seguir pending, el payout ha de seguir ingested, i els imports han de coincidir. Confirmar un payout que ja està conciliat, o una transacció que ja està casada, es rebutja sense deixar cap estat a mitges. Tota l'operació és tenant-scoped: un payout o una transacció d'una altra empresa mai és visible ni conciliable.

Inspeccionar payouts a l'API

Llista els payouts de la teva empresa amb paginació per cursor, filtrats per status de conciliació i per finestra de data d'arribada:

curl "https://api.factuarea.com/v1/payouts?status=ingested&arrival_date[gte]=2026-01-01&limit=25" \
  -H "Authorization: Bearer fact_test_…"

{
  "data": [
    {
      "id": "0192f3a4-7b2c-7e10-9c1a-1f2e3d4c5b6a",
      "object": "stripe_payout",
      "connected_account_id": "acct_1QabcDEF2ghIJklm",
      "stripe_payout_id": "po_1QabcDEF2ghIJklm",
      "amount_net": "1234.56",
      "fee_total": "37.04",
      "amount_gross": "1271.60",
      "currency": "EUR",
      "arrival_date": "2026-01-08",
      "status": "ingested",
      "reconciled_at": null,
      "bank_transaction_ref": null,
      "composition": {
        "components": [
          { "payment_intent": "pi_3QabcDEF2ghIJklm", "charge_id": "ch_3QabcDEF2ghIJklm", "amount": 121.00, "fee": 3.50 }
        ],
        "fee_total": 37.04
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Cada identificador és opac:

id és l'UUID v7 del payout — la identitat pública del recurs.
connected_account_id (acct_xxx) i stripe_payout_id (po_xxx) són ids externs de Stripe, no foreign keys a altres recursos de Factuarea.
bank_transaction_ref és l'UUID (v7) de la transacció de l'extracte bancari conciliada — null mentre el payout segueix ingested.
composition referencia ids opacs de Stripe (payment_intent = pi_xxx, charge_id = ch_xxx), no UUIDs interns de cobrament. Pot estar buit quan no s'ha pogut llegir el desglossament.

L'status d'un payout és ingested fins que es concilia contra una línia bancària, i després reconciled (terminal). Obtén un payout concret pel seu id:

curl "https://api.factuarea.com/v1/payouts/0192f3a4-7b2c-7e10-9c1a-1f2e3d4c5b6a" \
  -H "Authorization: Bearer fact_test_…"

Retorna 404 si el payout no existeix o pertany a una altra empresa.

L'esdeveniment sortint

Quan un payout es concilia, Factuarea emet l'esdeveniment payout.reconciled. El seu payload porta el snapshot complet del payout (object) més l'import net, la divisa i la referència de la transacció bancària, de manera que un receptor de webhooks pugui tancar la seva pròpia comptabilitat en el moment en què els diners es confirmen al banc. Subscriu-t'hi com a qualsevol altre esdeveniment — vegeu Webhooks i Esdeveniments.

No existeix un scope payouts:write: els payouts s'observen, mai es muten, a través de l'API. L'únic canvi d'estat — la conciliació — es dispara des del Dashboard contra el teu extracte Norma 43, i l'esdeveniment és el que notifica a la teva integració.