Available credit and flow of fundsPrivate preview
Learn how funds flow and how to use the available credit amount field to prevent authorisation declines.
Retrieve an account’s available credit amount
Each time a customer makes a card-based transaction, or you record a credit or debit adjustment, the connected account’s available credit changes. Staying with Gymbox’s 50 USD reward credit example from above, Barbell’s available credit increased by 50 USD after applying the reward credit adjustment. You can confirm that increase and determine Barbell’s latest available credit by retrieving the account’s credit ledger using the following command:
Example response
{ "credit_limit": 100000, "amount_pending": 10000, "obligations": { "accruing": 5000, "unpaid": 15000 }, "credit_available": 97000, "prefunded_available": , "currency": "usd", "livemode": false }
Stripe recommends using the credit_ field returned when calling the credit_ endpoint. This approach ensures that you always show your customers the accurate credit amount they have remaining to spend. Together, credit_ and your customer’s Issuing balance determine what a connected account can spend at any time. Stripe also uses it to determine whether a transaction authorisation request will be approved or declined on the basis of available funds.
Authorisation declines because of a lack of available credit
Authorisations made on a connected account with a CreditPolicy could be declined for the following reasons:
The connected account attempts to spend beyond its available credit limit. In this instance, the connected account might have unpaid FundingObligations that have reduced its available credit. Make sure that your connected account’s FundingObligations are always up-to-date to prevent Authorisation declines.
Your available platform Issuing account reaches zero, and the available Issuing balance of your connected account is also at zero. Top up your Issuing account with sufficient funds to avoid declines.
Track the flow of funds
While it’s not necessary for giving your connected accounts access to a credit account, you might want to track the state of authorisations, transactions, and transfers created when a connected account spends funds extended from your platform.
Assume the following starting state:
| Account | Issuing balance |
|---|---|
| Gymbox Issuing Account (Platform) | 70 USD |
| Barbell Issuing Balance (Connected Account) | 0 USD |
Authorisations
Barbell, who has a CreditPolicy with a credit_ of 100 USD set up with Gymbox, spends 10 USD. This results in a 10 USD authorisation on Barbell’s account:
{ "id": "iauth_1JVXl82eZvKYlo2CPIiWlzrn", "object": "issuing.authorization", "amount": 1000, "currency": "usd", "approved": true, "authorization_method": "online", "balance_transactions": [ { "id": "txn_1234XYZ", "object": "balance_transaction", "amount": -1000, "type": "issuing_authorization_hold", ... } ], "card": {...}, ... }
Simultaneously, this generates a hold on Gymbox’s issuing balance for the same amount, ensuring that the funds are reserved and can’t be used for transactions by Gymbox’s other connected accounts:
{ "id": "txn_1Mgr6fXpL7qsPGZtDwrMkq3S", "object": "balance_transaction", "amount": -1000, "available_on": 1677682692, "created": 1677682692, "currency": "usd", "description": "Platform hold for authorization (account: acct_1MgC5JRcH5icH3Nz, authorization: iauth_1Mgr6dRcH5icH3NzezZCHnJF)", "exchange_rate": null, "fee": 0, "fee_details": [], "net": -1000, "reporting_category": "issuing_authorization_hold", "source": { "id": "iph_1Mgr6eXpL7qsPGZtAMb7x0N6", "object": "issuing.platform_hold", "amount": 1000, "currency": "usd", "originating_account": "acct_1MgC5JRcH5icH3Nz", "originating_authorization": "iauth_1Mgr6dRcH5icH3NzezZCHnJF", "originating_balance_transaction": "txn_1Mgr6dRcH5icH3NzYGRkgcn7" }, "status": "available", "type": "issuing_authorization_hold" }
The balance is now:
| Account | Issuing balance |
|---|---|
| Gymbox Issuing Account (Platform) | 60 USD |
| Barbell Issuing Balance (Connected Account) | -10 USD |
Transfers and transaction captures
Before Issuing authorisations are captured and Issuing transactions are created, funds are transferred to the connected accounts. Then, holds are released from the platform.
On Barbell’s account, the authorisation has been updated and closed, releasing the held funds:
{ "id": "iauth_1JVXl82eZvKYlo2CPIiWlzrn", "object": "issuing.authorization", "amount": 1000, "currency": "usd", "approved": true, "authorization_method": "online", "balance_transactions": [ { "id": "txn_1234XYZ", "object": "balance_transaction", "amount": -1000, "type": "issuing_authorization_hold", ... }, { "id": "txn_4t355646t54w2", "object": "balance_transaction", "amount": 1000, "type": "issuing_authorization_release", }, ], "card": {...}, "status": "closed", "transactions": [ { "id": "ipi_1032HU2eZvKYlo2CEPtcnUvl", "object": "issuing.transaction", "amount": -1000, "authorization": "iauth_1JVXl82eZvKYlo2CPIiWlzrn", "balance_transaction": "txn_1345r1KCr4trgtrg0WfNdUCbG1w", ... } ... }
The funds held on the platform’s account are also released:
{ "id": "txn_1Mgr6fXpL7qsPGZtDwrPz7bA", "object": "balance_transaction", "amount": 1000, "available_on": 1677682692, "created": 1677682692, "currency": "usd", "description": "Released platform hold for authorization (account: acct_1MgC5JRcH5icH3Nz, authorization: iauth_1Mgr6dRcH5icH3NzezZCHnJF)", "exchange_rate": null, "fee": 0, "fee_details": [], "net": 1000, "reporting_category": "issuing_authorization_hold", "source": { "id": "iph_1Mgr6eXpL7qsPGZtAMb7m8Z3", "object": "issuing.platform_hold", "amount": -1000, "currency": "usd", "originating_account": "acct_1MgC5JRcH5icH3Nz", "originating_authorization": "iauth_1Mgr6dRcH5icH3NzezZCHnJF", "originating_balance_transaction": "txn_1Mgr6dRcH5icH3NzYGR7bA4c" }, "status": "available", "type": "issuing_authorization_hold" }
Stripe transfers funds from Gymbox to Barbell’s Issuing account and a Transfer object is created:
{ "id": "tr_3JeQsp2eZvKYlo2C13DagtB0", "object": "transfer", "amount": 1000, "amount_reversed": 0, "balance_transaction": "txn_1032HU2eZvKYlo2CEPtcnUvl", "created": 1646912059, "currency": "usd", "description": null, "destination": "acct_1032D82eZvKYlo2C", "livemode": true, "metadata": {}, "reversals": { "object": "list", "data": [], "has_more": false, "url": "/v1/transfers/tr_3JeQsp2eZvKYlo2C13DagtB0/reversals" }, "reversed": false, "source_transaction": null, "issuing_transaction": "ipi_1032HU2eZvKYlo2CEPtcnUvl", "metadata": {}, "source_balance": { "type": "issuing", }, // New destination_balance returned field links to the BT on the connected account side "destination_balance": { "type": "issuing", "issuing": { "balance_transaction": "txn_123", }, }, // ... other fields ... }
This sequence of hold, release, and transfer happens before Stripe creates the associated Issuing transaction. The balance is now:
| Account | Issuing balance |
|---|---|
| Gymbox Issuing Account (Platform) | 60 USD |
| Barbell Issuing Balance (Connected Account) | 0 USD |
If there’s no original authorisation for a transaction and the connected account doesn’t have sufficient funds to cover it, the platform balance transfer and transaction creation flow still occurs.
Refunds
When a connected account receives a refund, Stripe attempts to determine whether it pertains to a transaction that’s funded from that connected account’s balance or the platform’s account. If Stripe determines that it’s funded from the connected account’s balance, the funds return to the connected account’s balance. If the transaction is funded from the platform’s account (for example, from the connected account’s credit line), the connected account’s FundingObligation reduces by that amount. The refund is then transferred to the platform’s account because the platform already paid Stripe for the transaction on behalf of the connected account.
Say that Barbell has a 100 USD FundingObligation. If the amount is refunded, then:
- Barbell’s
FundingObligationdecreases from 100 to 0 USD - The 100 USD is transferred to Gymbox’s Issuing account, increasing their platform balance by 100 USD
It’s possible for the amount_ on a FundingObligation to be negative, which happens if the only transaction in a credit period is a refund and there’s no other card spend. The FundingObligation indicates a status of Needs refund. A negative FundingObligation can occur if there’s card spend but the amount of total refunds is higher than the total card spend.
Disputes
When a customer disputes a credit spend transaction on a connected account, the dispute follows the process outlined in Issuing disputes. Lost disputes result in no action (no credits are issued to the connected account). Won disputes issue a credit to the connected account in the same manner as described in the Refunds section.
Authorisation declines
Authorisations made on a connected account with a CreditPolicy could be declined for the following reasons:
- The connected account attempts to spend beyond its available credit limit. In this instance, the connected account might have unpaid
FundingObligationsthat have reduced its available credit. Make sure that your connected account’sFundingObligationsare always up-to-date to prevent authorisation declines. - Your available platform Issuing account reaches zero, and the available Issuing balance of your connected account is also at zero. Top up your Issuing account with sufficient funds to avoid declines.