User Credit Balances: The Loan or Line of Credit You Report

A user credit balance is the loan or line of credit you extend to one of your customers. It records the product’s terms at creation and the position you report as your customer draws, accrues, and repays. You create user credit balances, update their terms, and manage their status through the User Credit Balances API. You are the ledger of record. A user credit balance is Lead’s copy of what your ledger shows, so Lead expects you to report every change to it until it reaches a closed state. A user credit balance is not a user account. The user account holds who the customer is and the compliance data Lead needs. The user credit balance sits beneath the user account and reflects the amount of credit extended (i.e. amount owed) at any given point in time. One user account can hold several user credit balances, for example a term loan and a line of credit. The creation of a user credit balance for your end-user first happens in your system, and the user credit balance record is how you provide Lead visibility into the balance you are tracking in your system as it is updated. See Executing vs. Reporting. A user credit balance is also not a core balance. Core balances are the positions in your program’s bank accounts at Lead, such as your FBO and operating accounts, and are documented under Core Balance.

​

Where it fits in onboarding

Create a user credit balance after its user account exists and before any money moves. When you create a user credit balance, Lead validates it against its parent user account. Lead rejects the request if the user account:

• Does not exist.
• Is not active.
• Has neither the credit_with_underwriting nor the credit_without_underwriting feature.

​

Two structures

Every user credit balance has a details.structure that you set on create and cannot change:

• non_revolving. A term loan or buy now, pay later loan. The principal is fixed, and repayments do not restore available credit. Open one user credit balance per loan.
• revolving. A line of credit or credit card. The user credit balance stays open across many draws and repayments, and repayments restore available credit.

The structure sets which terms are required. The User Credit Balance Object page lists them.

​

How the position updates

You never set amounts on a user credit balance directly. You post user credit transactions, and Lead applies each one to the user credit balance’s amount, amount_breakdown, the rewards subobject, the dispute subobject, and the charge_off subobject. Lead applies user credit transactions asynchronously. A GET request right after you post a user credit transaction can return the position from before that user credit transaction. The past_due subobject is the exception. No user credit transaction moves it, so you report it with PATCH.

​

How user credit balances relate to the rest of the model

• User accounts. Every user credit balance references a user_account_id. Create the user account first.
• User credit transactions. Every user credit transaction references the user_credit_balance_id it affects.
• Fundings. A funding draws against a user credit balance. On a non_revolving user credit balance, the total principal across fundings cannot exceed details.max_funding_amount.
• Receivables. Lead tracks the credit it holds on a user credit balance as a receivable. Receivable sales move that receivable to a buyer.
• User deposit balances (coming soon). A user account can also hold user deposit balances. They are separate objects with their own lifecycle.

​

What you can do

• POST /v2/user_accounts/{user_account_id}/user_credit_balances: Create a user credit balance.
• GET /v2/user_credit_balances/{id}: Retrieve a user credit balance.
• GET /v2/user_credit_balances: List your user credit balances. See Listing user credit balances.
• PATCH /v2/user_credit_balances/{id}: Update the terms and the past-due position you are allowed to change.
• POST /v2/user_credit_balances/{id}/activate: Move an inactive user credit balance to active.
• POST /v2/user_credit_balances/{id}/deactivate: Move an active user credit balance to inactive.
• POST /v2/user_credit_balances/{id}/close: Close the user credit balance.
• POST /v2/user_credit_balances/{id}/stop_reporting: Stop reporting on the user credit balance.

​

Listing user credit balances

GET /v2/user_credit_balances returns your user credit balances with cursor pagination. Filter with these query parameters:

​

Authentication

• user_credit_balance/read_write for create, update, and the status endpoints. Also grants read access.
• user_credit_balance/read for the GET endpoints only. Use it when your integration only needs to read user credit balances.

​

What you cannot do

• Change amounts with PATCH. Post a user credit transaction instead. past_due is the only position you set with PATCH.
• Change the structure or the core terms. name, currency_code, details.structure, details.max_funding_amount, details.expected_finance_charge_amount, and interest.effective_apr are set at creation.
• Change status with PATCH. Use the activate, deactivate, close, and stop_reporting endpoints. See User Credit Balance Statuses.
• Mix old and new objects. User credit balances are designed to be adopted together with user accounts and user credit transactions. Your Lead team will coordinate your move.
• Subscribe to webhooks. All status changes are yours, so Lead emits no events for them.

​

In this section

• The User Credit Balance Object
• User Credit Balance Statuses