Refund API

Checksum required: YES

Use Case


To initiate partial or complete refund of transaction done one Paytm payment gateway

Request Attributes:

API Content format: JSON

Head

NameDESCRIPTIONMANDATORY
versionString (4) Version of the API. Current version is v1 YES
signatureString (108) Checksum string created by using Paytm checksum logic YES
requestTimestampString (15) EPOCH timestamp of the time request is being sent NO
clientIdString (3) This is used in case of merchant has two different merchant keys. In case one merchant key merchant should pass - C11 YES
channelIdString (3) For websites, the value is WEB For Mobile websites/App, the value is WAPNO

Body

NameDESCRIPTIONMANDATORY
midString(20) This is a unique identifier provided to every merchant by Paytm. MID is part of your account credentials and is different on staging and production environment. Your staging MIDs is available here & production MID will be available once your activation is completeYES
orderIdString (50)Order ID is merchant’s unique reference ID against which the refund transaction is being placed. OrderID is provided by merchant in transaction request payloadYES
refIdString (50)Unique reference ID for refund transaction which is generated by merchant . Duplicate REFID will be rejected by the Paytm gatewayYES
txnIdString (64)TXNID is Paytm payment transaction ID against which the refund transaction is being placed. TXNID is provided in response payload for every payment transactionYES
refundAmountStringIn case of non PCF refunds value to be passed is "REFUND"In case of PCF refunds, there are two additional scenarios where complete amount needs to be refunded: - R:- if the commission amount needs to refunded back to the customer. This is used in case of merchant cancellation of complete order C:- If the commission amount needs to be retained. This is used in case of customer cancellation of complete orderYES
commentsString (500)For refunds to source, merchant need not pass this parameter. In case merchant has taken instant refund solution from Paytm and customer has given a permission to refund into his bank account, then the value to be passed is To_Instant NO

Response Attributes:

Head

NAMEDescription
versionString (4) Version of the API. Current version is v1
clientIdString (3) This is used in case of merchant has two different merchant keys. In case one merchant key merchant should pass - C11
channelIdString (3)For websites, the value is WEB For Mobile websites/App, the value is WAP
requestTimestampString (15) EPOCH timestamp of the time request is being sent
signature String (108) Checksum string created by using Paytm checksum logic

Body

NAMEDescription
midString (20)This is a unique identifier provided to every merchant by Paytm
orderIdString (50)Order ID is merchant’s unique reference ID against which the refund transaction is being placed
refIdString (50)Merchant’s reference ID unique for every refund transaction. This is REFID for which refund status is being inquired
refundAmountString (10)Amount for which refund is supposed to be made. It can be equal to or lesser than the transaction amount. It should be upto two decimal place. Should not include any separator like (“,”)
refundIdString (50)Merchant’s reference ID unique for every refund transaction. This is REFID for which refund status is being inquired
resultInfoResultInforesultInfo Object
txnAmountString (10)Order value of the transaction in INR
txnIdString (64)TXNID is Paytm payment transaction ID against which the refund transaction is being placed
txnTimestampString (20)Timestamp of payment transaction

resultInfo

NAMEDescriptionMANDATORY
resultStatusenumResult Status of transactionYES
resultCodestringResult code returned to merchant . Max length of result code can be 64YES
resultMsgstringResult Message corresponding to transactionYES

Response Code

Result CodeResult StatusResult Message
330TXN_FAILUREChecksum provided is invalid
335TXN_FAILUREMid is invalid
10TXN_SUCCESSRefund Successful
600TXN_FAILUREInvalid refund request.
607TXN_FAILURERefund can not be initiated for a cancelled transaction.
630TXN_FAILURERefund amount mismatch with TxnType:R
619TXN_FAILUREInvalid refund amount
501PENDINGSystem Error
601PENDINGRefund request was raised for this transaction. But it is pending state.
617TXN_FAILURERefund Already Raised
626TXN_FAILURENot allowed to reprocess refund request
628TXN_FAILURERefund is in Pending state.Please check status query for final result
627TXN_FAILUREOrder Details Mismatch
624TXN_FAILURESystem Error
629TXN_FAILURERefund is already Successful
501TXN_FAILUREApplication Down

Checksum Generation Utility

For Web:

For App:


Endpoints

Staging: https://securegw-stage.paytm.in/refund/api/v1/async/refund

Production: https://securegw.paytm.in/refund/api/v1/async/refund

Request CodeResponse JSON
curl -X POST 'https://securegw-stage.paytm.in/refund/api/v1/async/refund' --header 'Content-Type: application/json' --data '{"body":{"mid":"xxxxxxxxxxxxxxxxxxxx","txnType":"REFUND","orderId":"xxxxxxxxxxxxxxxx","txnId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","refId":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx","refundAmount":"1.00"},"head":{"clientId":"C11","version":"v1","signature":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}}'

Old Refund API

Checksum required: YES

We do not recommend you to use this API. We will soon deprecate this API

Use Case


To initiate partial or complete refund to source account from which the transaction was done

Request Attributes:

API Content format: JSON

