search

POSTRefund API

Use Case

  • To initiate partial or complete refund of transaction
  • This is an async process. In the sync response we only notify registration of refund with PG. This does not mean refund has been accepted by PG or processed to customer’s bank account

Request Attributes

Content Type : JSON

Head

AttributeDescription
version
string(4)
optional

Version of the API.

Example: v1

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"
requestTimestamp
string(15)
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

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

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

AttributeDescription
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

It is unique reference ID for a transaction passed in the transaction request. Order ID should be passed to raise the refund

Example: OREDRID_98765

refId
string(50)
mandatory

Unique Reference Id for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway.
Example: REFUNDID_98765

txnId
string(64)
mandatory

TXNID is Paytm payment Transaction Id against which the refund transaction is being placed.

TXNID is provided in response payload for every payment transaction.

Example: 202005081112128XXXXXX68470101509706

txnType
string
mandatory

Request type

Possible Values: REFUND

refundAmount
string
mandatory

Amount for which the refund is to be made. It can be equal to or less than the transaction amount and should be upto two decimal places. The only special character allowed is (".").

Example: 30.00

preferredDestination
string
optional

Merchant wants to take instant refund solution from Paytm

Possible Values: TO_INSTANT

comments
string(500)
optional

Comments can be given by merchant citing the reason for refund.

disableMerchantDebitRetry
boolean
optional

If its true, we will not retry in case MPA balance is not sufficient then fail the refund

Default Value: false

agentInfo
object
optional

Refund initiator details. These will be available in refund success response and refund report generated from merchant panel 
 

AgentInfo
+
AttributeDescription
employeeId
string
optional

Employee ID of the person who initiated refund

Example: EMP-001

name
string
optional

Name of the person who initiated refund

Example: Test

phoneNo
string
optional

Phone number of the person who initiated refund

Example:  7777777777

email
string
optional

EmailID of the person who initiated refund

Example: customer@example.com

token
string(128)
optional

In case of success, the token is returned, used in Refund API.

refundItems
Object
conditional

The items to be refunded are to be passed. Applicable in case of multi-item transactions where only one or few of the items in the transaction have to be refunded.

refundItems
+
AttributeDescription
itemId
string
mandatory

The identifier for the item sent in the main transaction

productId
string
mandatory

Product Id/model of the item

itemRefundAmount
string
optional

Amount paid for the item in the main transaction

Response Attributes

Content Type : JSON

Head

AttributeDescription
version
string(2)

Version of the API passed in the request.

Example: v1

channelId
string(3)

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"
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

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: TXN_FAILURE, PENDING

resultMsg
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.
 

mid
string(20)

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)

Order ID is merchant’s unique reference ID for a transaction that has sent in request.

Example: OREDRID_98765

refId
string(50)

Merchant's Reference Id unique for every refund transaction. This is REFID for which refund status is being inquired.

 

Example: REFUNDID_98765

refundId
string(64)

This is a unique Paytm Refund Id that is issued by Paytm for each refund request.

Example: 123455081112128XXXXXX68470101509706

txnId
string(64)

TXNID is Paytm payment Transaction Id against which the refund transaction is being placed.

Example: 202005081112128XXXXXX68470101509706

txnTimestamp
string(20)

Timestamp of customer to merchant payment transaction.

Example: 2020-05-02 12:24:25.0

refundAmount
string

Amount for which refund is to be made. It can be equal to or less than the transaction amount and should be upto two decimal places. The only special character allowed is (".").

Example: 30.00

Response Codes & Messages

resultCoderesultStatusresultMsg
501PENDINGSystem Error
601PENDINGRefund request was raised for this transaction. But it is pending state.
330TXN_FAILUREChecksum provided is invalid
335TXN_FAILUREMid is invalid
600TXN_FAILUREInvalid refund request or restricted by bank.
607TXN_FAILURERefund can not be initiated for a cancelled transaction.
617TXN_FAILURERefund Already Raised (If merchant repeated their request within the 10 minutes after initiate the first refund request)
619TXN_FAILUREInvalid refund amount
626TXN_FAILUREAnother Refund on same order is already in Progress, please retry after few minutes
627TXN_FAILUREOrder Details Mismatch
628TXN_FAILURERefund request was raised to respective bank. But it is in pending state from bank side.
629TXN_FAILURERefund is already Successful
635TXN_FAILUREPartial Refund under Rupee 1 is not allowed
328TXN_FAILUREInvalid PaytmId.
612TXN_FAILUREThis is a valid authorized transaction, but could not be cancelled due to operational reasons.
640TXN_FAILUREOrder is closed due to dispute raised against it.
651TXN_FAILUREIncorrect refund request parameters
652TXN_FAILURERefund failed due to system issue. Try again later.
654TXN_FAILURERefund is blocked from merchant dashboard and API. Contact merchant helpdesk.
655TXN_FAILURERefund is not supported on Direct Settlement Merchant
656TXN_FAILURERefund window expired. Refund is not supported by bank.
657TXN_FAILURERefund is not supported by bank
658TXN_FAILUREPartial refund is not supported by bank
659TXN_FAILURERefund amount is greater than the allowed limit on this transaction
660TXN_FAILUREMissing mandatory refund request parameters
661TXN_FAILURERefund is not allowed on Transaction Wise Settlement Merchant
670TXN_FAILURERefund amount is greater than the allowed limit on this transaction. Please note chargeback is also accepted on this transaction.
671TXN_FAILURERefund retry is not supported with same refund id
672TXN_FAILURERefund is blocked as chargeback is in progress
673TXN_FAILUREOriginal transaction not found
674TXN_FAILURERefund amount is invalid or greater than transaction amount
675TXN_FAILUREInvalid refund request. Kindly contact with merchant helpdesk.
676TXN_FAILURERefund window expired on PG
677PENDINGRefund request is pending. Do status query for update.
678TXN_FAILUREMultiple partial refunds are not supported on this transaction.
679TXN_FAILUREInvalid refund request. Kindly retry once original order is successful.
631TXN_FAILURERecord not found
636TXN_FAILURERefund not allowed on orders older than 1 Year.
⇾
Staging
Production
https://securegw-stage.paytm.in/refund/applycopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl -X POST 'https://securegw-stage.paytm.in/refund/apply' \
--header 'Content-Type: application/json' \
--data '{"body":{"mid":"{mid}","txnType":"REFUND","orderId":"ORDERID_98765","txnId":"202005081112128XXXXXX68470101509706","refId":"REFUNDID_98765","refundAmount":"1.00"},"head":{"signature":"{signature}"}}'
copy icon