Recurring payments

Recurring payments via Hyperswitch can be setup by passing some additional flags, as highligted below. The recurring payments are not tied to a specific amount or cycle and the merchant can charge the end-user as per their own business requirements.

Setting up a recurring card payment

When setting up subscription there are two distinct implementation flows. The correct flow depends on whether you intend to charge the customer immediately or simply validate their details for later use.

1. The Setup with Charge Flow

Use Case: Use this when you need to collect a payment immediately (e.g., the first month of a subscription or a setup fee) while simultaneously saving the card details for future automatic charges.

Configuration Parameters :

• setup_future_usage: "off_session"

• amount > 0

2. The Zero Dollar Authorization Flow

Use Case: Use this for free trials, pay-later models, or delayed billing. This flow validates the payment method details without charging the customer's card.

Configuration Parameters :

• Pass below parameters while calling payments API for Zero Dollar Auth

• setup_future_usage: "off_session"

• amount: 0

• payment_type: "setup_mandate"

Once the CIT is successful, Hyperswitch returns a payment_method_id . This payment_method_id can be used by the merchant for all subsequent MIT recurring payments. Hyperswitch also returns the network_transction_id (NTID) in its response to allow PICI compliant merchants to direct pass card + NTID for processing MIT recurring payments

The payment_method_id serves as a unique identifier mapped to a specific combination of a Customer ID and a unique Payment Instrument (e.g., a specific credit card, digital wallet, or bank account).

• Logic: A single customer can have multiple payment methods, each assigned a distinct ID. However, the same payment instrument used by the same customer will always resolve to the same payment_method_id.

• Scope: This uniqueness applies across all payment types, including cards, wallets, and bank details.

Customer ID	Payment Instrument	Payment Method ID
123	Visa ending in 4242	PM1
123	Mastercard ending in 1111	PM2
456	Visa ending in 4242	PM3
123	PayPal Account ([email protected])	PM4

Internally the payment_method_id is mapped to a bunch of credentials - PSP token, Raw card + NTID, Network token + NTID depending on functionalities enabled for the merchant

Supported MIT Flows

Hyperswitch supports decoupled transaction flows, allowing Merchant-Initiated Transactions (MITs) to be processed independently of the original Customer-Initiated Transaction (CIT), even when the CIT was completed outside the Hyperswitch platform.

MITs are initiated by invoking the /payments API with off_session: true and providing the available reference data in the recurring_details object. Depending on the artifacts available in your system, one of the following approaches can be used:

Payment_method_id : Submit the Hyperswitch generated payment_method_id to process the MIT transaction. Depending on the merchant configurations the MIT will be processed with the same PSP or with a different PSP.

Processor Payment Token : Submit a processor-issued token that represents the previously authorized payment instrument.

Network Transaction ID with Card Data : Provide the original network transaction identifier along with the associated primary card data required for authorization.

Network Transaction ID with Network Token : Submit the network transaction identifier in combination with the corresponding network tokenized card credentials.

Limited Card Data : Use a reduced card data set captured at the time of subscription creation to authorize subsequent MITs.