Postfund your integration with StripePrivate preview

Learn how to postfund Stripe for card spend.

As a Connect platform or Direct user, you can now accrue a negative Issuing balance on card spend and postfund Stripe at a later time. This means you can fund your Issuing balance after card authorizations are captured by the network (usually 1 day after the authorization is created), instead of prefunding your Issuing balance before any card spend occurs. Each day, Stripe notifies you of how much is owed and you can send a same-day wire to fund Stripe before the deadline. You need to fund Stripe by the deadline (usually 20:00 UTC) to avoid late fees and additional penalties.

Connect

If you’re postfunding a Connect Platform, your Connected Account behavior is the same as described in:

The relationship between your platform and your Connected Accounts doesn’t change. The primary difference is that instead of needing to prefund the aggregate spend of your Connected Accounts, you can postfund spend.

Before you begin

Establishment of a reserve (accessed only in the event of operational failure)
The ability to send wires from your bank

Card Program CreditPolicy

Stripe configures a CreditPolicy for your card program, which contains key information about your payment obligations and terms. Your card program CreditPolicy is different from the CreditPolicy you set on your connected accounts. Your card program CreditPolicy is set and controlled by Stripe and defines the following key fields:

credit_limit_amount: The maximum aggregate amount that can be spent across all of your Connected accounts (or account, in the case of a Direct user). Stripe determines this setting and you must contact Stripe to request an update. This is also known as your exposure limit.
required_reserve_amount: The minimum amount you’re required to hold in your reserve at Stripe.
credit_period_interval and credit_period_interval_count: Both fields describe the length of time that card spend can accrue before it becomes due. For your card program, the credit interval is 1 day, meaning you’ll owe Stripe daily.

You can retrieve the details of your card program CreditPolicy by calling the GET CreditPolicy API endpoint.

Command Line

GET /v1/issuing/credit_policy

Example response

{
  "livemode": true,
  "credit_limit_amount": 10000, // minor units
  "credit_limit_currency": "usd",
  "required_reserve_amount": 9000, // minor units
  "reserve_currency": "usd",
  "status": "active",
  "credit_period_interval": "day",
  "credit_period_interval_count": 1
  // other fields for upcoming/last effective attributes
}

Card Program FundingObligation

While your CreditPolicy defines the overall parameters of your postfunding program, your FundingObligation represents your current obligation to Stripe for card spend across all of your connected accounts (or account, in the case of a Direct user).

Every morning, Stripe sends an issuing_funding_obligation.updated webhook event containing the FundingObligation that you owe Stripe. For any given FundingObligation, the amount_outstanding value represents the amount you owe that day.

{
  "id": "icfo_123",
  "amount_total": 95000000, // minor units
  "amount_outstanding": 95000000, // minor units
  "amount_paid": 0,
  "currency": "usd",
  "status": "unpaid",
  "due_at": "timestamp_on_t1",
  "paid_at": "nil",
  "owed_to": "stripe",
  "finalized_at": "timestamp_on_t2",
  "grace_period_ends_at": "timestamp_on_t3",
  …,
}

Late payments

Every FundingObligation contains a due_at field that represents when the FundingObligation becomes due.

{
  "id": "icfo_123",
  "amount_total": 95000000, // minor units
  "amount_outstanding": 95000000, // minor units
  "amount_paid": 0,
  "currency": "usd",
  "status": "unpaid",
  "due_at": "timestamp_on_t1",
  "paid_at": "nil",
  "owed_to": "stripe",
  "finalized_at": "timestamp_on_t2",
  "grace_period_ends_at": "timestamp_on_t3",
  …,
}

Failing to pay your FundingObligation when it’s due:

Changes the FundingObligation status to past_due, triggering an issuing_funding_obligation.updated webhook event
Incurs a late payment fee as stated in your contract with Stripe

Multiple late payments over time can lead to additional penalties on your platform (for example a decrease in your card program exposure limit).

Identify how much you owe Stripe

Stripe posts a FundingObligation for your card program every day, including on weekends and holidays. The best way to make sure your account stays current and avoids late fees and penalties is to calculate your total amount owed each day based on the amount_outstanding value for all unpaid and past_due FundingObligations using a formula:

`total_amount_outstanding` = sum(unpaid FundingObligations)¹ + sum(past_due FundingObligations)²

¹sum(unpaid FundingObligations) is the total of all FundingObligations with status=unpaid.

²sum(past_due FundingObligations) is the total of all FundingObligations with status=past_due.

Weekend and holiday balances due on next business day

While a FundingObligation created on a weekday is due that same day, a FundingObligation created on a weekend or holiday is due on the next business day. This means, for a typical weekend, you’ll have three FundingObligations due on Monday, so it’s important to correctly aggregate your total amount owed to Stripe.

