The User Credit Transaction Object

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

{
  "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.

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

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_provisionalfor $50 reduces amount_breakdown by 5000 and raises disputeby5000.
A dispute_lost for $50 raises amount_breakdown by 5000 and reduces disputeby5000.
A dispute_won for $50 reduces disputeby5000 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.
`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. 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.
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.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Fields

Types

How the dispute and charge-off blocks move

The details block

details.card_network

details.rewards

Reversals

Post and update

List user credit transactions

Coming from the Transactions file

​Fields

​Types

​How the dispute and charge-off blocks move

​The details block

​details.card_network

​details.rewards

​Reversals

​Post and update

​List user credit transactions

​Coming from the Transactions file

​Related

Fields

Types

How the dispute and charge-off blocks move

The details block

details.card_network

details.rewards

Reversals

Post and update

List user credit transactions

Coming from the Transactions file

Related