> ## 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.

# The User Credit Transaction Object

> Field-level reference for the User Credit Transaction object, including every type and what it moves on the user credit balance, reversals, post and update rules, list filters, and the mapping from the Transactions file.

A user credit transaction is a single change to a user credit balance. You post one with `POST /v2/user_credit_balances/{user_credit_balance_id}/user_credit_transactions` and read it with `GET /v2/user_credit_transactions/{id}`.

```json theme={null}
{
  "id": "user_credit_transaction_2xYw8Rk5Lp9SuV4oA7cDeF2gH6j",
  "user_credit_balance_id": "user_credit_balance_2xYv7Pm4Kq8RtW3nZ6bCdE1fG5h",
  "funding_id": null,
  "type": "card_network",
  "description": "Blue Bottle Coffee",
  "currency_code": "USD",
  "amount": 2500,
  "amount_in_usd": 2500,
  "amount_breakdown": {
    "principal": 2500,
    "interest": 0,
    "fees": 0
  },
  "details": {
    "card_network": {
      "card_id": "card_2xYw7Qj4Ko8RtU3nZ6bCdE1fG5h",
      "bin": "411111",
      "card_network": "visa",
      "network_transfer_type": "card",
      "authorization_amount": 2500,
      "authorization_currency_code": "USD",
      "settlement_amount": 2500,
      "settlement_currency_code": "USD",
      "settlement_date": "2026-10-02",
      "merchant": {
        "name": "Blue Bottle Coffee",
        "city": "New York",
        "state": "NY",
        "country_code": "US",
        "mcc": "5812"
      }
    },
    "rewards": {
      "amount": 100,
      "unit": "points"
    },
    "fee_type": null,
    "reversal": {
      "original_transaction_id": "user_credit_transaction_2xYw8Rk5Lp9SuV4oA7cDeF2gHasd"
    }
  },
  "metadata": {},
  "effective_at": "2026-10-01T18:30:00Z",
  "created_at": "2026-10-01T18:30:05Z",
  "updated_at": "2026-10-01T18:30:05Z"
}
```

