Payments
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. | Authorized, Succeeded, Failed, Reversing |
| Authorized | Funds have been held on the customer's instrument but not yet collected. This happens on a pre-authorization — you must explicitly capture the payment to collect the funds, or void it to release the hold. Do not fulfill the order on authorized alone. | The payment partner confirmed the customer authorized the payment, but the amount has not been debited. The payment waits for you to capture or void it. | Succeeded (on capture), Reversed (on void) |
| Succeeded | Funds have been collected. The parent order moves to Completed. | The payment partner confirmed the payment was authorized and captured — either in a single step, or when you capture a previously authorized payment. 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 authorization confirmation period expired, triggering an automatic refund. See the 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 authorization confirmation 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. Nimbbl allows a grace period for this delayed confirmation, configured for your account with Nimbbl. If a payment succeeds after that window, Nimbbl automatically initiates a reversal (refund) because the order may have already been cancelled or re-attempted. Contact [email protected] to review or change the window for your account.
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 authorization confirmation period, the payment moves to Succeeded and the order is marked Completed. If it arrives after the authorization confirmation period, the payment moves to Reversing and an automatic refund is initiated.
Transaction Types
A payment record carries a transaction_type that describes what the transaction did:
| Transaction Type | Description |
|---|---|
payment | A standard payment that collects funds in a single step. |
capture | Collects funds that were previously held by an authorized (pre-authorization) payment. After a successful capture the payment moves to Succeeded. |
void | Releases the hold on an authorized payment without collecting any funds. After a void the payment moves to Reversed. |
full-refund / partial-refund | Returns funds to the customer against a succeeded payment. See Refunds. |
A payment can be authorized instead of collected outright — the funds are held but not debited. An authorized payment does not auto-succeed: you must explicitly capture it to collect the funds, or void it to release the hold. To learn how this works, see Pre-authorization. For the integration steps, see Pre-auth and Capture.
Sale vs Pre-authorization
Every payment is processed in one of two ways:
- Sale — the funds are collected immediately in a single step. The payment goes straight to Succeeded.
- Pre-authorization — the funds are held on the customer's instrument but not collected. The payment becomes Authorized; when you capture it the funds are collected and it moves to Succeeded, or when you void it the hold is released and it moves to Reversed.
So a Succeeded payment can be either a sale or a captured pre-authorization. Tell them apart from the payment status and the presence of authorization_details: a payment that was ever authorized carries authorization_details even after it succeeds via capture, while a sale never does. See Pre-authorization for the held flow.
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, Authorized, Succeeded, Failed, Reversing, Reversal Failed, or Reversed) |
transaction_type | What the transaction did (payment, capture, void, full-refund, or partial-refund) |
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.
- Authorized — funds are held but not collected. Do not fulfill the order yet. You must explicitly capture the payment to collect the funds, or void it to release the hold. See Pre-authorization.
- Failed — the payment did not go through. If retries are available, allow the customer to try again.
- Reversed — the payment has been reversed (an automatic reversal, or a void of an authorized payment). 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