2.1 The Payment Lifecycle

In the previous chapter, we focused on deploying hyperswitch locally, initiating payments and understanding how a payment flows through Hyperswitch components from checkout initiation to routing, authorization, and final status updates across different services. In this chapter, we shift focus from where a payment flows to how a payment evolves over time.

This chapter takes a deep dive into the payment lifecycle in Hyperswitch, explaining what happens to a payment from the moment it is created until it reaches a final, terminal state. We examine how a payment transitions from one stage to another based on user actions (such as submitting payment details or completing authentication) and API calls.

Once this lifecycle model is clear, we move into practical payment flows. Using examples, this chapter walks through common payment patterns that merchants need to support in real-world systems such as instant payments, two-step manual capture payments, MIT transactions and more.

To understand the payment lifecycle clearly, we begin with the simplest payment use case: a customer completing an instant card payment. This baseline scenario helps introduce the fundamental payment states and transitions without added complexity. From there, we gradually expand into more advanced scenarios such as authentication flows, multiple authorization attempts, delayed and partial captures, and payments that require explicit merchant intervention demonstrating how each of these builds on the same underlying lifecycle model.

By walking through these cases incrementally, you will see how a payment moves from creation to its final terminal state, how transitions are triggered by user actions and API calls, and how Hyperswitch manages state consistently across synchronous and asynchronous events. By the end of this section, you should be able to map any real-world payment use cases to the Hyperswitch payment lifecycle and model it confidently using the primitives provided by the platform.

Baseline: Instant Card Payment

We begin with the simplest possible payment lifecycle: an instant card payment with automatic capture and no additional authentication. Once the payment intent is created, it enters the RequiresPaymentMethod state, indicating that Hyperswitch is waiting for a payment instrument to be attached. When the customer provides card details and the payment method is successfully attached, the payment transitions to RequiresConfirmation.

Upon confirmation, Hyperswitch moves the payment into the Processing state, where authorization and capture are performed in a single step. Since this is an auto-capture flow and no further action is required, a successful authorization and capture transitions the payment directly into the Successful terminal state. This flow establishes the core backbone of the lifecycle and serves as the foundation for all subsequent scenarios.

Introducing Customer Authentication (3DS)

The next lifecycle variation introduces customer authentication, typically required for regulations such as 3DS. The initial steps remain unchanged until RequiresConfirmation. At this point, instead of moving directly to processing, the payment transitions into RequiresCustomerAction, signaling that the customer must complete an external authentication step (for example, a 3DS challenge).

Once the customer successfully completes the authentication, control returns to Hyperswitch and the payment resumes processing. If authorization and capture succeed, the payment transitions to Successful. This flow highlights how Hyperswitch pauses and resumes the lifecycle cleanly around user-driven asynchronous actions without breaking state consistency.

Cancellation Paths During Authentication

The lifecycle also accounts for early exits. If the customer abandons the authentication flow or explicitly cancels the payment while in RequiresCustomerAction, the payment transitions to the Cancelled terminal state. This ensures that incomplete or abandoned payment attempts do not remain indefinitely active and are clearly marked as closed from a merchant reconciliation perspective.

Failure and Expiry Scenarios

Beyond cancellation, the lifecycle models failure and timeout conditions. If authentication fails, authorization is declined, or required actions are not completed within the allowed time window, the payment transitions into Failed or Expired states respectively. These terminal states represent definitive outcomes where no further progression is possible without creating a new payment intent. This distinction allows merchants to handle retries, user messaging, and reconciliation accurately.

Manual Capture Flow (Two-Step Payments)

Moving beyond instant payments, the lifecycle expands to support manual capture use cases. After confirmation and authorization, instead of auto-capturing, the payment transitions from Processing to RequiresCapture. At this stage, funds are authorized but not yet settled.

The merchant can later initiate a capture action, which moves the payment to Successful once the capture completes. Alternatively, the merchant may void or cancel the authorization, transitioning the payment into Cancelled. This flow is critical for use cases like order fulfillment, inventory checks, or delayed service delivery.

Partial Captures and Multiple Captures

The lifecycle further supports partial captures, where only a portion of the authorized amount is captured. In this case, the payment transitions into PartiallyCapturedAndCapturable, indicating that some funds have been captured while the remaining authorized amount is still available.

From here, merchants can perform additional captures until the full amount is settled, eventually reaching Successful, or choose to cancel the remaining authorization. This model enables complex fulfillment workflows such as split shipments or incremental service delivery.

Partial Authorization Scenarios

In some cases, processors approve only a portion of the requested amount. When this happens, the payment enters PartiallyAuthorizedRequiresCapture. This state indicates that partial funds are available and merchant intervention is required to decide the next step.

The merchant may capture the authorized amount, capture partially, or cancel the remaining authorization.

Merchant Review and Approval Flows

The lifecycle also supports merchant-driven decision points. In scenarios requiring fraud review or operational approval, the payment may transition into RequiresMerchantAction. At this stage, the merchant explicitly approves or rejects the payment.

Approval moves the payment back into Processing, after which it follows the standard capture path. Rejection transitions the payment into Cancelled. This pattern enables workflows where merchants need manual control before committing funds.

Bringing the Payment Lifecycle Together

This final view brings together all the individual paths we explored and shows the complete payment lifecycle as a single, unified model. What begins as a simple payment intent can evolve in many directions driven by customer actions, merchant decisions, processor responses, and time-based events yet all of these paths are governed by the same consistent state machine.

At its core, every payment starts by expressing intent (RequiresPaymentMethod), progresses through confirmation and processing, and may branch into customer authentication, merchant review, authorization-only states, or capture-related states. Whether a payment is auto-captured instantly, manually captured later, partially authorized, partially captured across multiple steps, or cancelled mid-way, each transition is explicit and intentional. Hyperswitch ensures that every action confirm, authenticate, capture, cancel, or retry moves the payment forward in a predictable and observable way.

Equally important is how the lifecycle converges. No matter how complex the journey, every payment eventually resolves into a small set of terminal states: Successful, Cancelled, Failed, or Expired. This convergence is what makes the model powerful: merchants can support sophisticated real-world payment scenarios without losing clarity in reconciliation, reporting, or downstream business logic.

With this lifecycle model in place, merchants are not constrained to predefined flows. Instead, they can compose their own payment experiences instant or delayed, customer-driven or merchant-controlled by mapping business requirements directly to lifecycle states and transitions. This flexibility is the foundation on which all practical payment flows in Hyperswitch are built.