Manage credit termsPrivate preview

Learn how to manage the credit terms for connected accounts.

Change a connected account’s credit terms by updating the CreditPolicy credit_limit_amount or credit_period_interval. You can also deactivate a connected account’s ability to spend funds supported by your platform’s Issuing account by setting status to inactive.

Update the credit limit

You can change a connected account’s credit limit by updating the CreditPolicy credit_limit_amount, but first you must report the underwriting decision through CreditUnderwritingRecord. If you try to update credit_limit_amount without first reporting the same amount through CreditUnderwritingRecord, you’ll get an error.

There are three scenarios to report underwriting decisions to change a credit limit through the CreditUnderwritingRecord API:

Approve an account’s request for a credit limit increase

If a connected account requests a higher credit limit, then first report their request as an application, and then report the decision to approve or reject.

Record the account’s request through the CreditUnderwritingRecord API’s create_from_application endpoint. Set the application’s purpose to credit_limit_increase, and use submitted_at to report the date and time the customer submitted their request. Even though this is an existing user, you must provide their name and email in the credit_user hash.

Example response

{
  "object": "issuing.credit_underwriting_record",
  "id": "cur_1NiHAD2eZvKYlo2CmWGpt5OX",
  "credit_user": {
    "name": "Barbell Gym",
    "email": "barbell-gym@gmail.com"
  },
  "created_from": "application",
  "application": {
    "purpose": "credit_limit_increase",
    "submitted_at": 1681138952,
    "application_method": "online"
  },
  "decision_deadline": 1683601352 // 30 days after submission
}

The second step is to approve or reject the application using the report_decision endpoint. Be sure to report the decision before the decision_deadline, which is 30 days after the customer submits their application.

To approve the application set the decision type to credit_limit_approved, and provide the approved amount.

To reject an application instead, follow the same steps above, but set the decision type to application_rejected and provide the reasons for rejection in application_rejected.reasons. For more details on this scenario, see Reject an application for an increased credit limit and report rejection reasons.

In each scenario, after reporting the decision, update credit_limit_amount with the CreditPolicy API to the same amount you approved.

This action triggers an issuing_credit_policy.updated webhook event and immediately updates the credit_limit_amount field on the CreditPolicy.

Example response

{
  "livemode": true,
  "credit_limit_amount": 200000, // 2,000.00 USD
  "credit_limit_currency": "usd",
  "credit_period_interval": "month",
  "credit_period_interval_count": 1,
  "days_until_due": 1,
  "last_effective_attributes": {
    "effective_until": 1681138965,
    "credit_limit_amount": 100000,
    "credit_period_interval": "month",
    "credit_period_interval_count": 1,
    "days_until_due": 1,
    "status": "active",
  },
  "upcoming_attributes": null
}

Update the credit period

The credit period that you set must always match the credit period that is defined in your bank-approved credit policy document. Before you can change a credit period through the API, you must first get approval through Stripe to adjust the credit period in your written credit policy document. You may also be required to send a change in terms notice to the population of impacted account holders. Please reach out to platform-compliance@stripe.com to collect the requisite approvals before taking any actions.

Once you’ve received approval from Stripe, follow the steps below to change a credit period in the CreditPolicy API. You don’t need to use CreditUnderwritingRecord when changing a credit period.

You can change a connected account’s credit period by updating the fields in the upcoming_attributes hash. You must pass in an effective_at timestamp when setting the upcoming_attributes to schedule when you want the changes to take effect.

Using our previous example, let’s say that Gymbox, a platform, decides to change their customer’s credit period interval from monthly to 15 days, and the platform wants this change to take effect at the start of the next month. The effective_at timestamp must be 10 digits and end in 00, because Stripe requires all changes through upcoming_attributes to take effect at 00:00 UTC.

The platform updates the connected account’s CreditPolicy as follows, using the upcoming_attributes hash:

Example response

{
  "livemode": true,
  "credit_limit_amount": 200000,
  "credit_limit_currency": "usd",
  "status": "active",
  "credit_period_interval": "month",
  "credit_period_interval_count": 1,
  "days_until_due": 1,
  "last_effective_attributes": {
    "effective_until": 1681138965, // time of previous update to credit period
    "credit_limit_amount": 200000,
    "credit_period_interval": "month",
    "credit_period_interval_count": 1,
    "days_until_due": 1,
    "status": "active",
  },
  "upcoming_attributes": {
    "effective_at": 1693526400, // 1st day of the next month, 00:00 UTC
    "credit_period_interval": "day",
    "credit_period_interval_count": 15,
    "days_until_due": 0,
  }
}

