• Getting Started
    • Mobile Integration (Android/IOS)
      Enterprise Solutions
      Retail Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Testing
      Refunds
      Guides
      Other Processes
      Mini Program Platform

      post Initiate Subscription API

      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 Type: JSON

      Head1

      Head

      ATTRIBUTEDESCRIPTION
      clientId string(3)
      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(4)
      optional
      Version of the API.
      Example: v1
      requestTimestamp string(15)
      optional
      EPOCH timestamp of the time at which request is being sent.
      Example: 1588402269
      channelId string(3)
      optional
      The parameter value identifies the Channel for which API call is initiated.
      Possible Values: WEBFor websites, the value to be passed should be "WEB", WAPFor Mobile websites/App, the value to be passed should be "WAP"
      signature string(108)
      mandatory
      Paytm validates the parameter values by verifying the signature comes in the request. It ensures that parameter values are not tempered. Signature string can be created by using Paytm checksum library
      Body1

      Body

      ATTRIBUTEDESCRIPTION
      requestType string(30)
      mandatory
      This parameter is used to identify the transaction flow. Its value shall be as mentioned below:
      1. 'NATIVE_SUBSCRIPTION' for 'Subscription'.
      mid string(20)
      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(30)
      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
      This parameter is an object and should contain the value of transaction i.e. amount and currency type
      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(INR)
      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(32)
      mandatory
      Unique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,_ ,$, .
      Example: CUST_001
      mobile string(10)
      optional
      10-digit mobile number of user
      Example: 7777777777
      email string(32)
      optional
      Valid email of the user
      firstName string(32)
      optional
      First name of the user
      lastName string(32)
      optional
      Last name of the user
      paytmSsoToken string(30)
      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: ae74f8b5-be5f-4503-XXXX-a60c9dcd3300
      callbackUrl string(255)
      optional
      Paytm sends the response of transaction on the URL which comes in the callbackUrl parameter.
      Example: https://merchant.com/callback/
      extendInfo object
      optional
      Merchant can pass any order specific information that is required to be passed here.
      ExtendInfo +
      AttributeDescription
      udf1 string(64)
      optional
      User define parameter 1
      udf2 string(64)
      optional
      User define parameter 2
      udf3 string(64)
      optional
      User define parameter 3
      mercUnqRef string(64)
      optional
      Merchant's reference text which comes in final response of Process Transaction API from Paytm
      comments string(256)
      optional
      Comments
      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
      subscriptionMaxAmount string(10)
      conditional
      Maximum amount that can be deducted in a subscription request. Mandatory: if subscriptionAmountType is VARIABLE
      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.
      Possible Values: DAY, WEEK, MONTH, BI_MONTHLY, QUARTER, SEMI_ANNUALLY, YEAR
      subscriptionFrequency string(5)
      optional
      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
      By Default 1
      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 sent in request
      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 request.
      subscriptionExpiryDate string(10)
      mandatory
      Date when subscription will expire. Renewal transactions will not be allowed after the expiry date. Format should be YYYY-MM-DD.
      subscriptionPaymentMode string(5)
      optional
      The payment mode which user has selected to complete creation and renewal of subscription.
      Possible Values: CC, DC, PPI and BANK_MANDATE
      subscriptionEnableRetry string(2)
      mandatory
      Merchant can retry a transaction in case of failure from bank/wallet
      Possible Values: 1 - For Enable Retry, 0 - Else
      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.
      appInvokeDevice string
      conditional
      For App Invoke Device (Payment via Paytm app).
      Possible Values: 3PBy Default, DEEPLINKQRPayment 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: ISASavings Account, CACurrent Account, OTHERSOthers

      Response Attributes


      API Content Type: JSON

      Head2

      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)
      Paytm validates the parameter values by verifying the signature comes in the request. It ensures that parameter values are not tempered. Signature string can be created by using Paytm checksum library
      Body2

      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: SUCCESS, FAILED
      resultMessage string(256)
      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(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.
      authenticated boolean
      True when ssoToken is provided in request and it is valid.

      Response Codes and Messages


      resultCoderesultStatusresultMsg
      0000SSubscription initiated successfully
      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
      4001FInvalid Subscription start date.
      Invalid Frequency Unit
      00000900USystem error
      StagingProduction
      REQUESTRESPONSE
      curl -X POST 'https://securegw-stage.paytm.in/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","subscriptionFrequency":"2","subscriptionFrequencyUnit":"MONTH","subscriptionExpiryDate":"2031-05-20","txnAmount":{"value":"10.00","currency":"INR"},"userInfo":{"custId":"CUST_001"},"callbackUrl":"https://merchant.com/callback"},"head":{"signature":"{signature}"}}'