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

Open the wallet

Open the customer, select the Wallet tab, and click Top up wallet.

Wallet tab with the Top up wallet button

Configure the credits

Choose Purchased (the customer pays for these) or Free (goodwill or promotional), and enter the number of Credits. Optionally add a Note, an Expires on date, a Priority (a lower number is used sooner), and a Reference ID.For purchased credits, Invoice the customer raises an invoice for them. With it off, the credits are recorded as already paid.

Top up wallet dialog with purchased credits and Invoice the customer turned on

Confirm

Click Top up 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

Open the auto top-up settings

On the customer’s Wallet tab, click the ⋯ menu next to Debit wallet and select Auto top-up settings.

Set the trigger and amount

Turn on Top up automatically. In Below, enter the balance in credits that triggers a top-up, and in Add, the number of credits to add each time.

Set the cool-off and invoicing

Optionally set a Cool-off and its Unit to wait between top-ups. Keep Invoice each top-up on to charge the customer for the credits, or turn it off to grant them as free credits.

Save

Click Save to activate auto top-up.

Auto top-up dialog with the balance threshold, top-up amount, cool-off, and invoicing

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 choose Purchased and turn on Invoice the customer in the top-up dialog, Flexprice initiates the following flow:

Top-Up Initiated

You choose Purchased, turn on Invoice the customer, and click Top up

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 become available only after the invoice is paid. When the invoice payment status becomes Succeeded, the wallet balance is topped up. Confirm the payment from the invoice’s ⋯ menu in one of these ways:

Record payment opens the Record payment page. Enter the Amount, choose a Method such as Offline (recorded manually) for a payment made outside Flexprice, and click Create payment. The payment record supports tracking and reconciliation.
Update payment status opens the Update payment status dialog. Under New payment status, select Succeeded and click Update status. The invoice is marked paid in full without a payment record.
Copy hosted invoice link gives you a link to the hosted invoice page, where the customer can pay through your connected payment provider. The payment status updates when the provider confirms the payment. For Stripe, see Stripe Payment Link & Checkout.

Record payment page with the invoice, amount, and Offline method

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.

Bonus Credits on Top-Up

Purchased credit top-ups (PURCHASED_CREDIT_DIRECT and PURCHASED_CREDIT_INVOICED, including pay-first checkout) can grant an extra bonus credit alongside the purchase. Free credit top-ups never receive a bonus.

The bonus is resolved automatically from a slab table, or set directly on the request.

Each slab grants its bonus as one of two types:

flat : a fixed number of bonus credits, regardless of purchase size
percentage : a percentage of the credits being purchased

Automatic Slab-Based Bonus

Configure the Bonus Credits Topup Configuration setting with a table of slabs, each mapping a purchase threshold to a bonus:

PUT /v1/settings/bonus_credits_topup_config
{
  "value": {
    "enabled": true,
    "slabs": [
      { "threshold": "200", "operator": "gte", "bonus": { "type": "percentage", "value": "10" } },
      { "threshold": "100", "operator": "gte", "bonus": { "type": "flat", "value": "50" } }
    ]
  }
}

When a purchased credit top-up runs, Flexprice matches credits_to_add against the slabs and grants the bonus from the first one it clears:

A top-up of 250 credits clears the 200 threshold first and gets a 10% bonus (25 bonus credits)
A top-up of 150 credits does not clear 200 but clears 100, and gets a flat 50 bonus credits
A top-up of 50 credits does not clear any threshold and gets no bonus

Slabs are evaluated in list order and the first match wins, so slabs must be sorted descending by threshold. Only the gte operator is supported.

Manual Override

To grant a specific bonus instead of resolving it from slabs, set bonus_credits_to_add on the top-up request.

Setting bonus_credits_to_add grants that amount as-is and skips slab resolution entirely for that top-up. When the field isn’t set, Flexprice resolves the bonus from the slab table instead, and if no slab matches, no bonus is granted.

See the Top-Up Wallet API reference for the full request and response schema.

Bonus Credit Expiry

Bonus credits can expire independently of the purchased credits they came with. Set bonus_credits_expiry_date_utc (an RFC3339 UTC timestamp) on the request to expire the bonus at a specific time; it’s rejected if it’s in the past, and only takes effect when a bonus is actually granted.

If the request doesn’t set bonus_credits_expiry_date_utc, and the matched slab defines expiration_duration and expiration_duration_unit (DAY, WEEK, MONTH, or YEAR, both required together), the bonus expires that long after it’s granted instead. If neither is set, the bonus credits don’t expire.

How the Bonus Is Recorded

The bonus is not merged into the purchase. It is created as its own wallet transaction:

transaction_reason: PURCHASED_CREDIT_BONUS
parent_transaction_id: the ID of the purchase transaction it’s linked to
transaction_status: mirrors the purchase transaction’s status. For a direct top-up both complete immediately; for an invoiced or pay-first top-up, the bonus stays pending until the purchase transaction completes, then both complete together

The top-up wallet response only returns the purchase transaction in wallet_transaction. Bonus credits do not appear there. Look up wallet transactions filtered by parent_transaction_id or transaction_reason: "PURCHASED_CREDIT_BONUS" to see the bonus. Once both transactions complete, wallet.balance reflects the purchase and the bonus together.

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
Settings - Configure automatic bonus credit slabs
Top-Up Wallet API Reference - Full request and response schema

Start Here

Usage Metering

Pricing and Packaging

Entitlements

Customers

Subscriptions

Credits and Wallets

Enterprise Billing

Invoicing and Taxes

Payments and Checkout

Reporting and Data

Self-hosting

Platform and Security

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

Bonus Credits on Top-Up

Automatic Slab-Based Bonus

Manual Override

Bonus Credit Expiry

How the Bonus Is Recorded

​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

​Bonus Credits on Top-Up

​Automatic Slab-Based Bonus

​Manual Override

​Bonus Credit Expiry

​How the Bonus Is Recorded

​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

Bonus Credits on Top-Up

Automatic Slab-Based Bonus

Manual Override

Bonus Credit Expiry

How the Bonus Is Recorded

Related Documentation