Obligation amounts, transactions, and adjustmentsPrivate preview

View details about a FundingObligation and make adjustments.

Retrieve FundingObligations

Over time, a connected account will have multiple paid off (or past_due) FundingObligation instances and at most a single currently pending FundingObligation. To fetch the FundingObligation for the current period, run this command:

Example funding obligation response

[
  {
    "id": "ifo_123",
    "livemode": true,
    "created": 1654628149,
    "amount_total": 10000,
    "amount_outstanding": 10000,
    "amount_paid": 0,
    "currency": "usd",
    "status": "unpaid",
    "due_at": 1654714851,
    "owed_to": "acct_123",
    "credit_period_starts_at": 1654625149,
    "credit_period_ends_at":1654713851,
    "paid_at": nil,
    "finalized_at": 1654713860,
  },
]

To fetch FundingObligations with a particular status, pass in the specific status value when requesting a list of FundingObligations. This API call retrieves FundingObligations with a status of past_due:

Ledger adjustments to account obligations

With the Credit Ledger API, you can record and maintain insights into off-card transaction activity that occurs in the normal course of your business. Using the Credit Ledger APIs you can:

Account for off-card transaction activity to adjust the credit available and funding obligations
Retrieve an account’s available credit amount
Compile both adjustments and card spend activity into a single statement

Credit adjustments	Debit adjustments
Credit adjustments decrease the amount owed to you by a connected account. They increase the connected account’s available credit. Examples include: Refund Rewards and rebates FO repayment Out of policy expense repayment	Debit adjustments increase the amount owed to you by a connected account. They decrease the connected account’s available credit. Examples include: Credit adjustment reversals Excess CA payment remediation (includes credit balance refunds)

To demonstrate the process of applying adjustments to a connected account’s credit ledger, say that Barbell (one of Gymbox’s connected accounts) has a 1,000 USD credit limit, and one of their shift managers used their Barbell Charge Card to spend 10 USD on two protein bars for lunch. However, Barbell’s spend policy prohibits this type of personal expense and the cardholder needs to repay Barbell out of pocket through a payroll deduction.

The table below outlines the sequence of events on Stripe using the Credit Ledger API. All amounts and value changes reflected in this table are book transfers only. No real funds are moved during this process.

ACTION	BARBELL ISSUING BALANCE (CONNECTED ACCOUNT)	BARBELL FUNDINGOBLIGATION TO GYMBOX	BARBELL AVAILABLE CREDIT	GYMBOX ISSUING BALANCE (PLATFORM)
Barbell starts with a 0 USD balance and 100 USD prior spend. Gymbox started with a 10,000 USD balance that was decremented by 100 USD for a previously captured transaction.	0 USD	100 USD	900 USD	9,900 USD
The cardholder makes another 10 USD transaction, which is authorized because Gymbox’s Issuing Balance is large enough to cover the spend amount. Gymbox’s Issuing Balance decreases by 10 USD as a result of the authorization hold.	-10 USD	100 USD	900 USD	9,890 USD
During authorization clearing (usually the next day), Stripe: 1. Stripe clears the authorization, 2. Decreases Gymbox’s balance by 10 and increases Barbell’s by 10, and 3. Increment Barbell’s FundingObligation by 10 USD	0 USD	110 USD	890 USD	9,890 USD
Barbell receives the payment from their shift manager and transfers 10 USD back to Gymbox. Gymbox applies a corresponding 10 USD credit adjustment.	0 USD	100 USD	900 USD	9,890 USD
At the end of the credit period, Gymbox decides to give its long-term customer Barbell a 50 USD statement credit for their loyalty. Gymbox reports a 50 USD credit adjustment for Barbell.	0 USD	50 USD	950 USD	9,890 USD
Immediately after sending the credit adjustment, Gymbox realizes that they’ve given too big of a credit. To correct the statement credit, Gymbox reports a 20 USD debit adjustment to Barbell’s obligations.	0 USD	70 USD	970 USD	9,890 USD

