> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flexprice.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Top-up wallet

Wallet top-ups allow you to add credits to customer wallets, ensuring continuous service availability. Flexprice supports two top-up methods: **manual top-up** for on-demand credit additions and **automatic top-up** for maintaining minimum balance thresholds.

***

## Manual Top-Up

Manual top-ups provide flexibility to add credits on demand. You can issue free credits for promotions and compensations, or process purchased credits through standard payment methods.

### Adding Credits Manually

<Steps>
  <Step title="Access the Wallet">
    Navigate to the customer's wallet and click **Top-up Wallet** in the top right corner

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/flexprice/public/images/docs/Wallet/Top-up%20wallet/top-wallet.png" alt="Screenshot 2025-03-12 at 6.19.40 PM.png" />
    </Frame>
  </Step>

  <Step title="Configure Credit Amount">
    In the top-up dialog, select your credit type and enter the amount to add to the wallet

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/flexprice/public/images/docs/Wallet/Top-up%20wallet/top-up-credit.png" alt="Screenshot 2025-03-12 at 6.20.01 PM.png" />
    </Frame>
  </Step>

  <Step title="Confirm">
    Click **Add Credits** to complete the top-up
  </Step>
</Steps>

***

## Automatic Top-Up

Automatic top-up ensures uninterrupted service by automatically recharging wallets when they fall below a specified threshold. This eliminates manual monitoring and prevents service disruptions due to insufficient balance.

### Configuring Auto Top-Up

<Steps>
  <Step title="Enable Auto Top-Up">
    During wallet creation, toggle **Recharge Wallet Automatically**
  </Step>

  <Step title="Set Trigger Threshold">
    Define when auto top-up should activate (e.g., when balance falls below \$100)
  </Step>

  <Step title="Configure Minimum Balance">
    Enter the minimum balance threshold that triggers automatic recharge
  </Step>

  <Step title="Define Top-Up Amount">
    Specify the amount to add when auto top-up is triggered (e.g., $100, $500)
  </Step>

  <Step title="Save">
    Click **Save changes** to activate auto top-up
  </Step>

  <Frame>
    <img src="https://mintlify.s3.us-west-1.amazonaws.com/flexprice/public/images/docs/Wallet/Top-up%20wallet/auto-top-up.png" alt="Screenshot 2025-03-12 at 6.20.01 PM.png" />
  </Frame>
</Steps>

***

## Credit Types Supported

Flexprice supports multiple credit types to accommodate different billing scenarios:

### Free Credits Top-Up

Promotional or complimentary credits added without requiring payment.

**Common use cases:**

* Welcome bonuses for new customers
* Promotional campaigns and special offers
* Service credits for issue resolution
* Customer loyalty and retention programs

### Purchased Credits Top-Up

Purchased credit top-up refers to credits that a customer buys. We support two types:

* **Purchased Credits** - Immediate credit addition
* **Purchased Credits (With Invoice)** - Invoice-based top-up with payment tracking

***

## Purchased Credit Top-Up (with Invoice)

The invoice-based top-up workflow provides comprehensive payment tracking and record-keeping for credit purchases.

### How It Works

When you select **Purchased Credits** and enable **Generate Invoice**, Flexprice initiates the following flow:

<Steps>
  <Step title="Top-Up Initiated">
    You select **Purchased Credits** and enable **Generate Invoice** in the top-up dialog, then click **Add Credits**
  </Step>

  <Step title="Invoice Created">
    An invoice is automatically generated and finalized with payment status `Pending`. The invoice contains the credit purchase details and is visible in your invoice list
  </Step>

  <Step title="Transaction Logged">
    A wallet transaction is created with status `pending` and transaction reason `PURCHASED_CREDIT_INVOICED`. The transaction is linked to the generated invoice

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/flexprice/public/images/docs/Wallet/Top-up%20wallet/transaction-before.png" alt="Screenshot 2025-03-12 at 6.20.01 PM.png" />
    </Frame>
  </Step>

  <Step title="Credits Hold">
    Credits remain unavailable and are not added to the wallet balance. The wallet balance remains unchanged until payment is confirmed
  </Step>

  <Step title="Record Payment">
    Credits get available only after the payment is followed through. When the invoice payment status becomes `Succeeded`, the wallet balance gets topped-up.

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/flexprice/public/images/docs/Wallet/Top-up%20wallet/record-payment.png" alt="Screenshot 2025-03-12 at 6.20.01 PM.png" />
    </Frame>

    You can either `Record Payment` or `Update Payment Status` directly to confirm payment.

    * **Record Payment** - A payment record is created for the invoice supporting tracking and reconciliation. Payment can be recorded through following methods:
      * **Offline Payment** - Record payment that was processed outside the system.
      * **Payment Link** - Generate a payment link for online payment. Payment status gets updated when payment is successfully processed through the payment gateway. If you want to know more about the `payment_link` behavior, check out [Stripe Payment Link & Checkout](/integrations/stripe/payment-links) for configuration instructions.
          <Frame>
            <img src="https://mintlify.s3.us-west-1.amazonaws.com/flexprice/public/images/docs/Wallet/Top-up%20wallet/top-up-payment-link.png" alt="Screenshot 2025-03-12 at 6.20.01 PM.png" />
          </Frame>
    * **Update Payment Status** - Invoice payment status changes from `Pending` to `SUCCEEDED` for API responses)
      After the payment is completed, the invoice status is updated to confirm successful payment.
  </Step>

  <Step title="Credits Available">
    Once payment is confirmed and the invoice is marked as paid:

    * Transaction status changes from `pending` to `completed`
    * Credits are immediately added to the customer's wallet
    * Wallet balance is updated and credits become available for use

    <Frame>
      <img src="https://mintlify.s3.us-west-1.amazonaws.com/flexprice/public/images/docs/Wallet/Top-up%20wallet/transaction-after.png" alt="Screenshot 2025-03-12 at 6.20.01 PM.png" />
    </Frame>
  </Step>
</Steps>

For complete transaction lifecycle details, check out [Purchased Credits (Invoiced)](/docs/wallet/transactions#purchased-credits-invoiced) in the Wallet Transactions documentation.

<Warning>
  **Payment Gateway Required** — Payment recording requires a configured payment gateway. For Example, Refer to [Stripe Connection Setup](/integrations/stripe/connection-setup) for configuration instructions.
</Warning>

### Credit Activation

Once payment is recorded and the invoice is marked as paid:

* Credits are immediately added to the customer's wallet
* Transaction status updates to `completed` in wallet history
* Credits become available for immediate use

### When to Use Invoice-Based Top-Ups

**Financial Record Keeping**

* Maintain detailed audit trails for all credit purchases
* Separate wallet top-up revenue from service charges
* Generate comprehensive transaction histories for accounting

**Enterprise Workflows**

* Support purchase order and approval processes
* Enable invoice-based payment for corporate customers
* Provide formal documentation for business expense tracking

**Compliance and Reporting**

* Meet regulatory requirements with detailed financial records
* Generate reports for credit purchase analysis
* Track customer acquisition and spending patterns

***

## Related Documentation

* [Wallet Transactions](/docs/wallet/transactions) - Monitor and manage all wallet transactions
* [Auto Top-Up Wallet](/docs/wallet/auto-top-up) - Configure automatic wallet recharging
* [Low Balance Alert](/docs/wallet/low-balance-alert) - Set up balance threshold notifications

***