• Getting Started
    • Website Integration
      Mobile Integration (Android/IOS)
      Enterprise Solutions
      Accept Payments
      Process Payments
      Disbursals
      API References
      Webhooks
      Testing
      Refunds
      Guides
      Other Processes

      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

      ATTRIBUTEDESCRIPTIONMANDATORY
      clientId
      String (3)
      ClientId by which key checksum is created, required to validate the checksum. Eg C11.No
      version
      String (4)
      version of the API. Current version is v1.No
      requestTimestamp
      String (15)
      UNIX timestamp of the time request is being sent.No
      channelId
      String (3)

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

      Body

      ATTRIBUTEDESCRIPTIONMANDATORY
      requestType
      String (30)
      This parameter is used to identify the transaction flow. For subscription, the value is “NATIVE_SUBSCRIPTION”.Yes
      mid
      String (20)
      This is a unique identifier provided to every merchant by Paytm.Yes
      orderId
      String (32)
      Unique reference ID for a transaction which is generated by merchant and sent in the request.Yes
      websiteName
      String (30)
      This is provided by Paytm and it defines the static response URL.
      For staging environment: WEBSTAGING.
      Yes
      txnAmount
      TxnAmount
      Transaction amount and the currency type
      Child Attribute
      Yes
      userInfo
      UserInfo
      User information contains user details like merchant customer ID, email, phone number etc.
      Child Attribute
      Yes
      paytmSsoToken
      String (30)
      Paytm Token for a user. This will not be available for merchants outside Paytm ecosystem.No
      callbackUrl
      String (255)
      On completion of transaction, Paytm payment gateway will send the response on this URL.. Sample URL is - https://merchant.com/callback/.No
      extendInfo
      ExtendInfo
      Merchant can pass any order specific information that is required to be passed
      Child Attribute
      No
      subscriptionAmountType
      String (10)
      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)
      Maximum amount that can be deducted in a subscription request. Mandatory: if subscriptionAmountType is VARIABLE.Conditional
      subscriptionFrequencyUnit
      String (10)
      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)
      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)
      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.
      Conditional
      subscriptionGraceDays
      String (2)
      Number of days after renewal cycle start date for which merchant can send renewal request.
      Mandatory if subscriptionStartDate is sent in request.
      Conditional
      subscriptionExpiryDate
      String (10)
      Date when subscription will expire. Renewal transactions will not be allowed after the expiry date. Format should be YYYY-MM-DD.Yes
      subscriptionPaymentMode
      String (5)
      The payment mode which user has selected to complete creation and renewal of subscription
      Possible values: CC, DC, PPI.
      No
      subscriptionEnableRetry
      String (2)
      Merchant can retry a transaction in case of failure from bank/wallet
      Possible Value: 0 or 1.
      Yes
      subscriptionRetryCount
      String (2)
      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

      Head

      ATTRIBUTEDESCRIPTION
      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 using Paytm checksum library.

      Body

      ATTRIBUTEDESCRIPTION
      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.
      resultInfoInformation related to response of the request.

      ResultInfo

      ATTRIBUTEDESCRIPTIONMANDATORY
      resultCodeStringResult code returned to merchant . Max length of result code can be 64.Yes
      resultStatusStringStatus of API call
      String
      (S:Success, F:Failure, U:Unknown).
      Yes
      resultMsgString(256)Result Message contains information about the result.Yes

      Response Codes and Messages

      resultCoderesultStatusresultMsg
      0000SSubscription initiated successfully
      1007FMissing mandatory element
      1008FPipe character is not allowed
      2004FSSO Token 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
      00000900USystem error

      Endpoints

      Staging: https://securegw-stage.paytm.in/subscription/create?mid={mid}&orderId={order-id}

      Production: https://securegw.paytm.in/subscription/create?mid={mid}&orderId={order-id}

      Request CodeResponse JSON
      curl -X POST 'https://securegw-stage.paytm.in/subscription/create?mid={mid}&orderId={order-id}' --header 'Content-Type: application/json' --data '{"body":{"requestType":"NATIVE_SUBSCRIPTION","mid":"{mid}","websiteName":"{website-name}","orderId":"{order-id}","subscriptionAmountType":"{subscription-amount-type}","subscriptionEnableRetry":"{subscription-enable-retry}","subscriptionFrequency":"{subscription-frequency}","subscriptionFrequencyUnit":"{subscription-frequency-unit}","subscriptionExpiryDate":"{YYYY-MM-DD}","txnAmount":{"value":"{transaction-amount-value}","currency":"{transaction-amount-currency}"},"userInfo":{"custId":"{customer-id]}"},"callbackUrl":"{callback-url}"},"head":{"signature":"{signature}"}}'