POSTRenew Subscription API

Use Case

To request payment collection for an ongoing subscription. These payment collections are requested with subscription ID provided at the time of creation of subscription
In case, the payment collection gets failed from the bank and retry is set on the subscription, retry can also be initiated using this API

Note

The success of this API suggests that Paytm has accepted the payment collection request post completion of validations against the created subscription (plan details). This does not mean that money has been deducted from customers account. Once accepted, we initiate the payment collection against the set payment instrument. Upon completion, the same is notified to you on your callback URL

Payment collection requests cannot be initiated against expired or cancelled subscriptions

Only one payment collection request can be initiated for a subscription in a frequency cycle

Request Attributes

Content Type : JSON

Head

Attribute	Description
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: 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(108) 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

Attribute

Description

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

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

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

subscriptionId

string(64)

mandatory

Unique subscription Id generated by Paytm for identifying a subscription.

debitDate

string

optional

For Future Date of debit

Format: YYYY-MM-DD HH:mm:ss
(Not required to process current date debit)

Example: 2020-04-20 00:00:00

splitSettlementInfo

object

optional

Send only in case split settlement required

splitSettlementInfo

Attribute

Description

splitInfo

object

mandatory

List for child vendor merchant mid's and their split info

splitInfo

Attribute	Description
mid string conditional	Child mid
partnerId string conditional	Id created for child mid
amount string conditional	Share of child vendor in the split by amount base Use: Only splitMethod is AMOUNT
percentage string conditional	Share of child vendor in the split by percentage base Use: Only splitMethod is PERCENTAGE
extendInfo string optional	Specific information related to split info that is required to be passed

splitMethod

string

mandatory

Split method
Possible Values: AMOUNT, PERCENTAGE

prenotifyReferenceId

string

optional

referenceId sent in prenotify request

extendInfo

Map<String , String>

optional

Merchant can pass any order specific information that is required to be passed here like mercUnqRef, Udf1 etc.

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

Response Attributes

Content Type : JSON

Head

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

Attribute

Description

resultInfo

object

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

ResultInfo

Attribute	Description
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 For Success , F For Failure
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 in section " Response Codes and Messages".

txnId

string(64)

This is a unique Paytm transaction ID that is issued by Paytm for each transaction.

Response Codes & Messages

resultCode	resultStatus	resultMsg
900	S	Subscription Txn accepted.
156	F	Per day Txn amount is crossed for Paytm
158	F	Per Month Txn amount is crossed for Paytm
165	F	User has crossed the monthly debit limit prescribed by RBI
196	F	Payment failed as amount entered exceeds the allowed limit. Please enter a lower amount and try again or reach out to the merchant for further assistance
202	F	Your payment is declined by the bank due to insufficent funds in your account. Please try again by using a different method to complete the payment.
227	F	Your payment has failed due to a technical error. Please try again or use a different method to complete the payment.
313	F	Invalid SavedCardID
325	F	Duplicate Order Id
501	F	System Error
505	F	Please try with lower amount or different payment mode. Transaction limits will revise as you continue using Paytm.
901	F	Subscription not available
905	F	Invalid Transaction Amount
910	F	Subscription is not configured for the merchant.
913	F	Invalid subscription amount type.
919	F	Merchant Not Found
924	F	Wallet balance Insufficient
928	F	Subscription Renewal Rejected.
929	F	Invalid Subscription Details.
931	F	Subscription already in progress.
935	F	Subscription has been already cancelled.
945	F	Manual renewal is not allowed as subscription has auto renewal preference configured.
947	F	Manual retry is not allowed on subscription where autorenewal or auto retry is configured.
1102	F	Something wents down, We are fixing the same
1103	F	The Debit Date is invalid
1104	F	Renewal request is already pending in this frequency cycle. This subscription is suspended. Renewal retry in progress. Please try after sometime.
1105	F	The Debit Date is beyond Subscription End Date
1106	F	Debit on a later date functionality not available for the the paymode linked to your subscription
2005	F	Checksum provided is invalid
3054	F	Prenotify not found for the given params

⇾

Staging

Production

https://securestage.paytmpayments.com/subscription/renew?mid={mid}&orderId={order-id} copy icon

REQUEST

RESPONSE

CURL

JAVA

NODE

PHP

PYTHON

DOTNET

curl -X POST 'https://securestage.paytmpayments.com/subscription/renew?mid={mid}&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","orderId":"ORDERID_98765","subscriptionId":"67491","txnAmount":{"value":"1.00","currency":"INR"}},"head":{"signature":"{signature}"}}'