> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# User Credit Transactions: The Activity You Report on a User Credit Balance

> What a user credit transaction is, how it moves a user credit balance, how reversals work, and what you can do with the User Credit Transactions API.

A user credit transaction is a single change to a user credit balance: a card purchase, a payment, a fee, an interest accrual, a dispute step, a charge-off, or a correction. You post one for every change your ledger records. Lead applies each one to the user credit balance and books the matching program-level accounting.

You are the ledger of record. A user credit transaction is Lead's copy of an entry in your ledger, so Lead expects you to post every entry on a user credit balance until the user credit balance reaches a terminal status.

The creation of a user credit transaction for your end-user typically first happens in your system (unless it is a record that Lead is creating on your behalf – e.g., in response to a funding request), and the user credit transaction record is how you inform Lead about a transaction that impacts the end-user's user credit balance. See [Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting).

A user credit transaction is not a core transaction. Core transactions are the ledger entries Lead creates on your program's core balances, such as your FBO and operating accounts, and are documented under [Core Transaction](/products/core-transaction/overview).

<Note>
  The User Credit Transactions API is currently in preview with a planned beta release in December 2026. Preview APIs are not yet available in sandbox or production and can change before beta. Use these pages to plan an integration, not to build one. Once released in beta, it will be available to all partners in sandbox, and in production for select programs. Beta APIs may change without a version increment, and changes will be announced in advance. See [Versioning and backwards compatibility](/core-concepts/platform/versioning-and-backwards-compatibility).
</Note>

## Where it fits in onboarding

Post user credit transactions once the user credit balance exists.

<Steps>
  <Step title="Entity API">
    Create an entity for each account holder, authorized signer, and authorized user.
  </Step>

  <Step title="Applications API">
    For underwritten credit products only. Report the final underwriting decision.
  </Step>

  <Step title="User Accounts API">
    Create the user account with the `credit_with_underwriting` or `credit_without_underwriting` feature.
  </Step>

  <Step title="User Credit Balances API">
    Create the user credit balance under the user account.
  </Step>

  <Step title="Funding API">
    Request a funding against the user credit balance to disburse to your customer, if your product uses it.
  </Step>

  <Step title="User Credit Transactions API">
    Report every disbursement (if not through the Funding API), accrual, fee, payment, and adjustment on the user credit balance.
  </Step>
</Steps>

## One state, and reversals instead of edits

A user credit transaction has one state, posted. It exists once Lead accepts it, and it has no `status` field and no lifecycle. You cannot delete a user credit transaction or change its amounts.

To undo a user credit transaction, call `POST /v2/user_credit_transactions/{id}/reverse`. Lead creates a new user credit transaction of the same `type` with every amount negated, and links the two. Use reversals for anything that undoes an entry you already posted, such as a refunded fee, a returned payment, or a payment you posted in error. See [Reversals](/v2/products/user-credit-transaction/user-credit-transaction-object#reversals).

A merchant refund on a card purchase is not a reversal. It is a new network event, so post it as a `card_network` user credit transaction with a negative `amount`.

## How a user credit transaction moves the user credit balance

You never set amounts on a user credit balance directly. Each user credit transaction carries a signed `amount` and an `amount_breakdown` that splits it into `principal`, `interest`, and `fees`. Lead reads the `type` and applies the amounts to the right blocks on the user credit balance.

* **Sign.** Amounts are signed from the user credit balance's point of view. A positive amount increases what your customer owes. A negative amount reduces it. A card purchase is positive, and a payment is negative.
* **Split.** `amount` must equal `principal + interest + fees`. Report how your ledger allocated each payment across the three. Lead does not apply a payment waterfall for you.
* **Routing.** Most types move only `amount_breakdown`. Dispute, charge-off, and rewards types also move, or only move, the `dispute`, `charge_off`, or `rewards` block. Any user credit transaction that carries `details.rewards` also moves `rewards`. [The User Credit Transaction Object](/v2/products/user-credit-transaction/user-credit-transaction-object#types) page lists what every type moves.

Lead applies user credit transactions asynchronously. A `GET` request on the user credit balance right after you post a user credit transaction can return the position from before that user credit transaction.

<Warning>
  Do not use the user credit balance to authorize spending. Your ledger stays the source of truth.
</Warning>

## When to post

Post each user credit transaction when your ledger records it. There is no daily cutoff and no empty submission on days without activity.

`effective_at` is when the user credit transaction affected the user credit balance on your ledger. It must fall in the current calendar quarter, in UTC. During the first 7 days of a quarter, it can also fall in the previous quarter. Lead rejects anything older, so report activity promptly.

## How user credit transactions relate to the rest of the model

* **User credit balances.** Every user credit transaction references the `user_credit_balance_id` it affects. You post it under that user credit balance's path.
* **Fundings.** When a funding disburses, Lead posts the `funding` user credit transaction for you and sets its `funding_id`. Do not post your own user credit transaction for the same disbursement. If you disburse outside the Funding API, post an `adjustment` with a positive `amount` instead.
* **Cards (coming soon).** A `card_network` user credit transaction can reference the card it was made on with `details.card_network.card_id`.
* **Receivables.** Lead tracks the credit it holds on a user credit balance as a receivable, and computes it from the user credit transactions you post.

## What you can do

* `POST /v2/user_credit_balances/{user_credit_balance_id}/user_credit_transactions`: Post a user credit transaction.
* `GET /v2/user_credit_transactions/{id}`: Retrieve a user credit transaction.
* `GET /v2/user_credit_transactions`: List your user credit transactions. See [List user credit transactions](/v2/products/user-credit-transaction/user-credit-transaction-object#list-user-credit-transactions) on The User Credit Transaction Object.
* `PATCH /v2/user_credit_transactions/{id}`: Update the description, metadata, and card settlement date.
* `POST /v2/user_credit_transactions/{id}/reverse`: Reverse a user credit transaction.

### Authentication

* **`user_credit_transaction/read_write`** for posting, updating, and reversing. Also grants read access.
* **`user_credit_transaction/read`** for the `GET` endpoints only. Use it when your integration only needs to read user credit transactions.

## What you cannot do

* **Change** `amounts`**, `type`, or `effective_at`.** Reverse the user credit transaction and post a new one.
* **Post to a user credit balance that is not `active`.** `card_network` user credit transactions are the exception. You can post them to `inactive` and `closed` user credit balances, because card networks settle after the fact. No user credit transaction posts to a `reporting_stopped` user credit balance.
* **Reverse a reversal, or reverse a user credit transaction twice.**
* **Reverse a user credit transaction Lead posted,** such as a `funding` user credit transaction.
* **Post a `funding` user credit transaction.** Lead posts it when a funding disburses. Report a disbursement made outside the Funding API as an `adjustment`.
* **Subscribe to webhooks.** You post every user credit transaction yourself, so Lead emits no events for them. To see what Lead has applied, retrieve or list user credit transactions.

## In this section

* [The User Credit Transaction Object](/v2/products/user-credit-transaction/user-credit-transaction-object)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.