paytm developer docs logoDeveloperDocumentation
search

POSTInitiate Subscription API

Use Case

  • To create a subscription with required subscription details like upfront transaction amount, frequency, subscription amount type etc. A subscription ID is provided in return which needs to be stored and passed in corresponding payment collection and cancellation requests.
  • To generate a transaction token. This token is valid for 15 minutes from the time of its creation. This token enables you to call all the subsequent APIs while creation of subscription from your client.

Request Attributes

Content Type : JSON

Head

AttributeDescription
clientId
string
optional

Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

Example: C11

version
string
optional

Version of the API.

Example: v1

requestTimestamp
string
optional

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

channelId
string
optional

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

Possible values:
WEB
For websites, the value to be passed should be "WEB"
,
WAP
For Mobile websites/App, the value to be passed should be "WAP"
signature
string
mandatory

Paytm 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
requestType
string
mandatory

This parameter is used to identify the transaction flow.

Its value shall be as mentioned below:

'NATIVE_SUBSCRIPTION' for 'Subscription'.

mid
string
mandatory

Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.

Example: INTEGR7769XXXXXX9383

orderId
string(50)
mandatory

The Unique reference ID of the Order. It is alphanumeric and special characters allowed are “@” “-” “_” “.”.
Example: OREDRID_98765

websiteName
string
mandatory

This is provided by Paytm and it defines the static response URL.
Example: WEBSTAGING, DEFAULT
Note: other websiteName provided by paytm

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 user's Paytm wallet and is provided in the response while linking user's Paytm wallet.

Example: eyJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiZGlyIn0..xxxxxxxxxxx.9iHTtWbCZ0I6qbn2sUnyz5siw1fqbmtEnFMFE7nSIX-yrwCkiGfAC6QmPr9q-tw8LMPOh5-3UXRbpeVZEupQd3wNyaArWybRX2HAxJDRD8mxJ_wxzJM6GZ1ov4O3EIsx2Y_Zr0aHCd3VbnTjRUnlVdxXJPFG8QZs0b_2TVdoAX3_QjZS8_dwcmIWoH8ebDzOIs7MJacETfMtyFGAo8Xc0LjznToUWvTsTbIXQoF1yB0.1fZFAYJVsY61BTv2htLcXQ8800/

callbackUrl
string
optional

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

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

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 configured BM URL but not the websiteName parameter.
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 :

  1. FIX: Amount charged in each frequency cycle will be the same as renewalAmount
  2. 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. 

Mandatory: Only if subscriptionAmountType is VARIABLE.

renewalAmount
string
conditional

Amount to be charged to the customer in each frequency cycle.
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
To enable Autorenewal
,
false
Else
autoRetry
boolean
optional

Preference to enable auto retry for failed collect transactions.

Possible values:
true
To enable Autoretry
,
false
Else
communicationManager
boolean
optional

Preference to enable sending notification to customers for the subscription events.

subscriptionFrequencyUnit
string
mandatory

This, combined with interval, defines the frequency. The values supported for this attribute currently are: weekly, monthly, bimonthly, quarterly, semi-annually, yearly and on-demand (as presented). If the billing cycle is of 2 months, the value for this attribute would be BI_MONTHLY.
Possible Values:  WEEK, MONTH, BI_MONTHLY, QUARTER, SEMI_ANNUALLY, YEAR, ONDEMAND

subscriptionStartDate
string
mandatory

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

Format of date is YYYY-MM-DD

subscriptionGraceDays
string
conditional

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

Mandatory if subscriptionStartDate is sent in 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 request will not be allowed after the expiry date. Format should be YYYY-MM-DD.

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
By Default
,
DEEPLINKQR
Payment By QR
mandateType
string
conditional

Required in Bank Mandate

Possible Values: E_MANDATE, PAPER_MANDATE

mandateAccountDetails
object
optional

Mandate Account Detail - For Stardard Checkout (Redirection Flow)

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
enablePaymentMode
Array of objects
optional

