A payment represents a single attempt to collect money against an order. Each payment uses one payment mode (Cards, UPI, Netbanking, Wallets, EMI, or Pay Later) and is routed through one payment partner. Multiple payments can be attempted against the same order if earlier attempts fail.
What is a Payment?
Payment Definition
A payment captures the details of a single payment attempt: the payment mode used, the amount, the payment partner that processed it, and the outcome. Nimbbl assigns a unique transaction_id to each payment.
Every payment is linked to exactly one order. When a payment succeeds, its parent order moves to Completed state. When a payment fails, the order can remain in Pending state to accept further attempts.
Payment Lifecycle and States
A payment moves through these states during processing:
| State | Description | Why It Moves | Possible Next States |
|---|---|---|---|
| New | Payment attempt created, not yet sent to the payment partner. | Nimbbl creates the payment record when the customer initiates a payment attempt. | Pending, Failed |
| Pending | Payment is being processed by the payment partner. The customer may be completing authentication (OTP, UPI approval, bank redirect). | The payment has been sent to the payment partner for processing. Nimbbl is waiting for a response. | Succeeded, Failed, Reversing |
| Succeeded | Funds have been collected. The parent order moves to Completed. | The payment partner confirmed the payment was authorized and captured. This is a terminal state. | — |
| Failed | Payment was declined or encountered an error. | The payment partner declined the transaction, the customer abandoned authentication, or a timeout occurred. This is a terminal state, though a delayed success or reversal may follow in rare cases (see below). | Succeeded (rare), Reversing (rare) |
| Reversing | A reversal has been initiated and is being processed by the payment partner. | The payment succeeded after the authorisation period expired, triggering an automatic refund. See the authorisation period note below. | Reversed, Reversal Failed |
| Reversal Failed | The reversal attempt did not succeed. | The payment partner was unable to process the automatic refund. The system will retry for up to two days. You can also manually refund from Command Center or the Refund API. | Reversing (retry) |
| Reversed | The payment has been automatically refunded after succeeding past the authorisation period. | The automatic refund completed successfully. This is a terminal state. | — |
Sometimes payments do not succeed in real time -- they may succeed after a delay of minutes, hours, or even days. As a business, you can configure an authorisation period (between 5 minutes and 5 days) that defines how long you are willing to wait for a delayed success. If a payment succeeds after the authorisation period, Nimbbl automatically initiates a reversal (refund) because the order may have already been cancelled or re-attempted. Contact [email protected] to configure your authorisation period.
Why Failed can move to Succeeded or Reversing
In rare cases, a payment initially reported as Failed by the payment partner may later be confirmed as successful through a delayed notification. If this delayed success arrives within the authorisation period, the payment moves to Succeeded and the order is marked Completed. If it arrives after the authorisation period, the payment moves to Reversing and an automatic refund is initiated.
Payment Attributes
Key attributes of a payment:
| Attribute | Description |
|---|---|
payment_id | Nimbbl's unique payment identifier (shown as Payment ID in Command Center) |
order_id | The parent order this payment belongs to |
payment_mode | Payment mode used (e.g., UPI, Credit Card, Netbanking, Wallet) |
sub_payment_mode | Details within the payment mode (e.g., bank name for Netbanking, UPI app for Intent) |
payment_partner | Payment partner that processed the payment |
transaction_amount | Amount processed (may differ from order amount when charges apply) |
transaction_currency | Currency in which the payment was processed |
payment_status | Current payment state (New, Pending, Succeeded, Failed, Reversing, Reversal Failed, or Reversed) |
psp_transaction_id | Payment partner's reference ID (useful for reconciliation) |
payment_arn | Bank or acquirer reference number (customers can use this to trace the payment with their bank) |
additional_charges | Convenience fees or surcharges applied |
shipping_charges | Shipping charges, if applicable |
cod_charges | Cash on Delivery charges, if applicable |
offer_discount | Discount applied through offers |
offer_id | Identifier for the offer applied to the transaction |
emi | EMI details when the payment mode is Card EMI, Debit Card EMI, or Cardless EMI |
nimbbl_error_code | Error code when payment fails (nested in error object) |
nimbbl_consumer_message | Customer-friendly failure message |
nimbbl_merchant_message | Merchant-facing explanation of the failure |
retry_allowed | Whether the customer should be allowed to retry with the same payment mode |
Relationship to Orders and Refunds
- To Orders: each payment belongs to one order. An order can have many payment attempts, but only one payment can succeed. Once a payment succeeds, the order moves to Completed and no further attempts are accepted.
- To Refunds: refunds are processed against a succeeded payment. A payment can have one or more refunds (full or partial), as long as the total refunded amount does not exceed the original payment amount.
Processing Payments
Initiating Payments
How a payment is initiated depends on your integration approach:
- Sonic checkout (Standard Checkout / Plug and Play) — the customer selects a payment mode in the Sonic UI, and Nimbbl initiates the payment automatically
- Custom Checkout (Full API) — your server calls the Make Payment API with the order ID, payment mode, and payment details
In both cases, the payment is routed through a payment partner based on Pulse routing rules.
Completing Payments
After initiation, the payment flow varies by payment mode:
- Cards — customer enters card details → 3D Secure / OTP authentication → payment partner processes → result
- UPI Intent — customer approves payment in their UPI app → payment partner processes → result
- UPI Collect — customer enters VPA → approves collect request in their UPI app → result
- Netbanking — customer selects bank → authenticates on bank page → result
- Wallets — customer selects wallet → authenticates on wallet provider → result
- EMI — customer selects EMI scheme → card details / authentication → result
Handling Payment States
Your integration should handle all payment states:
- Succeeded — the most common success path. Update your order as paid and fulfill it. Succeeded is a terminal state.
- Failed — the payment did not go through. If retries are available, allow the customer to try again.
- Reversed — the payment has been reversed. Update your records accordingly and communicate with the customer.
Never rely solely on the client-side callback to confirm payment status. Always verify using webhooks or the transaction enquiry API, and validate the response signature.
Handling Edge Cases and Reversals
Some edge cases require special handling:
- Timeout with unclear outcome — if a payment times out and the status is unknown, use the transaction enquiry API to poll for the final state
- Reversal — if a payment enters the Reversing state, it will resolve to either Reversed or Reversal Failed. Monitor reversal status through webhooks and update your records accordingly.
- Duplicate payments — Nimbbl prevents duplicate payments by enforcing one active payment attempt per order at a time