Stripe Settlement Mapping

Status: WIP

This guide explains how Stripe settlement data relates to instellix Settlement Reports and Settlement Items.
For concepts and the amount model, see Settlements.
For Stripe provider setup, see Payment Provider Stripe.

How Stripe settlements enter instellix

With Stripe configured in Integration > Payment Providers > Stripe, instellix retrieves settlement data automatically via the Stripe API (Balance Transactions), using the same secret key as for charging. No separate report user is required (unlike Adyen).
instellix creates Settlement Reports and Settlement Items from those balance movements for categorization, payment assignment, and accounting.

Balance Transactions → Settlement Items

Stripe Balance Transactions represent funds moving through the Stripe account. Typical types include payments, refunds, disputes/chargebacks, payouts, and fees.
instellix maps these movements into Settlement Items on the linked Merchant Payment Account. Important operational notes:

• stripe_fee appears as its own balance movement and is captured as fee-related settlement data (do not ignore fee lines when reconciling).
• advance / advance_funding form a netting pair and can be treated as a paired movement for reconciliation purposes.
• Chargebacks / disputes may appear as separate balance transactions (dispute + related fee). Chargeback-related fees are mapped so fee amounts are available for chargeback fee handling in the portal where enabled.
  Exact type-by-type field mapping for custom API push is provider-connector internal. Prefer automatic intake.

Amount model reminder

When creating Settlement Items via API (custom / hybrid):

• baseAmount = gross in settlement currency (MPA currency)
• originalAmount = amount in original transaction currency (if different)
• fees[] separately — do not put “net after fees” into baseAmount
  See Settlements.

Related articles

• Settlements
• Payment Provider Stripe
• Adyen Settlement Mapping
• Create settlement item