Provide and reconcile reportsPrivate preview

The following balance transaction types are related to financing for your connected accounts, including merchant cash advances and loans.

• Payout: financing_payout
• Paydown: financing_paydown
• Reversal: financing_payout_reversal or financing_paydown_reversal

Payout

Each payout transaction has a Balance Transaction object with the type financing_payout. You can display payouts in any list of balance transactions or equivalent models you have in your platform’s UI.

Paydown

Each payout transaction has a Balance Transaction object with the type financing_paydown. To display withholding transactions in your platform’s UI:

1. Retrieve a balance transaction and filter by transaction type.
2. Provide the connected account’s account ID in the Stripe-Account header.

For example:

curl -G https://api.stripe.com/v1/balance_transactions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d type=financing_paydown

If you successfully retrieve the Balance Transaction’s list, you receive a response such as:

{
 "object": "list",
 "data": [
 {
  "id": "txn_abcdef123456",
  "object": "balance_transaction",
  "amount": -1550,
  "available_on": 123456789,
  "created": 123456789,
  "currency": "usd",
  "description": "Withheld funds from py_abcdef123456 to pay down flex loan flxln_abcdef123456",
  "exchange_rate": null,
  "fee": 0,
  "fee_details": [],
  "net": -1550,
  "reporting_category": "financing_paydown",
  "source": "cptxn_abcdef123456",
  "status": "available",
  "type": "financing_paydown"
 },
 ...
 ],
 "has_more": false,
 "url": "/v1/balance_transactions"
}

If this paydown occurred because of Capital withholding on the Stripe payment, the description field in the response refers to this Stripe payment. For example, a paydown might have a description of “Withheld funds from ch_123abc to pay down loan flxln_123abc”.

You can retrieve the applicable Financing Transaction object by expanding the source field of the Balance Transaction:

curl -G https://api.stripe.com/v1/balance_transactions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d type=financing_paydown \
  -d "expand[]"="data.source"

When expanded, the source field displays the Financing Transaction details:

{
 "object": "list",
 "data": [
 {
  "id": "txn_abcdef123456",
  "object": "balance_transaction",
  "source": {
     "id": "cptxn_1NAyja2eZvKYlo2CGPcd8FIX",
     "object": "capital.financing_transaction",
     "account": "acct_1032D82eZvKYlo2C",
     "created_at": 1684861854,
     "details": {
       "advance_amount": 10000,
       "currency": "usd",
       "fee_amount": 1000,
       "linked_payment": "ch_1032Rp2eZvKYlo2Cv6jPGmkF",
       "reason": "automatic_withholding",
       "total_amount": 11000,
       "transaction": {
         "charge": "ch_1032Rp2eZvKYlo2Cv6jPGmkF"
       }
     },
     ...
   },
  "status": "available",
  "type": "financing_paydown"
 },
 ...
 ],
 "has_more": false,
 "url": "/v1/balance_transactions"
}

Reversal

Each reversal transaction has a Balance Transaction object with either type: financing_payout_reversal or financing_paydown_reversal. A reversal can occur because of a failed ACH transaction, financing cancellation, or a manual reversal request. Providing reversal transactions serves two purposes:

• They can indicate cancelled financing. If you included the original financing payout in your reports, include any reversals. This way, connected accounts can see that both transactions cancel each other out.
• They can return previously withheld funds to a connected account’s balance.

Omitting reversals from your reports can cause reconciliation problems for connected accounts, because the reports might reflect inaccurate financing.

You can display paydowns in any list of balance transactions or equivalent models you might have in your platform’s UI. For example:

Existing reports: For existing reports that show a connected account’s individual transactions (including the application fee or interchange costs), consider adding a withholding amount to the report. New reports: For new reports, show all withholding amounts for a specific time period. This helps your connected accounts see how much of their sales processing is being applied toward their financing. For payout reports, you might want to include a sum total amount withheld. This helps connected accounts reconcile their total incoming sales processing, minus the withholding (and any application fees you charge), to arrive at the payout amount they expect to see in their external bank account.

For more information, see Payout reconciliation.

You can use a sandbox to create financing offers in various states for connected accounts.

To create test scenarios:

1. Create a sandbox in your test environment.

2. Generate test offers through the Capital Dashboard.

3. Update offers as delivered and simulate acceptance.

4. Test automatic payouts by approving and disbursing funds.

5. Test a payout or paydown. You can’t test a reversal because they’re initiated only by Stripe in specific circumstances.

   • Payouts
     1. Verify automatic payouts occur after offer acceptance
     2. Monitor capital.financing_transaction.created webhooks
     3. Confirm payout transactions appear in your reporting
   • Paydowns
     1. Test automatic withholding by processing test payments
     2. Simulate manual paydowns through the Capital dashboard
     3. Verify paydown transactions appear in your reporting integration

6. Confirm transaction details appear correctly in your reporting interface.

7. Verify webhook handling for transaction notifications.

8. Test account links or embedded components if implemented.

9. Validate transaction reconciliation processes.

After testing, manually send a live offer to verify your reporting before you enable automatic offers for all eligible connected accounts. To learn more, see Testing.