A user credit transaction has one state, posted. It exists once Lead accepts it, and it has no `status` field. Corrections are reversals: new user credit transactions with their own IDs. See [Reversals](#reversals).

## Fields

| Field | Type | Description |
| :- | :- | :- |
| `id` | string | Unique identifier, prefixed `user_credit_transaction_`. |
| `user_credit_balance_id` | string | The user credit balance this user credit transaction affects. Set from the post path. |
| `funding_id` | string | The funding that produced this user credit transaction. Set by Lead on `funding` user credit transactions. Set by you on `fee` user credit transactions. `null` otherwise. |
| `type` | enum | What happened on the user credit balance. Sets which blocks of the user credit balance move. See [Types](#types). |
| `description` | string | A human-readable description, for example the merchant name. At most 120 characters. |
| `currency_code` | string | ISO 4217 currency code. Must match the user credit balance's `currency_code`. `USD` only today. |
| `amount` | integer | Signed, in minor units. Positive increases what your customer owes. Negative reduces it. Must equal the sum of `amount_breakdown`. |
| `amount_in_usd` | integer | `amount` converted to USD, in minor units. Set by Lead. Equal to `amount` while `currency_code` is `USD`. |
| `amount_breakdown` | object | The same amount split into `principal`, `interest`, and `fees`, each a signed integer in minor units. All three are required. |
| `details` | object | Type-specific fields. See [The details block](#the-details-block). |
| `metadata` | object | String key-value pairs for your own use, such as your ledger's transaction ID. Lead does not read them. |
| `effective_at` | timestamp | When the user credit transaction affected the user credit balance on your ledger. RFC 3339. Must fall in the current calendar quarter in UTC, or in the previous quarter during the first 7 days of a quarter. |
| `created_at` | timestamp | RFC 3339, UTC. |
| `updated_at` | timestamp | RFC 3339, UTC. |

## Types

The `type` sets the rules for the amounts and which blocks of the user credit balance move. "Sign" is the required sign of `amount`. Any type that carries `details.rewards` also moves `rewards`. See [The details block](#the-details-block).

| Type | Use when | Sign | Moves on the user credit balance |
| :- | :- | :- | :- |
| `card_network` | Your customer made a card purchase, cash advance, or other card network transaction. Use a negative `amount` for a merchant refund. Requires `details.card_network`. | Any | `amount_breakdown` |
| `funding` | Lead disbursed a funding. Lead posts this type. You cannot. | Positive | `amount_breakdown` |
| `payment` | Your customer made a payment. Split it across `principal`, `interest`, and `fees` the way your ledger allocated it. | Negative | `amount_breakdown` |
| `fee` | You charged your customer a fee. Requires `details.fee_type`. `principal` and `interest` must be zero. | Positive | `amount_breakdown.fees` |
| `interest_accrued` | Interest accrued on the user credit balance. `principal` and `fees` must be zero. | Positive | `amount_breakdown.interest` |
| `client_credit` | You credited your customer's balance at your own decision, for example a goodwill credit. | Negative | `amount_breakdown` |
| `cancellation` | Your customer canceled the loan within its cancellation window and returned the funds. | Negative | `amount_breakdown` |
| `reallocation` | You moved an outstanding amount between `principal`, `interest`, and `fees` without changing the total. The three must net to zero. | Zero | `amount_breakdown` |
| `adjustment` | You disbursed credit outside the Funding API, or you corrected the outstanding balance for a reason no other type covers, for example a draw that moved no money. Use a positive `amount` for a disbursement. Use only when no other type fits. | Any | `amount_breakdown` |
| `dispute_provisional` | You gave your customer provisional credit while a dispute is open. | Negative | `amount_breakdown`, and increases the same amount in `dispute` |
| `dispute_won` | The dispute resolved in your customer's favor, so the provisional credit is final. | Negative | `dispute` only is reduced |
| `dispute_lost` | The dispute resolved against your customer, so you took back the provisional credit. | Positive | `amount_breakdown`, and removes the same amount from `dispute` |
| `charge_off` | You wrote off an outstanding amount as a loss under your charge-off policy. | Negative | `amount_breakdown`, and adds the same amount to `charge_off` |
| `charge_off_recovery` | You recovered money on an amount you had charged off. | Negative | `charge_off` only |
| `rewards_earned` | Your customer earned rewards. Requires `details.rewards` with a positive `amount`. | Zero | `rewards` only |
| `rewards_spent` | Your customer spent rewards on something other than their balance, for example a gift card. Requires `details.rewards` with a negative `amount`. | Zero | `rewards` only |
| `rewards_redeemed` | Your customer redeemed rewards against their balance. Requires `details.rewards` with a negative `amount`. | Negative | `amount_breakdown` and `rewards` |

### How the dispute and charge-off blocks move

The `dispute` and `charge_off` blocks track amounts that have left the outstanding balance but are not yet settled.

* A `dispute_provisional`for \$50 reduces `amount_breakdown` by `5000` and raises `dispute`by`5000`.
* A `dispute_lost` for \$50 raises `amount_breakdown` by `5000` and reduces `dispute`by`5000`.
* A `dispute_won` for \$50 reduces `dispute`by`5000` and leaves `amount_breakdown` alone, because the provisional credit already reduced it.

Charge-offs follow the same pattern. A `charge_off` moves the amount from `amount_breakdown` into `charge_off`. A `charge_off_recovery` reduces `charge_off` only.

Send `amount_breakdown` on every type, including `dispute_won` and `charge_off_recovery`. Lead applies the split to the `dispute` or `charge_off` block.

## The details block

| Field | Type | Description |
| :- | :- | :- |
| `card_network` | object | The card network fields. Required for `card_network`. See below. |
| `fee_type` | enum | The kind of fee: `periodic_maintenance`, `card`, `international_transaction`, `borrower_origination`, or `other`. Required for `fee`. |
| `rewards` | object | The change in the rewards balance. Required for `rewards_earned`, `rewards_spent`, and `rewards_redeemed`. Optional on every other type. See [The details block](#the-details-block). |
| `reversal` | object | Set by Lead on a reversal. Holds `original_transaction_id`, the user credit transaction this one reversed. You cannot send it. |

### details.card\_network

| Field | Type | Description |
| :- | :- | :- |
| `card_network` | enum | `visa`, `mastercard`, `amex`, `pulse`, `star`, `accel`, `maestro`, `interlink`, or `tabapay`. Required. |
| `network_transfer_type` | enum | `card` for a card purchase or refund, `oct` for a push to card, `aft` for a pull from card. Required. |
| `bin` | string | The card's Bank Identification Number, 6 to 8 digits. Required. |
| `card_id` | string | The card the transaction was made on. Required when `network_transfer_type` is `card`. |
| `authorization_amount` | integer | The amount authorized at the point of sale, in minor units. Required. |
| `authorization_currency_code` | string | ISO 4217. Required. |
| `settlement_amount` | integer | The amount settled with the network, in minor units. Required. |
| `settlement_currency_code` | string | ISO 4217. Required. |
| `settlement_date` | date | `YYYY-MM-DD`. The date the network settled the transaction. Optional on post. You can add or change it with `PATCH`. |
| `original_transaction_id` | string | For a merchant refund, the `card_network` user credit transaction it refunds. Optional. |
| `merchant` | object | `name`, `address_line_1`, `city`, `state`, `country_code`, `zip_code`, and `mcc`. When `network_transfer_type` is `card`, `name`, `country_code` (ISO 3166-1 alpha-2), and `mcc` (4 digits) are required. The rest are optional. |

### details.rewards

| Field | Type | Description |
| :- | :- | :- |
| `amount` | integer | The change in the rewards balance, in minor units or points. Must be positive for `rewards_earned`, and negative for `rewards_spent` and `rewards_redeemed`. Any sign on other types. |
| `unit` | enum | `USD` or `points`. |

Send both fields whenever you send `details.rewards`.

Lead adds `details.rewards.amount` to the user credit balance's `rewards` block on every type that carries it, not only the three rewards types. To report rewards your customer earned on a card purchase, send `details.rewards` on the `card_network` user credit transaction. You do not need a separate `rewards_earned` transaction. Use `rewards_earned` for rewards that are not tied to another user credit transaction, such as a sign-up bonus.

## Reversals

`POST /v2/user_credit_transactions/{id}/reverse` undoes a user credit transaction. No request body is needed. `Idempotency-Key` is required.

Lead creates a new user credit transaction and returns it with a `200`. The reversal:

* Has the same `type` as the original.
* Negates `amount`, every `amount_breakdown` field, `details.rewards.amount`, and the `details.card_network` authorization and settlement amounts.
* Sets `details.reversal.original_transaction_id` to the original.
* Sets `effective_at` to the time of the reversal.

Reversal has these limits:

* The user credit balance must be `active`. Otherwise Lead returns a `422` with `operation_not_allowed`.
* You can reverse a user credit transaction once. A second reversal with a new `Idempotency-Key` returns a `409` with `operation_not_allowed` and the ID of the existing reversal. Retrying with the same key returns the original reversal.
* You cannot reverse a reversal. To restore an amount, post a new user credit transaction.
* You cannot reverse a user credit transaction Lead posted, such as `funding`.

## Post and update

`POST /v2/user_credit_balances/{user_credit_balance_id}/user_credit_transactions` requires an `Idempotency-Key` header. Without one, a retried request posts a second user credit transaction and double-counts the amount on the user credit balance. See [Idempotency](/api-reference/using-the-api/idempotency).

The request body takes these fields from the object: `type`, `description`, `currency_code`, `amount`, `amount_breakdown`, `details`, `effective_at`, and `metadata`. Leave out everything else. Lead sets it, and rejects a request that sends it.

* `type`, `description`, `currency_code`, `amount`, all three `amount_breakdown` fields, and `effective_at` are always required.
* `amount` must equal `amount_breakdown.principal + amount_breakdown.interest + amount_breakdown.fees`, and must have the sign the type requires. See [Types](#types).
* The user credit balance must be `active`. `card_network` user credit transactions can also post to `inactive` and `closed` user credit balances. Nothing posts to `reporting_stopped`. Otherwise Lead returns a `422` with `operation_not_allowed`.
* Reusing an `Idempotency-Key` with the same body returns the original user credit transaction. Reusing it with a different body returns a `422` with `idempotency_request_inconsistent`.

`PATCH /v2/user_credit_transactions/{id}` changes only the fields you send. You can change:

* `description`.
* `metadata`. Send `"metadata": null` to clear it.
* `details.card_network.settlement_date`, on `card_network` user credit transactions only.

Sending any other field returns a `422` with `immutable_field`. To change amounts, `type`, or `effective_at`, reverse the user credit transaction and post a new one. If another request changed the user credit transaction after yours was received, Lead returns a `409` with `object_modified_concurrently`. Retrieve it and retry.

## List user credit transactions

`GET /v2/user_credit_transactions` returns your user credit transactions with cursor pagination. Filter with these query parameters:

| Parameter | Type | Description |
| :- | :- | :- |
| `user_credit_balance_id` | string | Return only user credit transactions on this user credit balance. Use it to reconcile a user credit balance against your ledger. |
| `type` | enum | Return only this type. |
| `funding_id` | string | Return only user credit transactions linked to this funding. |
| `effective_at[after]`, `effective_at[on_or_after]`, `effective_at[before]`, `effective_at[on_or_before]` | timestamp | Return only user credit transactions effective in this range. RFC 3339. |
| `created_at[after]`, `created_at[on_or_after]`, `created_at[before]`, `created_at[on_or_before]` | timestamp | Return only user credit transactions posted in this range. RFC 3339. |
| `settlement_date[after]`, `settlement_date[on_or_after]`, `settlement_date[before]`, `settlement_date[on_or_before]` | date | Return only `card_network` user credit transactions settled in this range. `YYYY-MM-DD`. |
| `limit` | integer | The maximum number of user credit transactions to return. |
| `starting_after` | string | A `user_credit_transaction_` ID. Returns the page after this user credit transaction. |
| `ending_before` | string | A `user_credit_transaction_` ID. Returns the page before this user credit transaction. |

`GET /v2/user_credit_transactions/{id}` returns one user credit transaction. Lead returns a `404` if it does not exist.

## Coming from the Transactions file

The User Credit Transactions API replaces the daily Transactions file for credit balances. These are the fields that differ:

| Transactions file | User Credit Transactions API | What changed |
| :- | :- | :- |
| `client_transaction_id` | `id` (`user_credit_transaction_…`) | Lead generates the ID. Store it, because reversals and card refunds reference it. Keep your own ID in `metadata` if you need it. |
| `balance_id` | `user_credit_balance_id` (path) | The parent is now a user credit balance, set in the post path. |
| `currency` | `currency_code` | Renamed. |
| `amount`, `principal_amount`, `interest_amount`, `fee_amount` (decimals) | `amount`, `amount_breakdown.principal`, `interest`, `fees` (integers) | Integers in minor units. `1500` is \$15.00. |
| `rewards_amount`, `rewards_unit` | `details.rewards.amount`, `unit` | Moved. |
| `action` = `reversed` | `POST /v2/user_credit_transactions/{id}/reverse` | Reversals are an endpoint, linked to the original. |
| `type` = `disbursement` | `card_network` for card draws, `funding` for disbursements through the Funding API, or `adjustment` for any other disbursement | Card draws carry the network fields. Lead posts `funding` automatically. |
| `type` = `refund` | `card_network` with a negative `amount`, or a reversal | A merchant refund is a negative `card_network`. Undoing your own entry is a reversal. |
| `transfer_type` | `details.card_network.network_transfer_type` | Kept for card network transactions only. |
| `original_transaction_id` | `details.card_network.original_transaction_id`, or `details.reversal.original_transaction_id` | Split by use. Reversals set it for you. |
| Card and merchant columns | `details.card_network` and `details.card_network.merchant` | Grouped. |
| `settlement_date` | `details.card_network.settlement_date` | Card network transactions only. You can set it later with `PATCH`. |
| `interchange_fee_amount`, `transaction_fee_amount`, `acquirer_fee_amount` | — | Removed. |
| `transfer_ids`, `client_settlement_group_id`, `client_settlement_bank_account_id` | — | Removed. |
| `generated_at` | `created_at` | Set by Lead. |
| `fee_type` = `card`, `international_transaction` | `details.fee_type` | Adds `periodic_maintenance`, `borrower_origination`, and `other`. |
| Daily file by 6:00 a.m. CT, with an empty file on quiet days | Post each user credit transaction as it happens | No cutoff and no empty submissions. `effective_at` must fall in the current quarter. |

## Related

* [User Credit Transaction Overview](/v2/products/user-credit-transaction/overview)
* [The User Credit Balance Object](/v2/products/user-credit-balance/user-credit-balance-object)
* [User Credit Balance Statuses](/v2/products/user-credit-balance/statuses)
* [The Funding Object](/v2/products/fundings/funding-object)
* [Idempotency](/api-reference/using-the-api/idempotency)


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