PARAMETERDESCRIPTION
MID String(20) MandatoryThis is a unique identifier provided to every merchant by Paytm. MID is part of your account credentials and is different on staging and production environment. Your staging MIDs is available here & production MID will be available once your activation is complete
REFID String(50) MandatoryUnique reference ID for refund transaction which is generated by merchant . Duplicate REFID will be rejected by the Paytm gateway
TXNID String(64) MandatoryTXNID is Paytm payment transaction ID against which the refund transaction is being placed. TXNID is provided in response payload for every payment transaction
ORDERID String(50) MandatoryOrder ID is merchant’s unique reference ID against which the refund transaction is being placed. OrderID is provided by merchant in transaction request payload
REFUNDAMOUNT String(10) MandatoryAmount for which refund is supposed to be made. It can be equal to or lesser than the transaction amount. It should be upto two decimal place. Only special character allowed is (“.”)
TXNTYPE String MandatoryThis has fixed value for refund transaction - "REFUND"
CHECKSUM String(108) MandatorySignature to avoid tampering. Generated using server side checksum utility available here
COMMENTS String(50) OptionalComments can be given by merchant citing the reason for refund

Response Attributes:

API Content format: JSON

PARAMETERDESCRIPTION
MID String(20)This is a unique identifier provided to every merchant by Paytm
TXNID String(64)TXNID is Paytm payment transaction ID against which the refund transaction is being placed
ORDERID String(50)Order ID is merchant’s unique reference ID against which the refund transaction is being placed
REFUNDAMOUNT String(10)Amount for which refund is supposed to be made
TXNAMOUNT String(10)Order value of the transaction in INR
REFID String(50)Unique reference ID for refund transaction which is generated by merchant and sent in the request
STATUS String(20)This contains the status of refunds. It has following values: TXN_SUCCESS, TXN_FAILURE & PENDING
RESPCODE String(10)Codes refer to a particular reason of refund failure. These are detailed in the list provided below
RESPMSG String(500)Description message attached with each respcode. These are detailed in the list provided below
TXNDATE DateTimeDate of payment transaction in the format "yyyy-MM-dd HH:mm:ss.S"
Format - “2015-11-02 11:40:46.0”
CARD_ISSUER String(20)Name of issuing bank of the payment instrument used by customer. By paymodes, the details are provided below
Credit, debit cards, UPI - Name of the issuing bank. Example in case customer uses SBI's credit card, the value will be "SBI"
NB - empty string
Paytm Wallet - empty string
PAYMENTMODE String(15)The payment mode used by customer for transaction
Credit card – CC
Debit card - DC
Net banking - NB
UPI - UPI
Paytm wallet – PPI
REFUNDDATE DateTimeDate and timeof REFUND in the format "yyyy-MM-dd HH:mm:ss.S"
EX- “2015-11- 02 11:40:46.0”
REFUNDID String(64)This is a unique Paytm refund ID that is issued by Paytm for each refund request
BANKTXNID String(100)The transaction ID sent by the bank In case of Paytm proprietary instruments too, there is unique reference number generated by Paytm's system. In case the transaction does not reach the bank, this will be NULL or empty string. Primary reason for this is user dropping out of the payment flow before the transaction reaches to bank to servers
TOTALREFUNDAMT String(10)Total cummulative refund amount against this transaction. For example for a transaction with order value as INR 100, there has been two refunds of INR 20 & INR 30 historically, then TOTALREFUNDAMT will be INR 50

Refund Response Codes, Messages and Status

PARAMETERDESCRIPTIONSTATUS
10Refund successfulTXN_SUCCESS
328Currency not sameTXN_FAILURE
501System errorTXN_FAILURE
600Invalid refund requestTXN_FAILURE
601Refund request was raised for this transaction. But it is pending state.PENDING
606Checksum generated by Paytm payment gateway does not match checksum expected by bankTXN_FAILURE
607Order not exist for current requestTXN_FAILURE
609Refund initiated for a rejected transactionTXN_FAILURE
612This is a valid authorized transactionTXN_FAILURE
617Refund already raisedTXN_FAILURE
619Invalid refund amountTXN_FAILURE
620Refund failedTXN_FAILURE
622No_token-transcation_limitedTXN_FAILURE
640Order is frozenTXN_FAILURE
700Invalid consult requestTXN_FAILURE
701Refund already raised with same refidTXN_FAILURE
702Not allowed to reprocess refund requestTXN_FAILURE
703Refund is already success or in pending state. Please check status query for final resultTXN_FAILURE
704Balance not enoughTXN_FAILURE
Request CodeResponse JSON
curl -X 
POST https://securegw-stage.paytm.in/refund/process -H
'content-type: application/json' -d 
'JsonData={"MID":"rxazcv89315285244163",
"ORDERID":"order1",
"TXNTYPE":"REFUND",
"REFUNDAMOUNT":"100.12",
"TXNID":"20180613111212800110168032128074895",
"REFID":"reforder1","CHECKSUM":"4xWjvYndYjRGwwFlzx7QvfeZhkOX3MN7o1pHvoGIjroKaaok/isIQWmo2aNYAs/vVLZ3t54wCVZ3+SKtiw17BHhtze8wfHDOIVwEp7bOf5g="}'