Skip to main content

Implement one-time payment flows for processing payments in India

Zuora

Implement one-time payment flows for processing payments in India

This article describes how to implement one-time payment flows to process the following transactions in India:

Overview

To process local one-time and recurring transactions in INR, you can configure and integrate a Payment Page 2.0 on the following types of payment gateway integrations. You need to pass in additional client parameters in the Z.render function to support the use case of authorization amount processing or invoice processing.

Payment gateway integration Supported payment method type Support for recurring transactions Gateway configuration requirement
Stripe v2 Credit Card Reference Transaction

Yes

To process local recurring payments in Indian Rupees (INR) in India, mandates must be established. Any recurring payments in INR without the mandate ID data will fail. You can take advantage of the one-time payment flow of adding or updating a payment method to create a recurring mandate without being required to make a payment. You can also create a recurring mandate, complete a payment, and store the details as a fully tokenized payment method. For more information about Zuora's support and suggestions for recurring payments in India, see the Recurring Payments in India article in Zuora Community. 

The implementation of payment flows for local recurring payments in INR is only supported on Stripe v2 gateway integration for now. Zuora is continuing to evaluate other gateway partners for recurring mandate processing based on their readiness.

 
CyberSource 2.0 Credit Card No The Gateway Endpoint setting on the gateway instance page must be set to CyberSource India.

 Complete the following tasks to implement a Payment Page 2.0 to support one-time payment flows:

  1. Review prerequisites.
  2. Set up a Payment Page 2.0.
  3. Request a signature for the Payment Page from Zuora.
  4. Set up your client code to integrate the Payment Page to your web page.
  5. Implement the callback response.  

To support cross-border transactions that are not in INR, see information in the Recommendations for other scenarios section.

Procedure

Step 1. Review prerequisites

Prerequisites for implementing payment flows on Stripe v2

  • If you want to process recurring payments in India through Zuora, the following requirements must be met to be compliant with the directive of processing e-mandate for recurring transactions issued by the Reserve Bank of India (RBI):
    • Run your transactions in Indian Rupees (INR) through a local Indian entity.
    • Other processing requirements from RBI are met.
    • Understand that Zuora does not support saving the masked card numbers due to the RBI's regulation for storage of payment system data.
  • Zuora's support for implementing payment flows for processing local recurring payments in India is currently in a joint pilot program with Stripe. To use this feature, you must request the pilot version of the feature with Stripe to avoid issues with incorrect configuration. Work with your Stripe account representative to enable the support for recurring payments on the Stripe platform.
  • Ensure that the following requirements for implementing payment flows in Zuora are met:
  • To process the required webhook events with Stripe, enable the Stripe Real-Time Reconciliation feature. See Real-Time Reconciliation for details.

Prerequisites for implementing one-time payment flows on CyberSource 2.0

Step 2. Set up a Payment Page 2.0

  1. To understand the implementation procedure of Payment Pages 2.0 in Zuora, review Payment Pages 2.0 implementation overview.
  2. Set up a Payment Page 2.0:
  3. Optionally, preview the Payment Page.
  4. Optionally, translate and localize the Payment Page.
  5. Optionally, update the CSS for the Payment Page.

Step 3. Request a signature for the hosted page from Zuora

Follow the instructions in Request a signature for the Payment Page from Zuora. Because the Client-side HPM Parameter Validation feature is enabled, Zuora will validate the additional fields in the request by comparing them with the values specified in the digital signature.

Here are two request examples for the Generate RSA signature REST API operation.

{
   "uri":"https://sandbox.na.zuora.com/apps/PublicHostedPageLite.do",
   "method":"POST",
   "pageId":"test808145b3bf9d0145b3c6812b0008",
   "paymentGateway":"Stripe2",
   "authroizationAmount":"100",
   "currency":"INR",
   "accountId":"test808145b3bf9d0145b3c6812b0008"
}
{
   "uri":"https://sandbox.na.zuora.com/apps/PublicHostedPageLite.do",
   "method":"POST",
   "pageId":"test808145b3bf9d0145b3c6812b0008",
   "paymentGateway":"Stripe2",
   "accountId":"test808145b3bf9d0145b3c6812b0008"
}

Step 4. Set up your client code

Follow the instructions in Integrate Payment Pages 2.0. When rendering the Payment Page form, specify the following parameters in the Z.render function to support the use case of authorization amount processing or invoice processing.

Parameter Applicable use case Description

doPayment

Both

Required

Type: boolean

Default: false

true indicates that the Payment Page will create a payment method as well as process the one-time payment transaction.

If it is false or not specified, the Payment Page will only create a payment method.

storePaymentMethod

Both

Type: boolean

Default: true

true indicates that the tokenized payment method will be stored in Zuora and will be used in subsequent recurring payments.

false indicates that the payment method will not be stored in Zuora. End-customers need to be brought back on-session to authenticate the payment.

For the implementation of one-time payment flows on CyberSource 2.0, storePaymentMethod must be false, because Zuora does not support processing recurring payments in INR through one-time payment flows on CyberSource.

field_accountId

Both

Required

The payment method will be created for the specified account.

For more information about this parameter, see Client parameters for Payment Pages 2.0.

authorizationAmount

Authorization amount processing

Required for authorization amount processing

If doPayment is true, this field is used to specify the one-time payment amount sent to the gateway. 

If doPayment is false, this field is used to specify the initial authorization amount of the payment method.

For more information about this parameter, see Client parameters for Payment Pages 2.0.

field_currency

Authorization amount processing

Required for authorization amount processing

The currency of the one-time payment amount. 

