Payment Flows

Hyperswitch provides flexible payment processing with multiple flow patterns to accommodate different business needs. The system supports one-time payments, saved payment methods, and recurring billing through a comprehensive API design.

One-Time Payment Patterns

1

Instant Payment (Automatic Capture)

Use Case: Simple, immediate payment processing Endpoint: POST /payments

Required Fields:

  • confirm: true

  • capture_method: "automatic"

  • payment_method

Final Status: succeeded

2

Two-Step Manual Capture

Use Case: Deferred settlement (e.g., ship before charging)

Flow:

  • Authorize: POST /payments with capture_method: "manual" Status: requires_capture

  • Capture: POST /payments/{payment_id}/capture Final Status: succeeded

(Authorize-only → Capture funds)

3

Fully Decoupled Flow

Use Case: Complex checkout journeys with multiple modification steps. Useful in headless checkout or B2B portals where data is filled progressively.

Endpoints:

  • Create: POST /payments

  • Update: POST /payments/{payment_id}

  • Confirm: POST /payments/{payment_id}/confirm

  • Capture: POST /payments/{payment_id}/capture (if manual)

Typical progression:

  • Create intent → returns payment_id + client_secret

  • Update intent (customer, amount, etc.)

  • Confirm intent → status: succeeded / requires_capture

  • Capture (if manual) → status: succeeded

4

3D Secure Authentication Flow

Use Case: Enhanced security with customer authentication

Additional Fields:

  • authentication_type: "three_ds"

Status Progression: processing → requires_customer_action → succeeded

Flow summary:

  • POST /payments with authentication_type: "three_ds"

  • Status: requires_customer_action + redirect_url

  • Redirect customer to 3DS page, complete challenge

  • Resume payment processing → succeeded

Payment Method Management

1

Saving Payment Methods

During Payment Creation:

  • Add setup_future_usage: "off_session" or "on_session"

  • Include customer_id

  • Result: payment_method_id returned on success

Understanding setup_future_usage:

  • on_session: Use when the customer is actively present during the transaction (e.g., saving card for faster subsequent checkouts when customer is present).

  • off_session: Use when you intend to charge the customer later without their active involvement (e.g., subscriptions, recurring billing, MITs).

2

Using Saved Payment Methods

Typical flow:

  1. Initiate: Create payment with customer_id (POST /payments)

  2. List: Get saved cards via GET /customers/payment_methods (use client_secret, publishable_key)

  3. Confirm: Use selected payment_token in confirm call POST /payments/{id}/confirm

Result: Payment result after confirmation.

PCI Compliance and payment_method_id

Storing payment_method_id (a token representing the actual payment instrument, which could be a payment token, network token, or payment processor token) significantly reduces your PCI DSS scope. Hyperswitch securely stores the sensitive card details and provides you with this token. While you still need to ensure your systems handle payment_method_id and related customer data securely, you avoid the complexities of storing raw card numbers. Always consult with a PCI QSA to understand your specific compliance obligations.

Recurring Payment Flows

1

Customer-Initiated Transaction (CIT) Setup

Options:

  • Option 1 — Setup with Charge:

    • setup_future_usage: "off_session"

    • amount > 0

  • Option 2 — Zero Dollar Authorization:

    • setup_future_usage: "off_session"

    • amount: 0

    • payment_type: "setup_mandate"

These approaches allow creating a setup that can be used for future off-session charges.

2

Merchant-Initiated Transaction (MIT) Execution

Use Case: Subscription charges, scheduled billing without customer interaction

Required Fields:

  • off_session: true

  • recurring_details: { "type": "payment_method_id", "data": "<from_setup>" }

Typical flow:

  • Trigger billing (subscription/scheduled)

  • POST /payments with off_session: true and recurring_details

  • Process with saved payment_method_id

  • Status: succeeded

Status Flow Summary

(See individual flows above for status progressions; terminal states and capture behaviors summarized below.)

Notes

  • Terminal states: succeeded, failed, cancelled, partially_captured are terminal states requiring no further action.

  • Capture methods supported: automatic (funds captured immediately), manual (funds captured in a separate step), manual_multiple (funds captured in multiple partial amounts via separate steps), and scheduled (funds captured automatically at a future predefined time).

  • Authentication: 3DS authentication automatically resumes payment processing after customer completion.

  • MIT Compliance: Off-session recurring payments follow industry standards for merchant-initiated transactions.

Links:

  • Source page: https://api-reference.hyperswitch.io/v1/payments/payment--flows

  • Edit on GitHub: https://github.com/juspay/hyperswitch/edit/main/api-reference/v1/payments/payment--flows.mdx

  • Raise issue: https://github.com/juspay/hyperswitch/issues/new?title=Issue%20on%20docs&body=Path:%20/v1/payments/payment--flows

Related:

  • Setup Instructions: https://api-reference.hyperswitch.io/v1/payments/setup--instructions

  • Payments - Create: https://api-reference.hyperswitch.io/v1/payments/payments--create

PreviousRouting - Auth Rate BasedNextPayments Link - Retrieve