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

Attribute	Description
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

Attribute

Description

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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute	Description
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

Attribute

Description

resultInfo

Object

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

resultInfo

Attribute	Description
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

resultCode	resultStatus	resultMsg
0	S	Success
1007	F	Missing mandatory element
2013	F	Mid in the query param doesn't match with the Mid send in the request
2014	F	OrderId in the query param doesn't match with the OrderId send in the request
2007	F	Txn amount is invalid
4001	F	Invalid Max Amount
4001	F	Invalid Subscription Frequency
4001	F	Subscription Amount Limit For UPI Breached
4001	F	Invalid Request Type
4001	F	Subscription not available
4001	F	Invalid Subscription Amount Type
4001	F	Invalid Customer Id
501	F	System Error
2006	F	Mid is invalid
2022	F	Paymode selected is not enabled for your merchant account. Please reach out to support teams to enable
1102	TXN_FAILURE	Subscription already in progress
1102	TXN_FAILURE	Invalid subscription max amount value
1102	TXN_FAILURE	Invalid subscription expiry date
1102	TXN_FAILURE	Invalid subscription start date
1102	TXN_FAILURE	Invalid grace days for subscription
1102	TXN_FAILURE	Unsupported subscription payment mode
1102	TXN_FAILURE	Invalid renewal amount
1102	TXN_FAILURE	Invalid subscriptionEnableRetry value
1102	TXN_FAILURE	Invalid subscription retry count value
1102	TXN_FAILURE	Subscription has been disabled for your merchant account. Please reach out to support teams to enable the same
1102	TXN_FAILURE	Maximum Subscription Amount limit breached
1102	TXN_FAILURE	OnDemand Subscriptions are not allowed on merchant
1102	TXN_FAILURE	Subscription 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": ""}}}'