Fully Decoupled Payment Flow

A Fully Decoupled Payment Flow separates payment creation, update, confirmation, and capture into clearly independent API steps. Instead of treating checkout as a single atomic event, the merchant orchestrates the lifecycle progressively creating the intent first, enriching or modifying it over time, and confirming only when ready. This pattern is especially useful in complex checkout architectures, multi-step onboarding journeys, marketplaces, configurable pricing flows, or any scenario where payment details evolve before final authorization.

The flow begins with a simple intent creation call: POST /payments (Create Intent)

At this stage, the merchant typically sends minimal required fields (such as amount and currency) and receives back a payment_id and client_secret. The payment transitions from:

Start → RequiresPaymentMethod

Importantly, no authorization attempt is made yet. The intent simply represents the merchant’s expectation of a future payment.

Next, the merchant may update the intent:

POST /payments/{id} (Update customer, amount, metadata, etc.)

This step allows flexibility. The merchant can:

• Modify the amount

• Attach customer details

• Add metadata

• Adjust configuration parameters

The payment remains in a pre-confirmation state. This is where the “decoupled” nature becomes clear payment configuration and checkout progression are no longer tightly coupled to a single API call.

When the merchant is ready to proceed, they explicitly trigger: POST /payments/{id}/confirm

Only at this point does Hyperswitch attempt authorization with the processor. The payment transitions:

RequiresConfirmation → Processing → (Succeeded / RequiresCapture)

If capture_method was set to "automatic", the payment will move directly to Succeeded after authorization and capture. If capture_method was "manual", the payment will land in RequiresCapture, waiting for a subsequent capture call.

For manual capture scenarios, the final step is: POST /payments/{id}/capture

Which transitions:

RequiresCapture → Succeeded

The key characteristic of a Fully Decoupled Flow is lifecycle control. Each transition is intentionally triggered by a merchant API call rather than chained automatically. The merchant decides when to:

• Create the payment

• Attach or update details

• Confirm the authorization

• Capture the funds

State transitions remain identical to the standard lifecycle model, but ownership of timing shifts entirely to the merchant.

This pattern is particularly powerful for:

• Complex checkout UIs

• Multi-party or marketplace systems

• Deferred confirmation scenarios

• External fraud or risk decision workflows

• Systems requiring asynchronous approval before confirmation

By decoupling lifecycle stages into discrete calls, merchants gain maximum flexibility while still operating within the same consistent Hyperswitch payment state machine.