User Credit Balance Statuses

You manage user credit balance status. New user credit balances start in active, and you move them with the activate, deactivate, close, and stop_reporting endpoints. This page explains what each status means, what each transition checks, and which reasons each one accepts. Lead expects you to report every change to a user credit balance until it reaches one of these statuses: closed or reporting_stopped.

Lifecycle

The dashed lines are error correction only. See Correcting a mistaken status change below.

Statuses

Status	Description	Notes
`active`	The user credit balance is open, and the customer can draw on it or repay it.	Every new user credit balance starts here.
`inactive`	You have paused the user credit balance, and you expect it may reopen.	Use this for dormant or frozen credit. You can still update the user credit balance with `PATCH`. The User Credit Transaction Object page lists which user credit transactions Lead accepts while a user credit balance is not `active`.
`closed`	The credit is finished: repaid or charged off.	Lead sets `closed_at`. You cannot update a closed user credit balance. It stays readable. To correct a mistaken close, see below.
`reporting_stopped`	You no longer report on the user credit balance to Lead.	You cannot update the user credit balance or post user credit transactions to it. It stays readable.

Transitions

Endpoint	From	To	Request body
`POST /v2/user_credit_balances/{id}/deactivate`	`active`	`inactive`	`status_reason` required
`POST /v2/user_credit_balances/{id}/activate`	`inactive`, or `closed` or `reporting_stopped` to correct a mistake	`active`	None
`POST /v2/user_credit_balances/{id}/close`	`active` or `inactive`	`closed`	`status_reason` required
`POST /v2/user_credit_balances/{id}/stop_reporting`	`active` or `inactive`	`reporting_stopped`	`status_reason` required

Send the reason as JSON, for example:

{ "status_reason": "paid_off" }

You cannot change status with PATCH. Every status endpoint is safe to retry. Calling an endpoint on a user credit balance that is already in the target status returns the user credit balance unchanged. Calling deactivate on a closed or reporting_stopped user credit balance returns an error. Only activate works on them, and only to correct a mistake.

Checks before close

Lead checks the outstanding position against the status_reason you send:

charged_off requires a non-zero charge_off.amount. The outstanding amount_breakdown can stay above zero, because the customer may still owe it.
Every other reason requires amount_breakdown.principal, amount_breakdown.interest, and amount_breakdown.fees to all be zero. Post the final payment as a user credit transaction, wait for it to apply, then close.

If the check fails, Lead returns a 422 with operation_not_allowed.

Checks before stop_reporting

Lead must not hold any receivable on the user credit balance. If Lead still holds a receivable, the request returns a 422 with object_state_conflict. Use this status only when your Technical Account Manager has confirmed it applies to your program.

Status reasons

status_reason explains the current status. Active user credit balances return active. The deactivate, close, and stop_reporting endpoints each accept their own set of reasons. Lead rejects a reason that does not belong to the endpoint you call. Deactivate

Reason	Use when
`dormant`	The customer has not used the user credit balance for the inactivity period your program defines, so you paused it. Use this when you expect it to return to `active` once the customer uses it again.
`frozen`	You restricted the user credit balance while you investigate or resolve an issue, such as suspected fraud, a legal hold, or a compliance review. Reactivate it if the issue is resolved.
`other`	You paused the user credit balance for a reason that is neither inactivity nor a restriction. Use this only when `dormant` and `frozen` do not fit.

Close

Reason	Use when
`paid_off`	The customer repaid the full outstanding balance, and no further credit is available. Use this for loans repaid at maturity or early, and for credit lines closed after payoff.
`charged_off`	You wrote off the outstanding balance as a loss under your charge-off policy, typically after a period of delinquency. The customer may still owe it.
`client_closed`	You closed the user credit balance at your own decision, with nothing outstanding.
`entity_closed`	The customer asked to close the user credit balance, with nothing outstanding.
`canceled`	The user credit balance was canceled before any funds were drawn.

Stop reporting

Reason	Use when
`receivables_sold_to_partner`	Under Originate-to-Sell you continue reporting after each daily sale; `stop_reporting` is for the case where Lead has sold its remaining receivables and no longer needs the position, which your Technical Account Manager will confirm.
`data_not_available`	You can no longer report the position to Lead, and Lead holds no receivable on it.

Correcting a mistaken status change

If you closed a user credit balance or stopped reporting on it by mistake, call POST /v2/user_credit_balances/{id}/activate on it. No request body is needed. The user credit balance returns to active with status_reason active, and Lead clears closed_at. Then report any activity you missed with user credit transactions.

Use this only to fix a reporting error. If a user credit balance can resume in the normal course of business, deactivate it instead of closing it.

Relationship to the user account

A user credit balance’s status is separate from its user account’s status. Closing or deactivating the user account does not change the status of the user credit balances beneath it. Manage each user credit balance separately.

Products

Banking Infrastructure

Customers & Accounts

Balances and Transactions

Lending & Receivables

Payment Rails

Lifecycle

Statuses

Transitions

Checks before close

Checks before stop_reporting

Status reasons

Correcting a mistaken status change

Relationship to the user account

​Lifecycle

​Statuses

​Transitions

​Checks before close

​Checks before stop_reporting

​Status reasons

​Correcting a mistaken status change

​Relationship to the user account

​Related

Lifecycle

Statuses

Transitions

Checks before close

Checks before stop_reporting

Status reasons

Correcting a mistaken status change

Relationship to the user account

Related