At the effective_at timestamp, the CreditPolicy will automatically update to what was in the upcoming_attributes hash, and the last_effective_attributes hash will update to reflect the values prior to the change.

Example response

{
  "livemode": true,
  "credit_limit_amount": 200000,
  "credit_limit_currency": "usd",
  "status": "active",
  "credit_period_interval": "day",
  "credit_period_interval_count": 15,
  "days_until_due": 0,
  "last_effective_attributes": {
    "effective_until": 1693526400, // 1st day of the next month, 00:00 UTC
    "credit_limit_amount": 200000,
    "credit_period_interval": "month",
    "credit_period_interval_count": 1,
    "days_until_due": 1,
    "status": "active"
  },
  "upcoming_attributes": null
}

This triggers an issuing_credit_policy.updated event. At the effective_at timestamp when the credit period changes take effect, the FundingObligation for the current period is finalized and a new FundingObligation is created to mark the start of a new credit period on the new credit terms.

Close the credit line and report the reasons

You can close the connected account’s credit line by following these two steps.

First, use the CreditUnderwritingRecord API to submit details of the decision through the create_from_proactive_review endpoint. Set the decision type to credit_line_closed and provide at least one reason, and you can provide up to four. These must be the “principal” reasons for rejecting the application and they must be consistent with the rejection reasons defined in your bank-approved credit policy. Closing a credit line is an adverse action, so sending a notice is required with the applicable reasons for closure.

Example response

{
  "object": "issuing.credit_underwriting_record",
  "id": "cur_1NiHAD2eZvKYlo2CmWGpt5OX",
  "credit_user": {
    "name": "Barbell Gym",
    "email": "barbell-gym@gmail.com"
  },
  "created_from": "proactive_review",
  "decided_at": 1681138952,
  "decision": {
    "type": "credit_line_closed",
    "credit_line_closed": {
      "reasons": ["debt_to_cash_ratio_too_high"]
    }
  },
  "decision_deadline": null // no deadline for proactive review
}

Next, set the account’s CreditPolicy status to inactive.

Example response

{
  "livemode": true,
  "credit_limit_amount": 200000,
  "credit_limit_currency": "usd",
  "status": "inactive",
  "credit_period_interval": "month",
  "credit_period_interval_count": 1,
  "days_until_due": 1,
  "last_effective_attributes": {
    "effective_until": "time_of_deactivation",
    "credit_limit_amount": 200000,
    "status": "active",
    "credit_period_interval": "month",
    "credit_period_interval_count": 1,
    "days_until_due": 1,
  },
  "upcoming_attributes": null
}

This status change triggers an issuing_credit_policy.updated event. When you deactivate a CreditPolicy, you’ll continue to receive FundingObligation updates for the next 31 days to account for any cleared Transactions, because authorizations that happened before deactivation can be captured up to 31 days later.

If the connected account’s issuing balance is below 0 (indicating the account owes money to Stripe) when you attempt to set CreditPolicy to inactive you’ll receive an error, and you should topup the balance to return it to zero in order to deactivate the CreditPolicy. After the CreditPolicy status is inactive, authorization attempts on the account’s cards are funded by the account’s issuing balance, and will be declined if the balance is insufficient.

Once you’ve closed the credit line by setting status to inactive, you can’t reopen the line by changing status back to active unless you receive a new application from the customer. In that case, follow the steps to report a new, approved credit application.

Revoke the card_issuing_charge_card capability

If you have stopped using your platform Issuing account to support a connected account because they no longer meet the underwriting criteria of your bank-approved credit policy or are in violation of the Terms of Service, leave their CreditPolicy inactive. You must also revoke the card_issuing_charge_card capability by un-requesting it.

You can request the card_issuing_charge_card capability again in the future for the same connected account if the user submits a new application by following the steps to set up a connected account with credit.

If the connected account maintains an active card_issuing capability, you can still issue cards for the connected account. However, you must add funds into the connected account’s Issuing balance for their cards to work.

Summary of webhooks

As a reminder, you can monitor these two webhooks:

issuing_credit_policy.created: Triggers whenever a CreditPolicy is created, which happens when the capability is requested for the connected account.
issuing_credit_policy.updated: Triggers whenever a CreditPolicy is updated, which can happen when the platform updates the connected account’s policy.