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

Access the Wallet

Navigate to the customer’s wallet and click Top-up Wallet in the top right corner

Configure Credit Amount

In the top-up dialog, select your credit type and enter the amount to add to the wallet

Confirm

Click Add Credits to complete the top-up

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

Enable Auto Top-Up

During wallet creation, toggle Recharge Wallet Automatically

Set Trigger Threshold

Define when auto top-up should activate (e.g., when balance falls below $100)

Configure Minimum Balance

Enter the minimum balance threshold that triggers automatic recharge

Define Top-Up Amount

Specify the amount to add when auto top-up is triggered (e.g.,

100,

500)

Save

Click Save changes to activate auto top-up

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:

Top-Up Initiated

You select Purchased Credits and enable Generate Invoice in the top-up dialog, then click Add Credits

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

Transaction Logged

A wallet transaction is created with status pending and transaction reason PURCHASED_CREDIT_INVOICED. The transaction is linked to the generated invoice

Credits Hold

Credits remain unavailable and are not added to the wallet balance. The wallet balance remains unchanged until payment is confirmed

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.

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 for configuration instructions.
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.

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

For complete transaction lifecycle details, check out Purchased Credits (Invoiced) in the Wallet Transactions documentation.

Payment Gateway Required — Payment recording requires a configured payment gateway. For Example, Refer to Stripe Connection Setup for configuration instructions.

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:

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:

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

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.

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.

Wallet Transactions - Monitor and manage all wallet transactions
Auto Top-Up Wallet - Configure automatic wallet recharging
Low Balance Alert - Set up balance threshold notifications
Pay-First Checkout - Gate a top-up behind a successful payment

Introduction

Getting Started

Connect

Event Ingestion

Product Catalogue

Scenarios

Customers

Checkout

Subscriptions

Wallet

Invoices

Webhooks

Settings

Collectors

Data Exports

RBAC

Cookbooks

AI Cost Tracking

Contributing Guide

Exportable UI

Manual Top-Up

Adding Credits Manually

Automatic Top-Up

Configuring Auto Top-Up

Credit Types Supported

Free Credits Top-Up

Purchased Credits Top-Up

Purchased Credit Top-Up (with Invoice)

How It Works

Credit Activation

When to Use Invoice-Based Top-Ups

Collect Payment Before Credits Apply

​Manual Top-Up

​Adding Credits Manually

​Automatic Top-Up

​Configuring Auto Top-Up

​Credit Types Supported

​Free Credits Top-Up

​Purchased Credits Top-Up

​Purchased Credit Top-Up (with Invoice)

​How It Works

​Credit Activation

​When to Use Invoice-Based Top-Ups

​Collect Payment Before Credits Apply

​Related Documentation

Manual Top-Up

Adding Credits Manually

Automatic Top-Up

Configuring Auto Top-Up

Credit Types Supported

Free Credits Top-Up

Purchased Credits Top-Up

Purchased Credit Top-Up (with Invoice)

How It Works

Credit Activation

When to Use Invoice-Based Top-Ups

Collect Payment Before Credits Apply

Related Documentation