Overview

This guide shows you how to use the Purchase endpoint to create new subscriptions using Cards for customers in India where RBI E-mandates are required. We’ll also illustrate how to work with the Stripe sandbox simulator.

Prerequisites & limitations

Familiarity with Recurly’s V3 API, Webhooks, and basic REST concepts
Completed the Quickstart Guide
Familiarity with our 3DS guides for new cards and stored cards:
- 3D Secure for new cards
- 3D Secure for Stored billing IDs
A Stripe gateway account.

Definition

Creating Purchases refers to the process of generating new customer accounts alongside subscriptions in a single, consolidated call to the Recurly Purchase endpoint. This streamlines checkout experiences by bundling all required resources into one request.

This is necessary for Stripes India e-mandates due to the 3DS requirement on all customer-initiated requests. All Subscription Signup requests from Recurly's APIs are customer initiated.

India Requirements

When processing cards in India, we will request an e-mandate from the gateway which is tied to the specific subscription. You may only have one e-mandate per Account at this time.

All customer-initiated transactions, including all subscription signup events are required to use 3D Secure. Therefore it is not recommended to split your integration into a two-step process (add billing info, then add subscription), as this will cause the gateway to request 3DS again.

One-time transactions are allowed when using a card payment method for a consumer in India, but you must use 3DS, even on stored billing info. Please reference the above documentation for 3DS on new and stored cards.

Creating Subscriptions

Step 1: Generate a Card Payment Request + Subscription

Use a supported client library, Recurly.js and/or a V3 Recurly API implementation. Our client libraries help you build out our APIs easily and process transactions faster. Cards for India customers will require 3DS handling via Recurly.js, so ensure, no matter how you pass in card data, that you are handling 3DS Action and 3Ds Action Result tokens. See our 3DS documentation for details.

📘
One-Step Flow
It is recommended to handle the subscription signup and card detail storage in a single step to avoid Stripe requesting 3DS verification twice.

Send a request to the create purchase endpoint on Recurly’s API, including:

Customer account data (e.g., code, name, billing info, phone number, email address, card or Recurly.js token-id)
Subscriptions (with plan codes)

Please Note: You can use the /subscriptions endpoint for this purpose, but ensure you're passing in the token-id or the PAN data in that call for al "all in one" style subscription creation. This will ensure the mandate is created properly with the card and 3DS is handled prior to card storage.

Tip: Many more parameters are available. See the Create Purchase reference to learn more.

Step 2: Process the purchase response

A successful purchase returns an InvoiceCollection, which contains any charge or credit invoices generated by the request. If the purchase fails, you’ll receive an error response indicating what went wrong. Card transactions for India customers will be in a Scheduled state, and the Invoice will be Processing.

Card transactions in India use consumer-approved enrollment with the consumer's bank to allow consumers to authenticate their identity and authorize payments in their mobile apps. This process can take up to 26 hours to receive final updates from the gateway as there is a 24 hour wait period prior to processing a transaction. This can auto-cancel a new subscription if the consumer does not respond to the push notification on their phone.

Stripe handles the pre-renewal notification for initial transactions and renewals internally, and does not expose that process to us. We will receive webhooks from Stripe when status updates are received.

In this step, you will handle the 3DS flow using Recurly.js as documented in the below two guides:

Please reference 3DS flows for Recurly.js and return to this page.

Step 3: Verify and finish

After a successful purchase, you can confirm the details via the Recurly Admin UI or by calling Recurly’s API to list your new account, subscription, or invoice.

Step 4: Listen for webhooks

After a successful signup, there will be several webhooks you should listen to in order to ensure you are enabling access to features on in your environment, and disabling access should a consumer decide to cancel their subscription from within their mobile banking application.

It is recommended that you listen for at least the webhooks below. Since consumers can cancel, pause, and resume subscriptions within their Banking App, it is extremely important to listen for these events throughout the lifecycle of a subscription.

Sandbox behavior

When using Stripe, they offer some India Cards that you can use to simulate different behaviors.

Stripe India test cards

You can test successful mandate creation, consumer-driven pauses or cancellations, issuing bank pre-debit notification failures, and mandate cancellations.

Next steps

Now that you can create new subscriptions, explore payment method guide to explore other use cases and limitations related to the Card usage in India on Stripe. Ensure you've read through our RBI documentation if you are not using Stripe.