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

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

​

Where it fits in onboarding

Post user credit transactions once the user credit balance exists.

​

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

​

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