paytm developer docs logoDeveloperDocumentation
search

POSTCreate Subscription API

Use Case

To create a subscription with required subscription details like upfront transaction amount, frequency, subscription amount type etc. 

Request Attributes

Content Type : JSON

Head

AttributeDescription
requestTimeStamp
string
optional

EPOCH timestamp of the time at which request is being sent.
 

Example: 1588402269

signature
string
mandatory

AI router validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.

 

 Note: Create the signature using the body parameter of the request.

channelId
string
optional

The parameter value identifies the Channel for which the API call is initiated.
 

Possible values: WEB , WAP

Body

AttributeDescription
mid
string
mandatory

This is a unique identifier provided to every merchant by AI router.
 

Example: 216820000002516036253

orderId
string
mandatory

It is a unique reference ID for a transaction passed in the transaction request. Order ID should be passed to raise the refund
 

Example: OREDRID_98765

requestType
string
mandatory

This parameter is used to identify the transaction flow.
Its value shall be as mentioned below:
'SUBSCRIPTION' for Subscription and ‘RENEW_SUBCRIPTION’ for Renewal
 

websiteName
string
mandatory

This is provided by AI router and it defines the static response URL.


Note: other websiteName provided by paytm

Example: WEBSTAGING, DEFAULT

txnAmount
object
mandatory

The first payment amount to be charged to the customer at the time of subscription creation.
*Only for UPI & e-Mandates paymodes - The txnAmount cannot be greater than the renewalAmount
 

Example: {"value" : "1.00", "currency" : "INR"}

TxnAmount
+
AttributeDescription
value
string
mandatory

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string
mandatory

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

userInfo
Object
mandatory

User information contains user details like customer ID, email, phone number etc.

UserInfo
+
AttributeDescription
custId
string
mandatory

Unique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,=,_ ,$, .
Example: CUST_001

mobile
string
conditional

10-digit mobile number of user.
Example: 9988000000

Mandatory, in case merchant wants to give Debit Card EMI as a payment option to its users.

email
string
optional

Valid email of the user.

Example: vaibhav41094@gmail.com

firstName
string
optional

First name of the user

lastName
string
optional

Last name of the user.

paytmSsoToken
string
optional

This is a unique token linked with the user's Paytm wallet and is provided in the response while linking the user's Paytm wallet.

callbackUrl
string
optional

AI router sends the response of the transaction on the URL which comes in the callbackUrl parameter.

Note: If not passed, the transaction response will be sent to the url configured against the parameter passed in websiteName. If the payment option is BANK_MANDATE, the response will be sent to the configured BM URL but not the websiteName parameter.

Example: https://<callback URL to be used by merchant>

extendInfo
Object
optional

Merchant can pass any order specific information that is required to be passed here

ExtendInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1.

udf2
string
optional

User define parameter 2.

udf3
string
optional

User define parameter 3.

mercUnqRef
string
optional

Merchant's reference text which comes in final response of Process Transaction API from Paytm

comments
string
optional

Comments

subscriptionAmountType
string
mandatory

The amount to be charged in each frequency cycle can be fixed or capped to max amount.
 

Possible values are :

FIX: Amount charged in each frequency cycle will be the same as renewalAmount
VARIABLE: Amount charged in each frequency cycle can be variable and capped by subscriptionMaxAmount

subscriptionMaxAmount
string
conditional

Maximum amount that can be charged to the customer in each frequency cycle. 

 

 Note: Mandatory only if subscriptionAmountType is VARIABLE.

renewalAmount
string
conditional

Amount to be charged to the customer in each frequency cycle.

 

 Note: Required only if subscriptionAmountType is FIX. If not passed, then txnAmount is considered as renewalAmount

autoRenewal
Boolean
optional

Preference to enable auto renewal for this subscription.
 

Possible values: true , false

autoRetry
Boolean
optional

Preference to enable auto retry for failed collect transactions.
 

Possible values: true , false

subscriptionFrequencyUnit
string
mandatory

This, combined with the interval, defines the frequency. The values supported for this attribute currently are: daily, weekly, monthly, and yearly. If the billing cycle is of 2 months, the value for this attribute would be monthly.

 

Possible Values: DAY, WEEK, MONTH, BI_MONTHLY, QUARTER, SEMI_ANNUALLY, YEAR, ONDEMAND

subscriptionFrequency
string
optional

Combined with subscriptionFrequencyUnit, defines the frequency of subsequent payment collection.
If the frequency cycle is of 2 months, attribute values can be: subscriptionFrequency: 2, subscriptionFrequencyUnit : MONTH
If the frequency cycle is of 15 days, attribute values can be : subscriptionFrequency: 15, subscriptionFrequencyUnit : DAY
By Default 1
 

subscriptionStartDate
string
mandatory

This is the date when the first payment collection can be charged to the customer. Subsequent payment collections can be charged by the customer after a definite period defined with subscriptionFrequency and subscriptionFrequencyUnit.


Format of Date YYYY-MM-DD
 

subscriptionGraceDays
string
conditional

Number of days after payment collection due date for which merchant can send renewal request.

 

 Note: Mandatory if subscriptionStartDate is sent on request.

  • Not supported for eNACH
  • Not supported for On-Demand frequency
  • For Cards, maximum 3 grace days are supported
subscriptionExpiryDate
string
mandatory

Date when subscription will expire. Payment collection requests will not be allowed after the expiry date. Format should be YYYY-MM-DD.

