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

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

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

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

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

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

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

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

resultCode	resultStatus	resultMsg
501	PENDING	System Error
601	PENDING	Refund request was raised for this transaction. But it is pending state.
330	TXN_FAILURE	Checksum provided is invalid
335	TXN_FAILURE	Mid is invalid
600	TXN_FAILURE	Invalid refund request or restricted by bank.
607	TXN_FAILURE	Refund can not be initiated for a cancelled transaction.
617	TXN_FAILURE	Refund Already Raised (If merchant repeated their request within the 10 minutes after initiate the first refund request)
619	TXN_FAILURE	Invalid refund amount
626	TXN_FAILURE	Another Refund on same order is already in Progress, please retry after few minutes
627	TXN_FAILURE	Order Details Mismatch
628	TXN_FAILURE	Refund request was raised to respective bank. But it is in pending state from bank side.
629	TXN_FAILURE	Refund is already Successful
635	TXN_FAILURE	Partial Refund under Rupee 1 is not allowed
328	TXN_FAILURE	Invalid PaytmId.
612	TXN_FAILURE	This is a valid authorized transaction, but could not be cancelled due to operational reasons.
640	TXN_FAILURE	Order is closed due to dispute raised against it.
651	TXN_FAILURE	Incorrect refund request parameters
652	TXN_FAILURE	Refund failed due to system issue. Try again later.
654	TXN_FAILURE	Refund is blocked from merchant dashboard and API. Contact merchant helpdesk.
655	TXN_FAILURE	Refund is not supported on Direct Settlement Merchant
656	TXN_FAILURE	Refund window expired. Refund is not supported by bank.
657	TXN_FAILURE	Refund is not supported by bank
658	TXN_FAILURE	Partial refund is not supported by bank
659	TXN_FAILURE	Refund amount is greater than the allowed limit on this transaction
660	TXN_FAILURE	Missing mandatory refund request parameters
661	TXN_FAILURE	Refund is not allowed on Transaction Wise Settlement Merchant
670	TXN_FAILURE	Refund amount is greater than the allowed limit on this transaction. Please note chargeback is also accepted on this transaction.
671	TXN_FAILURE	Refund retry is not supported with same refund id
672	TXN_FAILURE	Refund is blocked as chargeback is in progress
673	TXN_FAILURE	Original transaction not found
674	TXN_FAILURE	Refund amount is invalid or greater than transaction amount
675	TXN_FAILURE	Invalid refund request. Kindly contact with merchant helpdesk.
676	TXN_FAILURE	Refund window expired on PG
677	PENDING	Refund request is pending. Do status query for update.
678	TXN_FAILURE	Multiple partial refunds are not supported on this transaction.
679	TXN_FAILURE	Invalid refund request. Kindly retry once original order is successful.
631	TXN_FAILURE	Record not found
636	TXN_FAILURE	Refund not allowed on orders older than 1 Year.

⇾

Staging

Production

https://securegw-stage.paytm.in/refund/apply copy 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}"}}'