List of the payment modes which needs to enable. If the value provided then only listed payment modes are available for transaction.
Example: [{"mode" : "UPI", "channels" : ["UPIPUSH"]}]

PaymentMode
+
AttributeDescription
mode
string
optional

Mode of Payment BALANCE, 
PPBL, UPI, 
CREDIT_CARD 
DEBIT_CARD 
BANK_MANDATE 
PAYTM_DIGITAL_CREDIT

channels
Array of strings
optional

Channel associated with mode.
Possible Values:
For UPI: 
UPI 
UPIPUSH 
UPIPUSHEXPRESS
For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX

disablePaymentMode
Array of objects
optional

List of the payment modes which need to disable. If the value provided then all the listed payment modes are unavailable for transaction.
Example: [{"mode" : "UPI", "channels" : ["UPIPUSH"]}]

PaymentMode
+
AttributeDescription
mode
string
optional

Mode of Payment BALANCE, 
PPBL, UPI, 
CREDIT_CARD 
DEBIT_CARD 
BANK_MANDATE 
PAYTM_DIGITAL_CREDIT

channels
Array of strings
optional

Channel associated with mode.
Possible Values:
For UPI: 
UPI 
UPIPUSH 
UPIPUSHEXPRESS
For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX

Response Attributes

Content Type : JSON

Head

AttributeDescription
clientId
string(3)

Paytm use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

Example: C11

version
string(2)

Version of the API passed in the request.
Example: v1

responseTimestamp
string(15)

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

signature
string(108)

You should validate the parameter values by verifying the signature comes in the response. It ensures that parameter values not tempered. Signature string can be verified by using Paytm checksum library.

Body

AttributeDescription
resultInfo
object

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

ResultInfo
+
AttributeDescription
resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64. The different result codes corresponding to this API are mentioned below.

resultStatus
string

This parameter indicates the status of API call.

Possible Values: S, F, U

resultMsg
string

This parameter is the result message which contains information about the result.The different result messages corresponding to this API are mentioned below.
 

txnToken
string

Paytm 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 Paytm for identifying a subscription.

authenticated
boolean

True when ssoToken is provided in request and it is valid.

Response Codes & Messages

resultCoderesultStatusresultMsg
0000SSubscription initiated successfully
900USystem error
1007FMissing mandatory element
1008FPipe character is not allowed
2004FSSO Token is invalid
2005FChecksum provided is invalid
2007FTxn amount is invalid
2009FDuplicate request, with same orderId is already in progress
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
2022FInvalid Subs payment mode
2022FPaymode selected is not enabled for your merchant account. Please reach out to support teams to enable
4001FInvalid Subscription start date.
4001FInvalid Frequency Unit
4001FInvalid Subscription Amount Type
4001FInvalid Max Amount
4001FGrace days cannot be greater than the frequency set against the subscription
4001FTxn Amount can not be non-zero in case of Bank Mandates
4001FInvalid AppInvokeDevice
4001FGrace days value is mandatory
4004FMax amount is greater than the permissible amount limit for available paymodes
4006FAdd and Pay Payments are not allowed for this subscription
00000900FTransaction amount cannot be greater than the max amount set against the subscription
⇾
Staging
Production
https://securestage.paytmpayments.com/subscription/create?mid={mid}&orderId={order-id}copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securestage.paytmpayments.com/subscription/create?mid={mid}&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"body":{"requestType":"NATIVE_SUBSCRIPTION","mid":"{mid}","websiteName":"WEBSTAGING","orderId":"ORDERID_98765","subscriptionAmountType":"FIX","subscriptionEnableRetry":"1","subscriptionFrequencyUnit":"MONTH","subscriptionExpiryDate":"2031-05-20","txnAmount":{"value":"10.00","currency":"INR"},"userInfo":{"custId":"CUST_001"},"callbackUrl":"https://merchant.com/callback"},"head":{"signature":"{signature}"}}'
copy icon