Pay off your FundingObligation

To fund Stripe daily based on the due_at timestamp for the total amount you owe, use any of the following methods:

Same-day wires: You can initiate a same-day wire from your bank to your Stripe Issuing balance to pay off a FundingObligation. Use the FundingInstructions API to retrieve the account and routing number for your Issuing balance, and use that as the destination for the wire.
Balance Transfers: Within the US, you can move money instantly from your Stripe payments balance to your Issuing balance and use it to pay off your FundingObligation through the Dashboard or the API (reach out to Stripe to be gated into the API).
Existing pre-funded Issuing balance: Stripe applies any pre-funded or over-funded amounts from the previous day to your next FundingObligation.

After Stripe receives the full amount owed on the FundingObligation, we update its status and amounts and trigger an issuing_funding_obligation.updated webhook event.

{
  "id": "icfo_123",
  "amount_total": 95000000, // minor units
  "amount_outstanding": 0,
  "amount_paid": 95000000, // minor units
  "currency": "usd",
  "status": "paid",
  "due_at": "timestamp_on_t1",
  "paid_at": "timestamp_of_payment",
  "owed_to": "stripe",
  "grace_period_ends_at": "timestamp_on_t2"
  …,
}

If you only pay a portion of the total amount due, Stripe updates the amounts, but the status remains unpaid, which is reflected in the issuing_funding_obligation.updated webhook event.

{
  "id": "icfo_123",
  "amount_total": 95000000, // minor units
  "amount_outstanding": 3000000, // minor units
  "amount_paid": 92000000, // minor units
  "currency": "usd",
  "status": "unpaid",
  "due_at": "timestamp_on_t1",
  "paid_at": "timestamp_of_payment",
  "owed_to": "stripe",
  "grace_period_ends_at": "timestamp_on_t2"
  …,
}

If the balance remains unpaid past the due_at deadline, the status becomes past_due, which triggers another issuing_funding_obligation.updated webhook event.

Get transactions for a FundingObligation

Retrieve the list of transactions that contribute to a FundingObligation by passing one of the following parameters in the List all transactions API request:

The funding_obligation_for_account parameter for Direct users
The funding_obligation_for_platform parameter for Platform users

Direct

Example response

{
  "object": "list",
  "url": "/v1/issuing/transactions",
  "has_more": false,
  "data": [
    {
      "id": "ipi_123",
      "object": "issuing.transaction",
      // various other fields
      "funding_obligation_for_platform": null,
      "funding_obligation_for_account": "ifo_123",
      // various other fields
    },
    {
      "id": "ipi_123",
      "object": "issuing.transaction",
      // various other fields
      "funding_obligation_for_platform": null,
      "funding_obligation_for_account": "ifo_123",
      // various other fields
    },
    {...}
  ]
}

Platform

Connect platforms need to specify the Stripe-Account header with a connected account ID. Use funding_obligation_for_platform to query by the platform FundingObligation or funding_obligation_for_account if you know a connected account’s FundingObligation.

Example response

{
  "object": "list",
  "url": "/v1/issuing/transactions",
  "has_more": false,
  "data": [
    {
      "id": "ipi_123",
      "object": "issuing.transaction",
      // various other fields
      "funding_obligation_for_platform": "ifo_123",
      "funding_obligation_for_account": "ifo_456",
      // various other fields
    },
    {
      "id": "ipi_123",
      "object": "issuing.transaction",
      // various other fields
      "funding_obligation_for_platform": "ifo_123",
      "funding_obligation_for_account": "ifo_789",
      // various other fields
    },
    {...}
  ]
}

Manage your reserve

You must post a reserve (called “Collateral” in your program agreement) at Stripe before you’re allowed to postfund card spend. Stripe holds the reserve in an account that is both owned and controlled by Stripe. Stripe holds the reserve as security against funds owed and draws from the reserve to pay off any past_due FundingObligations. You might be charged a late fee if Stripe draws from the reserve. Additionally, dipping into the reserve might cause Stripe to reduce your platform credit_limit_amount or increase your reserve requirement. To avoid this, fund your Stripe Issuing balance through wires or balance transfers before the due_at timestamp on the FundingObligation for your credit integration.

Get your reserve requirements

You can identify the required_reserve_amount in your CreditPolicy. You must push this amount to your reserve before you can start postfunding.

Command Line

GET /v1/issuing/credit_policy

Example response

{
  "livemode": true,
  "credit_limit_amount": 10000, // minor units
  "credit_limit_currency": "usd",
  "required_reserve_amount": 9000, // minor units
  "reserve_currency": "usd",
  "status": "active",
  "credit_period_interval": "day",
  "credit_period_interval_count": 1
  // other fields for upcoming/last effective attributes
}

Add funds to your reserve balance

