Initiate Subscription API

Checksum required: YES

Use Case


  • To create a subscription with required subscription details like upfront amount, renewal frequency, renewal amount type etc. A subscription ID is provided in return which needs to be stored and passed in corresponding renewal 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:

API Content format: JSON

Head

PARAMETERDESCRIPTIONMANDATORY
clientId
String (3)
Mandatory
ClientId by which key checksum is created, required to validate the checksum. Eg C11No
version
String (4)
Mandatory
Version of the API. Current version is v1Yes
requestTimestamp
String (15)
Mandatory
UNIX timestamp of the time request is being sentYes
channelId
String (3)
Optional

For websites, the value is WEB
For Mobile websites/App, the value is WAP
No
signature
String (108)
Mandatory
Checksum string created by using Paytm checksum logicYes

Body

PARAMETERDESCRIPTIONMANDATORY
requestType
String (30)
Mandatory
Define the type of transaction. For subscription, the value is “NATIVE_SUBSCRIPTION”Yes
mid
String (20)
Mandatory
This is a unique identifier provided to every merchant by PaytmYes
orderId
String (32)
Mandatory
Unique reference ID for a transaction which is generated by merchant and sent in the requestYes
websiteName
String (30)
Mandatory
For staging environment: For staging environment: WEBSTAGING
For production environment: Will be available here once your activation is complete
Yes
txnAmount
Json object
Mandatory
Transaction amount and the currency type
Child Attribute
Yes
userInfo
Json object
Mandatory
Customer details like merchant customer ID, email, phone number etc
Child Attribute
Yes
paytmSsoToken
String (30)
Mandatory
Paytm Token for a user. This will not be available for merchants outside Paytm ecosystemNo
callbackUrl
String (255)
Optional
On completion of transaction, Paytm payment gateway will send the response on this URL.. Sample URL is - https://merchant.com/callback/No
extendInfo
Json object
Optional
Merchant can pass any order specific information that is required to be passed here
Child Attribute
No
subscriptionAmountType
String (10)
Mandatory
Renewal amount of subscription can be fixed or capped to max amount. Possible values are
1. FIX: Amount charged in all renewal transactions will be same as txnAmount
2. VARIABLE: Renewal amount can be variable and capped by subscriptionMaxAmount
Yes
subscriptionMaxAmount
String (10)
Conditional
Maximum amount that can be deducted in a subscription request. Mandatory: if subscriptionAmountType is VARIABLEConfidential
subscriptionFrequencyUnit
String (10)
Mandatory
This, combined with 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.Yes
subscriptionFrequency
String (5)
Mandatory
Combined with subscriptionFrequencyUnit, defines the frequency of renewal transaction. If the renewal cycle is of 2 months, attribute values can be:
subscriptionFrequency: 2, subscriptionFrequencyUnit : MONTH
If the renewal cycle is of 15 days, attribute values can be :
subscriptionFrequency: 15, subscriptionFrequencyUnit : DAY
Yes
subscriptionStartDate
String (20)
Conditional
This is the date when first renewal transaction can be charged to the customer. Subsequent renewals can be charged by customer after a definite period defined with subscriptionFrequency and subscriptionFrequencyUnit. Format of date is YYYY-MM-DD
Mandatory if subscriptionGraceDays is provided
Yes
subscriptionGraceDays
String (2)
Conditional
Number of days after renewal cycle start date for which merchant can send renewal request.
Mandatory: If subscriptionStartDate is sent in this request
Confidential
subscriptionExpiryDate
String (10)
Mandatory
Date when subscription will expire. Renewal transactions will not be allowed after the expiry date. Format should be YYYY-MM-DDYes
subscriptionPaymentMode
String (5)
Mandatory
The payment mode which user has selected to complete creation and renewal of subscription
Possible values: CC, DC, PPI
Yes
subscriptionEnableRetry
String (2)
Mandatory
Merchant can retry a transaction in case of failure from bank/wallet
Possible Value: 0 or 1
Yes
subscriptionRetryCount
String (2)
Optional
Count of renewal retries allowed in case of failure renewal fails.
In case grace days are not present : Retries are allowed on renewal date only
In case grace days are present : Retries are allowed dates >= renewal date and <= Renewal Date + Grace days
No

Response Attributes

API Content format: JSON

Head

PARAMETERDESCRIPTION
clientId
String (3)
ClientId by which key checksum is created, required to validate the checksum. Eg C11
Version
String (2)
Version of the API passed in the request
responseTimestamp
String (15)
UNIX Timestamp of the response
Signature
String (108)
Checksum string created by Paytm from response parameters

Body

PARAMETERDESCRIPTION
txnToken
String (64)
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 (64)
Unique subscription id generated by Paytm for identifying a subscription
authenticatedTrue, If token is verified for Wallet transaction, else False
resultInfo
Json object
Information related to response of the request

Initiate Subscription Response Codes, Messages and Status

CODEMESSAGESTATUS
0000Subscription initiated successfullySuccess
1007Missing mandatory elementFail
1008Pipe character is not allowedFail
2004SSO Token is invalidFail
2007Txn amount is invalidFail
2009Duplicate request, with same orderId is already in progressFail
2013Mid in the query param doesn’t match with the Mid send in the requestFail
2014OrderId in the query param doesn’t match with the OrderId send in the requestFail
00000900System errorFail

Endpoints

Staging: https://securegw-stage.paytm.in/subscription/create?mid=<mid>&orderId=<orderId>

Production: https://securegw.paytm.in/subscription/create?mid=<mid>&orderId=<orderId>

Request CodeResponse JSON
curl -X POST 'https://securegw-stage.paytm.in/subscription/create?mid=xxxxxxxxxxxxxxxxxxxx&orderId=ORDER_xxxxxxxxxx' --header 'Content-Type: application/json' --data '{"body":{"requestType":"NATIVE_SUBSCRIPTION","mid":"xxxxxxxxxxxxxxxxxxxx","websiteName":"dineoutWEB","orderId":"ORDER_xxxxxxxxxx","subscriptionPaymentMode":"PPI","subscriptionAmountType":"VARIABLE","txnAmount":{"value":"100.00","currency":"INR"},"subscriptionMaxAmount":"200.00","subscriptionFrequency":"1","subscriptionFrequencyUnit":"MONTH","subscriptionStartDate":"2019-05-01","subscriptionExpiryDate":"2019-12-31","subscriptionGraceDays":"5","subscriptionEnableRetry":"1","subscriptionRetryCount":"3","userInfo":{"custId":"xxxxxxx"},"paytmSsoToken":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx","callbackUrl":"https://pg-stage.paytm.in/MerchantSite/bankResponse"},"head":{"clientId":"C11","version":"v1","requestTimestamp":xxxxxxxxxx,"channelId":"WEB","signature":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx+xxxxxx="}}'