subscriptionPaymentMode
string
optional

The payment mode which the user has selected to complete creation and subsequent payment collection of subscription.
 

Possible Values: CC, DC, BANK_MANDATE and UPI

subscriptionEnableRetry
string
mandatory

Merchant can retry a transaction in case of failure from bank/wallet
Not supported for eNACH
 

Possible Values: 1 - For Enable Retry, 0 - Else

subscriptionRetryCount
string
optional

Count of payment collection retries allowed in case of failure of collection request .

  • In case grace days are not present : Retries are allowed on payment collection date only
  • In case grace days are present : Retries are allowed for the dates >= Payment collection date and <= Payment collection date + Grace days.

Not supported for eNACH
 

appInvokeDevice
string
conditional

For App Invoke Device (Payment via Paytm app).
 

Possible values: 3P , DEEPLINKQR

mandateAccountDetails
object
optional

Mandate Account Details, If the Mandate account details are already shared with the merchant the same can be passed here.

MandateAccountDetails
+
AttributeDescription
accountHolderName
string
optional

Account Holder Name

Example: Lalit Chaudhary

channelCode
string
optional

Account Holder's Bank Code

Example: SBI, HDFC, ICICI etc.
List of Bank Codes (Channel)

accountNumber
string
optional

Account Number

Example: 62980XXXX220

ifsc
string
optional

Bank IFSC

Example: ICIC00XX298

accountType
string
optional

Account Type

Possible values:
ISA
Savings Account
,
CA
Current Account
,
OTHERS
Others

Response Attributes

Content Type : JSON

Head

AttributeDescription
responseTimeStamp
string

EPOCH timestamp of the time at which response is being sent.
 

Example: 1588402269

signature
string

AI router validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.

 

 Note: Create the signature using the body parameter of the request.

Body

AttributeDescription
resultInfo
Object

This parameter gives the information about the result in the API response

resultInfo
+
AttributeDescription
resultStatus
string

This parameter is the result specific to the phase of the transaction mentioned in the txnType field

resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64.

resultMsg
string

This parameter is the result message which contains information about the result.

txnToken
string

AI router security token for a transaction valid for either one transaction or for 15 minutes. All subsequent API calls in creation will require this token.

subscriptionId
string

Unique Subscription ID generated by AI router for identifying a subscription transaction

Response Codes & Messages

resultCoderesultStatusresultMsg
0SSuccess
1007FMissing mandatory element
2013FMid in the query param doesn't match with the Mid send in the request
2014FOrderId in the query param doesn't match with the OrderId send in the request
2007FTxn amount is invalid
4001FInvalid Max Amount
4001FInvalid Subscription Frequency
4001FSubscription Amount Limit For UPI Breached
4001FInvalid Request Type
4001FSubscription not available
4001FInvalid Subscription Amount Type
4001FInvalid Customer Id
501FSystem Error
2006FMid is invalid
2022FPaymode selected is not enabled for your merchant account. Please reach out to support teams to enable
1102TXN_FAILURESubscription already in progress
1102TXN_FAILUREInvalid subscription max amount value
1102TXN_FAILUREInvalid subscription expiry date
1102TXN_FAILUREInvalid subscription start date
1102TXN_FAILUREInvalid grace days for subscription
1102TXN_FAILUREUnsupported subscription payment mode
1102TXN_FAILUREInvalid renewal amount
1102TXN_FAILUREInvalid subscriptionEnableRetry value
1102TXN_FAILUREInvalid subscription retry count value
1102TXN_FAILURESubscription has been disabled for your merchant account. Please reach out to support teams to enable the same
1102TXN_FAILUREMaximum Subscription Amount limit breached
1102TXN_FAILUREOnDemand Subscriptions are not allowed on merchant
1102TXN_FAILURESubscription Count limit breached
⇾
Staging
Production
https://stage-router.paytm.in/aoa-subscription/api/v2/subscription/create?mid={mid}&orderId={orderId}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl --location 'https://stage-router.paytm.in/aoa-subscription/api/v2/subscription/create?mid=YOUR_MID_HERE&orderId=arjun335' \
--header 'Content-Type: application/json' \
--data '{"head": {"requestTimestamp": "Time","channelId": "WEB","signature": "Hr4lmS2AvY9RwwaB+ao0nSKvj4oBB6mVsELooMY6iEooJjYqVXKirMOoOYdaFomh9hsQCoFGF1KXDKuGlqRSFiS5+MYUqZajgzMuQmSq/5o="},"body": {"mid": "YOUR_MID_HERE","requestType": "SUBSCRIPTION","orderId": "arun335","websiteName": "retail","txnAmount": {"value": "1","currency": "INR"},"subscriptionPaymentMode": "BANK_MANDATE","subscriptionAmountType": "VARIABLE","subscriptionMaxAmount": "1000","subscriptionFrequency": "15","subscriptionFrequencyUnit": "MONTH","subscriptionExpiryDate": "2024-07-15","subscriptionGraceDays": "1","subscriptionStartDate": "2023-05-16","subscriptionRetryCount": "1","userInfo": {"custId": "CUD316","mobile": "","email": "","firstName": "","lastName": ""},"callbackUrl": "https://pg-staging.paytm.in/MerchantSite/bankResponse","extendInfo": {"udf1": "","udf2": "","udf3": "","mercUnqRef": "","comments": ""}}}'




 
copy icon