Stripe supports pushing funds into the reserve balance. You can find the account details for your reserve in the FundingInstruction, which contains bank account and routing information for you to originate a funds transfer to.

Caution

This is a different set of instructions than what Stripe uses to fund your Issuing balance. The destination_balance for your reserve funding instructions are set as issuing_credit_reserved.

Example response

{
  "id": "fi_XYZ",
  "object": "funding_instruction",
  "livemode": "true",
  "currency": "usd",
  "bank_transfer": {
    "type": 'us_bank_account',
    "country": "US",
    "financial_addresses": [{
      "supported_networks": ['ach', 'domestic_wire_us'],
      "type": 'aba',
      "aba": {
        "account_number": "546475644",
        "bank_name": "Wells Fargo",
        "routing_number": "123456"
      },
    }]
  },
  "destination_balance": "issuing_credit_reserved",
  "funding_type": "bank_transfer",
}

Funds pushed (through a wire or ACH credit) to the bank account retrieved from the FundingInstructions land in your reserve balance. When the funds land, you’ll receive a topup.succeeded webhook notification.

{
  "id": "tu_XYZ",
  "object": "topup",
  "amount": 9000,
  "balance_transaction": "txn_123",
  "destination_balance": "issuing_credit_reserved"
  "created": 123456789,
  ...
}

Check your reserve balance

You can use the /v1/balance API to check your reserve balance at any time:

Example response

{
  "object": "balance",
  "available": [ ... ],
  "connect_reserved": [ ... ],
  "issuing": { ... },
  "issuing_credit_reserved": [
    {
    "amount": 9000,
    "currency": "usd"
    }
  ],
  "livemode": true,
  "pending": [ ... ]
}

Reserve withdrawal by Stripe

If you have a past_due FundingObligation, Stripe first draws from your reserve to pay off the FundingObligation. We use the issuing_funding_obligation.updated webhook to notify you, and the FundingObligation object is updated to show the amount paid off by your reserve. If your reserve is unable to pay off the full amount_outstanding on the FundingObligation, the FundingObligation remains past_due — see Past Due Funding Obligations for more details and implications.

The following shows a FundingObligation that’s fully paid by the reserve:

{
  "id": "icfo_123"
  "amount_total": 95000000, // minor units
  "amount_outstanding": 0,
  "amount_paid": 95000000, // minor units
  "amount_paid_from_reserve": 95000000, // minor units
  "currency": "usd",
  "status": "paid",
  "due_at": "timestamp_on_t1",
  "paid_at": "timestamp_of_payment_with_reserve",
  "owed_to": "stripe",
  "grace_period_ends_at": "timestamp_on_t2",
  …,
}

You’ll also see a BalanceTransfer object (and associated BalanceTransactions) representing the automated transfer of funds from your reserve balance to your Issuing balance.

Example response

{
  "id": "btr_1MinsBCq7itcH1tbDkk4sY8w",
  "object": "balance_transfer",
  "amount": 10000,
  "currency": "usd",
  "destination_balance": {
    "issuing": {
      "balance_transaction": "txn_123_inbound"
    },
    "type": "issuing"
  },
  ...
  "source_balance": {
    "issuing_credit_reserved": {
      "balance_transaction": "txn_123_outbound"
    },
    "type": "issuing_credit_reserved"
  }
}

Example response

{
  "id": "txn_123_outbound",
  "object": "balance_transaction",
  "amount": 100,
  "currency": "usd",
  ...
  "type": "balance_transfer_outbound",
  "balance_type": "issuing_credit_reserved",
  "reporting_category": "issuing_credit_reserved_funds"
}

{
  "id": "txn_123_inbound",
  "object": "balance_transaction",
  "amount": 100,
  "currency": "usd",
  ...
  "type": "balance_transfer_inbound",
  "balance_type": "issuing",
  "reporting_category": "issuing_credit_reserved_funds"
}

Replenish your reserve

If Stripe draws from your reserve to pay off a FundingObligation, you must replenish the funds in your reserve to the minimum reserve_amount on your CreditPolicy. Stripe generates a FundingObligation for the reserve that notifies you of the amount and time by which you must replenish the reserve. You’ll also receive an issuing_funding_obligation.created webhook. To replenish your reserve, you must push funds using the same reserve balance FundingInstruction used previously. You must replenish your reserve by the due_at timestamp on the FundingObligation.

{
  "id" : "fo_456",
  "object": "issuing.funding_obligation",
  "amount_outstanding": 10000,
  "amount_paid": 0,
  "amount_total": 10000,
  "currency": "usd",
  "status": "pending",
  "due_at": "timestamp_t1",
  "grace_period": "timestamp_t2",
  "balance_type": "issuing_credit_reserved"
  ...
}