Account for off-card transaction activity

Stripe automatically creates a credit ledger for all users onboarded to use Charge Card. Over time, a connected account will have accumulated spend through transactions and their FundingObligations and Available Credit will adjust based on that card spend activity. To apply an adjustment and create a corresponding credit ledger entry (for example, for a 50 USD customer loyalty reward credit), run this command:

Example response

{
  "id": "cla_1IC5a2ILABoM8KJZ2EgdP4Tb",
  "object_type": "issuing_credit_ledger_adjustment",
  "reason": "platform_issued_credit_memo",
  "reason_description": "Customer loyalty reward credited to account",
  "amount": 5000,
  "currency": "usd",
  "funding_obligation": "fo_12345",
  "livemode": false
}

Then, you can display to your customer a list of debit and credit adjustments made to their account in the current credit period. You can do so by calling the credit_ledger_adjustments endpoint with the stripe_account and funding_obligation parameters populated.

Example response

{
  "object": "list",
  "url": "/v1/issuing/credit_ledger_adjustments",
  "has_more": false,
  "data": [
    {
      "id": "icla_1IC5a2ILABoM8KJZ2EgdP4Tb",
      "object_type": "issuing_credit_ledger_adjustment",
      "created": 1605236462,
      "amount": 50000,
      "currency": "usd",
      "reason": "platform_issued_credit_memo",
      "funding_obligation": "fo_12345",
      "livemode": false
    },
    // ... more objects
  ]
}

To confirm that the amount_outstanding on the corresponding FundingObligation was reduced by the amount of the credit adjustment, retrieve the FundingObligation or listen to the issuing_funding_obligation.updated webhook.

Get spend activity for a FundingObligation

To compile a view of spend activity across card-based transaction authorizations, cleared transactions, repayments, and off-card transaction adjustments into a single statement, call the credit_ledger_entries endpoint. Specify an obligation ID within the funding_obligation request parameter.

Example response

{
  "object": "list",
  "url": "/v1/issuing/credit_ledger_entries",
  "has_more": false,
  "data": [
    {
      "id": "cle_1IC6b2ILABoM8KZz3EgtT9ka",
      "object": "credit_ledger_entry",
      "created": 1615292400,
      "amount": -80000,
      "currency": "usd",
      "funding_obligation": "fo_12345",
      "livemode": true,
      "source": {
        "issuing_transaction": "ipi_1Fq2s1ILABoM8KZjPhQNaz2s",
        "type": "issuing_transaction"
      }
    },
    {
      "id": "cle_1IC6b2ILABoM8KZz3EgwX7yp",
      "object": "credit_ledger_entry",
      "created": 1615206000,
      "amount": 20000,
      "currency": "usd",
      "funding_obligation": "fo_23456",
      "livemode": true,
      "source": {
        "issuing_credit_ledger_adjustment": "icla_1Fq8f2ILABoM8KZwSpPJz20F",
        "type": "issuing_credit_ledger_adjustment"
      }
    },
    // ... more objects if available
  ]
}

Card-based transactions will be marked with type issuing_transaction while adjustments will be marked with type issuing_credit_ledger_adjustment.

Alternatively, if you’re not making adjustments to the credit ledger, you can retrieve the list of transactions that contributed to a connected account’s FundingObligation by passing the funding_obligation_for_account parameter in the List all transactions API request:

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_789",
      "funding_obligation_for_account": "ifo_456",
      // various other fields
    },
    {...}
  ]
}

Summary of webhooks

As a reminder, you can monitor these three webhooks:

issuing_funding_obligation.created: Triggers whenever a FundingObligation is created, which happens around the beginning of each new credit period for the connected account.
issuing_funding_obligation.updated: Triggers whenever a FundingObligation is updated, which happens whenever the funding obligation changes status or amount fields, or has been updated to indicate repayment.
issuing_credit_ledger_adjustment.created: Triggers whenever a new adjustment to a FundingObligation is created.