> For the complete documentation index, see [llms.txt](https://docs.hyperswitch.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hyperswitch.io/integrations/prism/api-reference/setup-recurring.md). # Setup Recurring ## Overview The `SetupRecurring` RPC establishes a payment mandate (recurring payment instruction) at the payment processor. This enables future charges without requiring the customer to re-enter payment details or be present for each transaction. It's the foundation of subscription billing, recurring donations, and automated bill payment systems. **Business Use Case:** When setting up a SaaS subscription, monthly utility bill, insurance premium, or any service that bills customers on a recurring basis. The mandate represents the customer's consent for future charges and is stored securely at the processor, reducing PCI compliance scope and improving authorization rates. ## Purpose **Why use SetupRecurring?** | Scenario | Developer Implementation | | ------------------------ | -------------------------------------------------------------------------------------------------------------------- | | **SaaS subscriptions** | Customer signs up for monthly plan - call `SetupRecurring` to create mandate, then use mandate for recurring billing | | **Utility bills** | Customer enrolls in auto-pay - call `SetupRecurring` to enable automatic monthly charges | | **Membership renewals** | Gym or club membership - call `SetupRecurring` to set up annual renewal charges | | **Installment payments** | Buy-now-pay-later setup - call `SetupRecurring` to create scheduled payment plan | | **Donation programs** | Monthly charity donations - call `SetupRecurring` to enable recurring contributions | **Key outcomes:** * Mandate reference created for future charges * Customer consent stored at processor level * No PCI exposure for stored payment methods * Higher authorization rates for repeat charges * Compliance with SEPA and other mandate regulations ## Request Fields | Field | Type | Required | Description | | ----------------------------------- | ------------------ | -------- | ---------------------------------------------------------------------- | | `merchant_recurring_payment_id` | string | Yes | Your unique identifier for this recurring setup | | `amount` | Money | Yes | Initial amount (for validation) | | `payment_method` | PaymentMethod | Yes | Payment method to be used for recurring charges | | `customer` | Customer | No | Customer information | | `address` | PaymentAddress | Yes | Billing and shipping address | | `auth_type` | AuthenticationType | Yes | Type of authentication to be used (e.g., THREE\_DS, NO\_THREE\_DS) | | `enrolled_for_3ds` | bool | Yes | Indicates if the customer is enrolled for 3D Secure | | `authentication_data` | AuthenticationData | No | Additional authentication data | | `metadata` | SecretString | No | Additional metadata for the connector | | `connector_feature_data` | SecretString | No | Connector-specific metadata for the transaction | | `return_url` | string | No | URL to redirect after setup | | `webhook_url` | string | No | URL for webhook notifications | | `complete_authorize_url` | string | No | URL to complete authorization | | `session_token` | string | No | Session token, if applicable | | `order_tax_amount` | int64 | No | Tax amount, if an initial payment is part of setup | | `order_category` | string | No | Category of the order/service related to the mandate | | `merchant_order_id` | string | No | Merchant's internal reference ID | | `shipping_cost` | int64 | No | Shipping cost, if an initial payment is part of setup | | `setup_future_usage` | FutureUsage | No | Indicates future usage intention. Values: ON\_SESSION, OFF\_SESSION | | `off_session` | bool | No | Indicates if off-session process | | `request_incremental_authorization` | bool | Yes | Indicates if incremental authorization is requested | | `request_extended_authorization` | bool | No | Indicates if extended authorization is requested | | `enable_partial_authorization` | bool | No | Indicates if partial authorization is enabled | | `customer_acceptance` | CustomerAcceptance | No | Details of customer acceptance for mandate | | `browser_info` | BrowserInformation | No | Information about the customer's browser | | `payment_experience` | PaymentExperience | No | Preferred payment experience | | `payment_channel` | PaymentChannel | No | Describes the channel through which the payment was initiated | | `billing_descriptor` | BillingDescriptor | No | Billing Descriptor information to be sent to the payment gateway | | `state` | ConnectorState | No | State data for access token storage and other connector-specific state | | `payment_method_token` | SecretString | No | Token for previously saved payment method | | `order_id` | string | No | Connector order identifier if an order was created before authorize | | `locale` | string | No | Locale/language preference for the shopper (e.g., "en-US") | | `connector_testing_data` | SecretString | No | Connector-specific testing data (JSON stringified) | ## Response Fields | Field | Type | Description | | ----------------------------------- | --------------------- | ------------------------------------------------------------------------- | | `connector_recurring_payment_id` | string | Identifier for the mandate registration | | `status` | PaymentStatus | Status of the mandate setup attempt | | `error` | ErrorInfo | Error details if setup failed | | `status_code` | uint32 | HTTP status code from the connector | | `response_headers` | map\ | Optional HTTP response headers from the connector | | `mandate_reference` | MandateReference | Reference to the created mandate for future charges | | `redirection_data` | RedirectForm | Data for redirecting the customer's browser (if additional auth required) | | `network_transaction_id` | string | Card network transaction reference | | `merchant_recurring_payment_id` | string | Your recurring payment reference (echoed back) | | `connector_response` | ConnectorResponseData | Various data regarding the response from connector | | `incremental_authorization_allowed` | bool | Indicates if incremental authorization is allowed | | `captured_amount` | int64 | Captured amount in minor currency units if initial charge included | | `state` | ConnectorState | State data for access token storage and other connector-specific state | | `raw_connector_request` | SecretString | Raw request to the connector for debugging | | `connector_feature_data` | SecretString | Connector-specific metadata for the transaction | ## Example ### Request (grpcurl) ```bash grpcurl -H "x-connector: stripe" \ -H "x-connector-config: {\"config\":{\"Stripe\":{\"api_key\":\"$STRIPE_API_KEY\"}}}" \ -d '{ "merchant_recurring_payment_id": "recurring_001", "amount": { "minor_amount": 2900, "currency": "USD" }, "payment_method": { "card": { "card_number": "4242424242424242", "expiry_month": "12", "expiry_year": "2027", "card_holder_name": "John Doe", "cvc": "123" } }, "address": { "billing": { "line1": "123 Main St", "city": "San Francisco", "state": "CA", "zip": "94102", "country": "US" } }, "auth_type": "NO_THREE_DS", "enrolled_for_3ds": false, "request_incremental_authorization": false, "setup_future_usage": "OFF_SESSION" }' \ localhost:8080 \ types.PaymentService/SetupRecurring ``` ### Response ```json { "connector_recurring_payment_id": "seti_3Oxxx...", "status": "AUTHORIZED", "status_code": 200, "mandate_reference": { "mandate_id": "pm_3Oxxx...", "mandate_status": "ACTIVE" }, "merchant_recurring_payment_id": "recurring_001", "incremental_authorization_allowed": false } ``` ## Next Steps * [RecurringPaymentService.Charge](/integrations/prism/api-reference/recurring-payment-service.md) - Use the mandate for future recurring charges * [Authorize](/integrations/prism/api-reference/authorize.md) - Create initial charge with mandate * [CustomerService.Create](/integrations/prism/api-reference/customer-service.md) - Create customer for associated recurring payments * [Capture](/integrations/prism/api-reference/capture.md) - Capture initial payment if part of setup --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.hyperswitch.io/integrations/prism/api-reference/setup-recurring.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.