A refund returns funds to a customer after a successful payment. Nimbbl supports both full refunds (returning the entire payment amount) and partial refunds (returning a portion of the payment amount). Refunds are processed through the same payment partner that handled the original payment.
What is a Refund?
A refund reverses part or all of a completed payment. Each refund is linked to a specific payment and tracked with its own lifecycle. Multiple partial refunds can be issued against a single payment, as long as the total refunded amount does not exceed the original payment amount.
Refund Types
- Full refund — returns the entire payment amount to the customer. After a full refund, no further refunds can be issued against this payment.
- Partial refund — returns a specified portion of the payment amount. You can issue multiple partial refunds until the total refunded reaches the original payment amount.
Refund Lifecycle and States
Refunds start in Pending state when initiated:
| State | Description | Why It Moves | Possible Next States |
|---|---|---|---|
| Pending | Refund request created and queued for processing by the payment partner. | You initiated a refund (via Command Center or API) and Nimbbl sent the request to the payment partner. | Succeeded, Failed |
| Succeeded | Funds have been returned to the customer. | The payment partner confirmed the refund was processed. This is a terminal state. | — |
| Failed | Refund was rejected by the payment partner. | The payment partner could not process the refund -- common causes include insufficient settlement balance, expired refund window, or a transient partner error. This is a terminal state, though a delayed success may follow in rare cases. | Succeeded (rare) |
Why Failed can move to Succeeded
In rare cases, a refund initially reported as Failed may later be confirmed as successful through a delayed notification from the payment partner. Track refund status through webhooks to catch these delayed updates.
Refund Timeline
Refund processing time varies by payment mode, payment partner, and the customer's bank. As a general guideline, UPI and wallet refunds tend to be processed faster than card and netbanking refunds, but exact timelines depend on the specific payment partner and banking institution involved.
Processing Refunds
You can initiate refunds through two channels:
Refunding via Command Center
The Command Center provides a UI-based refund flow directly from the payment details screen. Navigate to the payment, select Issue Refund, choose between full and partial refund, and confirm the amount. For details on the UI flow, see Search Payments and Search Refunds.
Refunding via API
For automated or programmatic refunds, use the Refund API. Your server sends a refund request with the payment reference and the amount to refund:
- Identify the payment to refund (using the Payment ID)
- Call the Refund API with the refund amount (full or partial)
- Nimbbl processes the refund through the original payment partner
- Track the refund state through webhooks or the transaction enquiry API
Always track refund status through webhooks. Refund processing is asynchronous — the API response confirms that the refund was initiated, not that it was completed.
Handling Refund Failures
If a refund fails, check the failure reason in the refund details. Common causes include:
- Insufficient settlement balance — the payment partner requires sufficient settled funds to process the refund
- Refund window expired — some payment partners have a time limit for processing refunds
- Payment partner error — a transient error at the payment partner level
For failed refunds, you can retry the request or contact the payment partner through Nimbbl support.
Refund Attributes
Key attributes of a refund:
| Attribute | Description |
|---|---|
refund_id | Unique identifier for this refund (shown as Refund ID in Command Center) |
original_payment_transaction_id | The payment transaction this refund is against |
refund_request_id | Your reference ID for the refund request |
refund_amount | Amount being refunded |
refund_status | Current lifecycle state (Pending, Succeeded, Failed) |
transaction_type | full_refund or partial_refund |
refund_arn | Bank or acquirer reference number (available after success — customers can use this to trace the refund with their bank) |
error | Failure details when a refund fails |
SKU-Based Refunds
When an order includes line items, you can issue refunds at the SKU level — refunding specific items rather than an arbitrary amount. This allows precise tracking of which products were refunded and helps reconcile inventory and accounting.