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

***

## Collect Payment Before Credits Apply

The flow above finalizes an invoice and waits for you to record payment. If you would rather hand the customer a payment page and let a successful payment release the credits, add a `checkout` object to the top-up request:

```json theme={null}
POST /wallets/wallet_01KY1TRVGSC4YVB3XAMFV66EC5/top-up
{
  "credits_to_add": "500",
  "transaction_reason": "PURCHASED_CREDIT_INVOICED",
  "checkout": {
    "payment_provider": "razorpay",
    "success_url": "https://app.example.com/wallet/success",
    "cancel_url": "https://app.example.com/wallet/cancel"
  }
}
```

The wallet balance does not move. Flexprice creates a pending wallet transaction and a `DRAFT` invoice, then returns a payment link:

```json theme={null}
{
  "wallet": { "id": "wallet_01KY1TRVGSC4YVB3XAMFV66EC5", "balance": "100" },
  "wallet_transaction": {
    "id": "wtxn_01KY9HQ95BGBN77GZXZ45W6B6W",
    "transaction_status": "pending",
    "transaction_reason": "PURCHASED_CREDIT_INVOICED",
    "credits": "500"
  },
  "invoice_id": "inv_01KY9HBFHBX2JBD01QZTS109D2",
  "checkout_session": {
    "id": "cs_01KY9HRYQBMHN2NM718CX16Z1R",
    "checkout_status": "pending",
    "payment_action": {
      "type": "payment_link",
      "url": "https://rzp.io/l/XXXXXXX"
    }
  }
}
```

Redirect the customer to `checkout_session.payment_action.url`. When the payment succeeds, the invoice is finalized, the transaction moves to `completed`, and the 500 credits land in the wallet.

| Behavior                 | Detail                                                                                                                                                                  |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Supported reason         | `checkout` requires `transaction_reason: "PURCHASED_CREDIT_INVOICED"`. Any other reason returns a validation error                                                      |
| Auto-complete override   | If your environment has auto-complete enabled for purchased credit transactions, `checkout` overrides it. The transaction always stays pending until the payment clears |
| One session per wallet   | A second pay-first top-up on the same wallet is rejected while a session is open                                                                                        |
| If payment never happens | On failure or expiry the draft invoice and the pending transaction are archived, and the balance is unchanged                                                           |

<Note>
  `checkout` and the manual **Record Payment** flow are alternatives, not steps in sequence. Use `checkout` when you want the customer to pay through a hosted page; use the invoice flow when you settle payment yourself or out of band.
</Note>

To attempt a charge against a payment method the customer has already authorized instead of sending them to a payment page, see [Charge a saved payment method](/docs/checkout/pay-first-checkout#charge-a-saved-payment-method).

***

## 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
* [Pay-First Checkout](/docs/checkout/pay-first-checkout) - Gate a top-up behind a successful payment

***