For more information about this parameter, see Client parameters for Payment Pages 2.0.

documents Invoice processing

Required for invoice processing

An array of invoices to be paid in this transaction, containing the following fields:

  • type - The value must be invoice.
  • ref - The value must be the invoice number, such as INV0000001.
     

For the implementation of the one-time payment flow for local recurring payments in India on Stripe v2, in addition to the fields for authorization amounts or invoices, specify the following fields to generate a mandate ID. The default value for each field is specific to the Stripe gateway integration.

Parameter Description

cardMandateEnabled

Required

Type: boolean

Default: false

true indicates that the Gateway Options fields for generating a mandate ID can be specified.

If cardMandateEnabled is true, for the Gateway Options fields in this table that are not specified, the default values will be used. You can specify the field to override the default value.

param_gwOptions_CardMandateReference

Optional

Type: string

Default: null

Unique identifier for the mandate.

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateDescription

Optional

Type: string

Default: null

A description of the mandate.

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateAmountType

Optional

Type: string (enum)

Default: maximum

The value can be fixed or maximum.

  • fixed - The value of the param_gwOptions_CardMandateAmount field indicates the exact amount to be charged in future payments.
  • maximum - The amount charged can be up to the value passed for the param_gwOptions_CardMandateAmount field.

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateAmount

Optional

Type: number

Default: 5000

Amount to be charged for future payments.

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateStartDate

Optional

Type: date-time

Default: Date and time when passing the parameter

Start date of the mandate, such as 2021-09-14T21:56:00+08:00 

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateEndDate

Optional

Type: date-time

Default: 20 years after the mandate start date

End date of the mandate, such as 2022-09-14T21:56:00+08:00

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateInterval

Optional

Type: string (enum)

Default: sporadic

Payment frequency. The value can be day, week, month, year, or sporadic.

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateIntervalCount

Optional

Type: integer

Default: null

The number of intervals between payments. Up to one year interval is allowed (1 year, 12 months, or 52 weeks). This parameter is optional when iparam_gwOptions_CardMandateInterval is sporadic.

See Client parameters for Payment Pages 2.0 for details about the Gateway Options fields.

param_gwOptions_CardMandateSupportedTypes

Optional

Type: string

Default: empty

The mandate type supported for this payment. Currently, only india is allowed. If you want to set india as the default value, submit a request at Zuora Global Support.

In summary, to create a payment flow for processing one-time payments in INR in India, use either Stripe v2 or CyberSource 2.0 payment gateway integration and specify the following fields and other fields according to your use case: 

  • doPayment:"true"
  • storePaymentMethod:"false"
  • Other fields for processing authorization amounts or invoices according to your use case

To create a payment flow for processing local recurring payments in INR in India, use the Stripe v2 payment gateway integration and specify the following fields and other fields according to your use case: 

  • doPayment:"true"
  • storePaymentMethod:"true"
  • cardMandateEnabled:"true"
  • Other fields for generating the mandate ID for your needs
  • Other fields for processing authorization amounts or invoices according to your use case

To create a recurring mandate without being required to make a payment, use the Stripe v2 payment gateway integration and specify the following fields and other fields according to your use case: 

  • doPayment:"false"
  • storePaymentMethod:"true"
  • cardMandateEnabled:"true"
  • Other fields for generating the mandate ID for your needs

Here is an example of the parameters for the payment flow for processing recurring payments on Stripe v2:

var params = {
    doPayment:"true",
    field_accountId:"testc0f87596f2f301759c29443622fa",
    authorizationAmount:"99",
    field_currency:"INR",
    cardMandateEnabled:"true",
    param_gwOptions_CardMandateReference:"sample-reference",
    param_gwOptions_CardMandateDescription:"sample description",
    param_gwOptions_CardMandateAmountType:"fixed",
    param_gwOptions_CardMandateAmount: "4000",
    param_gwOptions_CardMandateStartDate: "2021-09-14T21:56:00+08:00",
    param_gwOptions_CardMandateEndDate: "",
    param_gwOptions_CardMandateInterval: "month",
    param_gwOptions_CardMandateIntervalCount: "1",
    param_gwOptions_CardMandateSupportedTypes: "india"
};

Step 5. Implement callback response

See Advanced Integration of Payment Pages 2.0 for more information.

Additional information for payment flow implementation on Stripe v2

View mandate information in Zuora

After the additional fields are passed to the gateway and the mandate ID is successfully generated, it will be stored for the payment method in Zuora. You can view the mandate information by any of the following methods:

  • View the information at any of the following UI locations:
    • Payment detail page > View Detail hover help next to the Payment Method field
    • Account detail page > Billing and Payment Info section > View Detail hover help next to the Default Payment Method field
    • Account detail page > Electronic Payment Methods section > Your Credit Card Reference Transaction record
  • Retrieve the information through the Retrieve a payment method API operation. 
  • Retrieve the information from the Payment Method data source. See Generate a data source export for more information.
  • Retrieve the information from the PaymentMethod object in Data Query. See Construct SQL Queries in Data Query for more information.

Recommendations for other scenarios

To support cross-border transactions that are not in INR currency and therefore do not require a recurring mandate to be established, Zuora recommends you implement a one-time payment flow in non-INR currency. See the following articles for instructions.

If Zuora’s one-time payments do not meet your needs, the following solutions are recommended. You can then push the external payments into Zuora.

  • Work with your current payment gateway provider for guidance on how to implement necessary measures for your recurring payments.
  • Implement Pay-By-Link flows.
  • Build your own one-time payment flow.