POST /payments
Required Fields:
confirm: true
capture_method: "automatic"
payment_method
succeeded
POST /payments
with capture_method: "manual"
requires_capture
POST /payments/{payment_id}/capture
succeeded
POST /payments
POST /payments/{payment_id}
POST /payments/{payment_id}/confirm
POST /payments/{payment_id}/capture
(if manual)authentication_type: "three_ds"
processing
→ requires_customer_action
→ succeeded
setup_future_usage: "off_session"
or "on_session"
customer_id
payment_method_id
returned on successsetup_future_usage
:
on_session
: Use when the customer is actively present during the transaction. This is typical for scenarios like saving card details for faster checkouts in subsequent sessions where the customer will still be present to initiate the payment (e.g., card vaulting for e-commerce sites).off_session
: Use when you intend to charge the customer later without their active involvement at the time of charge. This is suitable for subscriptions, recurring billing, or merchant-initiated transactions (MITs) where the customer has pre-authorized future charges.customer_id
GET /customers/payment_methods
payment_token
in confirm callpayment_method_id
payment_method_id
(which is 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.
setup_future_usage: "off_session"
amount > 0
setup_future_usage: "off_session"
amount: 0
payment_type: "setup_mandate"
off_session: true
recurring_details: { "type": "payment_method_id", "data": "<from_setup>"}
succeeded
, failed
, cancelled
, partially_captured
are terminal states requiring no further actionautomatic
(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) capture methods.