This section explains the conceptual foundations of Nimbbl's payment processing. Understanding these concepts will help you make informed decisions when building and maintaining your integration — regardless of whether you use Standard Checkout, Custom Checkout, or Plug and Play.
Entities and Relationships
Every Nimbbl transaction is built around three core entities:
- Order — represents a customer's purchase intent. An order is the container that holds transaction information such as amount, currency, line items, and customer details. An order exists independently of any payment attempt.
- Payment — represents an attempt to collect money for an order. A single order can have multiple payment attempts (for example, if the first attempt fails and the customer retries). Each payment uses one payment mode and is processed by one payment partner.
- Refund — represents a return of funds for a successful payment. A single payment can have multiple refunds, as long as the total refunded amount does not exceed the original payment amount.
The relationships are straightforward: one order can have many payments, and one payment can have many refunds. Payment partners process the actual money movement, and payment modes define how the customer pays (Cards, UPI, Netbanking, and so on).
Lifecycle at a Glance
Each entity moves through a defined set of states during its lifecycle. Orders progress from creation through pending to completion or lapse. Payments move from initiation through processing to success, failure, or reversal. Refunds follow a simpler path from pending to success or failure.
The detailed lifecycle states and transition rules are covered in each entity's dedicated guide. See Orders, Payments, and Refunds for full lifecycle documentation.
How You Learn About Changes
Payment processing is asynchronous. When a payment status changes at the payment partner, your system needs to know about it. Nimbbl provides two mechanisms:
- Webhooks are the primary method. Nimbbl sends a POST request to your configured webhook URL whenever a transaction status changes. This is the most efficient approach for keeping your system in sync.
- Transaction Enquiry is a pull-based API that lets you fetch the current status of any transaction on demand. Use this as a backup mechanism or for reconciliation.
- Signature validation ensures that the data you receive actually came from Nimbbl and was not tampered with in transit.
For implementation details, see Webhooks and Transaction Enquiry and Validating Payment Response with Signature.
Where to Go Next
- Understand the order lifecycle and how to create orders — Orders
- Understand payment processing and edge cases — Payments
- Process full, partial, and SKU-based refunds — Refunds
- Understand payment partner routing — Payment Partners
- Learn about supported payment instruments — Payment Modes
- Understand multi-currency and conversion — Currencies
- Set up webhooks and transaction enquiry — Webhooks and Transaction Enquiry
- Validate payment responses — Validating Payment Response with Signature