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.
The Manual Wallet Debit feature allows you to manually deduct credits from a customer’s wallet. This is essential for handling refunds, billing corrections, chargebacks, and other administrative adjustments.
Common Use Cases:
- Refunds: Process customer refunds for overcharges or billing errors
- Billing Adjustments: Correct incorrect credit allocations
- Chargebacks: Handle payment disputes and chargebacks
- Administrative Corrections: Fix manual entry errors or system issues
- Wallet Termination: Deduct remaining balance when closing a wallet
How Manual Debit Works
When you debit a wallet, Flexprice automatically:
- Validates Balance: Ensures sufficient credits are available before processing
- Consumes Credits: Deducts credits using a priority-based algorithm (see below)
- Updates Balance: Reduces the wallet balance by the debited amount
- Creates Transaction Record: Maintains a complete audit trail
- Triggers Alerts: Notifies you if the balance falls below configured thresholds
Credit Consumption Algorithm
Flexprice uses a smart Priority-Based FIFO algorithm to determine which credits to consume when processing a debit:
Consumption Order
Credits are consumed in the following order:
-
Priority (Lower number = Higher priority)
- Credits with priority 1 are consumed before priority 2
- Credits without priority are consumed last
-
Expiry Date (Earlier expiry first)
- Credits expiring sooner are consumed first to prevent waste
- Credits without expiry dates are consumed last
-
Credit Amount (Larger amounts first)
- Among credits with the same priority and expiry, larger amounts are consumed first
- This optimizes the number of transaction updates required
Example Scenario
Suppose a wallet has the following credits:
| Credits | Priority | Expiry Date | Status |
|---|
| 50 | 1 | 2024-03-01 | Available |
| 30 | 1 | 2024-03-01 | Available |
| 100 | 1 | 2024-03-15 | Available |
| 75 | 2 | 2024-02-20 | Available |
| 200 | None | None | Available |
- 50 credits from priority 1, expiring 2024-03-01
- 30 credits from priority 1, expiring 2024-03-01
- 70 credits from priority 1, expiring 2024-03-15 (partial)
The wallet will have 30 credits remaining from the third transaction, plus the untouched 75 and 200 credits.
Making a Manual Debit via Dashboard
You can easily debit credits from a customer’s wallet through the Flexprice dashboard:
Step 1: Navigate to the Wallet
- Go to Billing in the main navigation
- Select Customers from the billing section
- Select the customer whose wallet you want to debit
- Navigate to the Wallet tab
Step 2: Access Manual Debit
- Click the three-dot menu (⋮) in the top right corner of the wallet section
- Select Manual Debit from the dropdown menu
Step 3: Enter Debit Details
A “Manual Debit” dialog will appear with the following fields:
-
Credits to Deduct: Enter the number of credits you want to debit from the wallet
- The system will show a preview: “$X will be debited from the wallet”
-
Reference ID (Optional): Enter a unique reference ID for this transaction
- This serves as the idempotency key to prevent duplicate debits
- Useful for linking to invoices, tickets, or other reference systems
-
Click Submit to process the debit
Step 4: Verify the Transaction
After submitting:
- The wallet balance will be updated immediately
- The debit transaction will appear in the Transactions list
- You’ll see “-X credits” in the transaction history
Making a Manual Debit via API
Endpoint
POST https://api.cloud.flexprice.io/v1/wallets/{wallet_id}/debit
Request Parameters
| Parameter | Type | Required | Description |
|---|
credits | string | Yes | Amount of credits to debit (decimal format, e.g., “100.50”) |
transaction_reason | string | Yes | Reason code for the debit (see Transaction Reasons below) |
idempotency_key | string | Yes | Unique key to prevent duplicate debits |
description | string | No | Human-readable description of the debit |
metadata | object | No | Custom key-value pairs for additional context |
Transaction Reasons
Use appropriate transaction reason codes to categorize debits:
| Reason Code | Use Case |
|---|
MANUAL_BALANCE_DEBIT | Administrative corrections and manual adjustments |
Example Request
curl --request POST \
--url https://api.cloud.flexprice.io/v1/wallets/{id}/debit \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '{
"credits": 123,
"description": "<string>",
"idempotency_key": "<string>",
"metadata": {},
"transaction_reason": "MANUAL_BALANCE_DEBIT"
}'
Success Response
{
"id": "wallet_0123",
"customer_id": "cust_0123",
"name": "Prepaid Wallet",
"currency": "usd",
"balance": "1587",
"credit_balance": "1587",
"wallet_status": "active",
"auto_topup_trigger": "disabled",
"auto_topup_min_balance": "0",
"auto_topup_amount": "0",
"wallet_type": "PRE_PAID",
"config": {
"allowed_price_types": [
"ALL"
]
},
"conversion_rate": "1",
"alert_enabled": true,
"alert_state": "ok",
"created_at": "2025-11-05T13:41:59.256406Z",
"updated_at": "2025-11-14T15:55:38.19095Z"
}
Error Responses
| Error Code | HTTP Status | Description |
|---|
INSUFFICIENT_BALANCE | 400 | Wallet doesn’t have enough credits |
INVALID_CREDITS | 400 | Credits amount must be positive |
MISSING_IDEMPOTENCY_KEY | 400 | Idempotency key is required |
WALLET_NOT_FOUND | 404 | Wallet doesn’t exist |
WALLET_NOT_ACTIVE | 400 | Wallet is not in active status |
Example Error Response
{
"error": {
"code": "INSUFFICIENT_BALANCE",
"message": "insufficient balance",
"hint": "Insufficient balance to process debit operation",
"details": {
"wallet_id": "wallet_abc123",
"amount": "150.50",
"available_balance": "100.00"
}
}
}
Idempotency
The idempotency_key parameter is required and ensures that duplicate API requests (e.g., due to network timeouts) don’t result in multiple debits.
Best Practices for Idempotency Keys
- Use a unique identifier for each logical debit operation
- Include context in the key, e.g.,
refund_invoice_123_20240115
- Never reuse idempotency keys across different operations
Use Case Examples
Example: Administrative Correction
curl --location 'https://api.cloud.flexprice.io/v1/wallets/{id}/debit' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'x-api-key: sk_xxxxxxxxxxxx' \
--data '{
"idempotency_key": "Manual-adjustment-123",
"transaction_reason": "MANUAL_BALANCE_DEBIT",
"credits": 1
}'
Important Considerations
Balance Validation
Before processing a debit, Flexprice:
- Checks that the wallet has sufficient available credits
- Excludes expired credits from the calculation
- Returns an error if insufficient balance is found
Transaction Atomicity
All debit operations are atomic:
- Credits are consumed and wallet balance is updated in a single database transaction
- If any step fails, all changes are rolled back
- This ensures data consistency and prevents partial debits
Audit Trail
Every manual debit creates a complete audit trail:
- Transaction record with type
DEBIT
- Before and after balances
- Description and metadata
- Transaction reason
- Idempotency key for tracking
- Timestamp and user information
Alert Integration
After a debit, Flexprice automatically:
- Checks the wallet’s low balance alert threshold
- Triggers an alert if the new balance is below the threshold
- Notifies you through configured alert channels
Best Practices
💡 Always Use Idempotency Keys: Protect against duplicate debits by using unique idempotency keys for each operation
💡 Provide Clear Descriptions: Include descriptive text and metadata to make audit trails meaningful
💡 Choose Appropriate Reasons: Use the correct transaction reason code to categorize debits properly
💡 Validate Before Debiting: Check wallet balance before attempting large debits to avoid errors
💡 Handle Errors Gracefully: Implement proper error handling, especially for INSUFFICIENT_BALANCE errors
💡 Monitor Alert Notifications: Watch for low balance alerts after processing debits
Troubleshooting
Insufficient Balance Error
Problem: API returns INSUFFICIENT_BALANCE error
Solution:
- Check the wallet’s current balance before attempting the debit
- Verify that you’re not including expired credits in your calculation
- Consider splitting large debits across multiple operations if needed
Duplicate Idempotency Key Error
Problem: API rejects request due to duplicate idempotency key
Solution:
- Ensure each unique debit operation has a unique idempotency key
- Check if the previous operation with the same key completed successfully
- Generate new idempotency keys for each distinct operation
Wallet Not Active Error
Problem: API returns WALLET_NOT_ACTIVE error
Solution:
- Verify the wallet status is
ACTIVE
- Check if the wallet has been closed or suspended
- Reactivate the wallet if necessary before debiting