Listening for updated reserve requirements

Your required reserve amount might change as your program scales, which results in an update to the required_reserve_amount field in your CreditPolicy. If your reserve requirement increases due to growth in your program, your exposure limit also scales appropriately. Listen for the issuing_credit_policy.updated webhook for notification of any changes.

Reserve requirement increases

When your reserve requirement increases (as denoted in your CreditPolicy), the process is similar to when your reserve requires replenishing. You receive a FundingObligation for the reserve, which must be paid by the time denoted in the FundingObligation.

{
  "id" : "fo_321",
  "object": "issuing.funding_obligation",
  "amount_outstanding": 2000,
  "amount_paid": 0,
  "amount_total": 0,
  "currency": "usd",
  "status": "pending",
  "due_at": "timestamp_t1",
  "grace_period": "timestamp_t2",
  "balance_type": "issuing_credit_reserved"
  ...
}

Reserve requirement decreases

When your reserve requirement decreases (as denoted in your CreditPolicy), we transfer the excess funds into your Issuing balance so you can decide whether you want to apply it forward to your spend or pay out to the bank account linked to your Issuing integration.

Overdue reserve obligations

If your reserve funding obligation becomes past_due (past the due_at time), we begin to decline transaction authorizations. If there’s an issue with your reserve payment, contact your account executive for escalation.

Card program available spend

Stripe doesn’t currently provide a field or balance that shows the amount your card program has available to spend. You can compute this number with the following formula:

available credit = `credit_limit_amount` + issuing balance (issuing balance may be negative due to additional spend allowed by the exposure limit)

Authorization declines when postfunding

When postfunding, authorizations could be declined due to:

past_due FundingObligations
Failure to replenish your reserve

Declines due to past_due FundingObligations

Stripe declines authorizations when a FundingObligation is past_due beyond the grace period defined in the grace_period_ends_at timestamp of the FundingObligation. Refer to the following example to find the grace_period_ends_at:

{
  "id": "icfo_123",
  "amount_total": 95000000, // minor units
  "amount_outstanding": 95000000, // minor units
  "amount_paid": 0,
  "currency": "usd",
  "status": "past_due",
  "due_at": "timestamp_on_t1",
  "paid_at": nil,
  "owed_to": "stripe",
  "grace_period_ends_at": "timestamp_on_t2",
  ...,
}

If the grace period has passed, Issuing authorizations are declined and issuing_authorization.created events are sent with the following:

{
  "id": "iauth_123",
  "object": "issuing_authorization",
  "approved": false,
  ...,
  "status": "closed",
  "request_history": [
    {
      "amount": 100, // minor units
      "approved": false,
      "reason": "past_due_funding_obligation_to_stripe",
      ...,
    }
  ]
}

Failure to replenish your reserve

Whenever Stripe draws from your reserve to pay off a FundingObligation, you have a grace period (usually 24 hours) to replenish it back to the full required_reserve_amount in your CreditPolicy. If you continue to spend without replenishing your reserve by the end of your grace period, Stripe declines Issuing authorizations and you receive the following issuing_authorization.created event:

{
  "id": "iauth_123",
  "object": "issuing_authorization",
  "approved": false,
  // other fields...
  "status": "closed",
  "request_history": [
    {
      "amount": 100, // minor units
      "approved": false,
      ...,
      "reason": "insufficient_reserve_balance",
    }
  ]
}

Enable purchase limit notifications for your platform

You can use your settings to enable email notifications to help monitor your platform purchase limit, which is the limit on the total spend across your platform. Your platform purchase limit is represented by the credit_limit_amount attribute in your Platform CreditPolicy object. By default, this email notification is turned on when your integration is enabled for live mode and the threshold is set to 25% of the credit_limit_amount attribute in your Platform CreditPolicy object. You receive an alert whenever your available spend falls below your set threshold.

To update these notifications in live or testing environments:

Visit your email notifications settings.
Under Issuing purchase limit, choose from two types of alerting options:
- No notifications Select this option to disable the email notifications for all recipients.
- Issuing purchase limit threshold Update this value by using the input field. This value is set to 25% by default.

The following table calculates the available spend for a platform when credit_limit_amount is set to 100 USD and issuing purchase limit alerting threshold set to 25%. (Assume the platform has an issuing balance of -80 USD.)

Terms	How it’s determined	Example platform
Available spend alerting threshold	The `credit_limit_amount` times the alerting threshold.	100 * 0.25 = 25 USD
Current available spend	The `credit_limit_amount` plus the current issuing balance (issuing balance is negative for credit spend).	100 - 80 = 20 USD
Platform is notified through email	When the current available spend is less than the available spend threshold.	The platform is alerted

You can configure recipients of these email alerts in your user profile by selecting Issuing purchase limit under Email preferences.