POSTRefund API (Sync)
Use Case
- To initiate partial or complete refund of transaction
- This is a sync API. In the sync response we provide the final status of the refund. This is achieved after raising the refund to the acquiring bank
- Suggested to use the new Refund API as all the new features are built on this
Request Attributes
Head
Attribute | Description |
---|---|
version string(4) optional | Version of the API. Example: v1 |
channelId string(15) 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. |
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. |
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 pass 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. | ||||||||||
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 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 (".") | ||||||||||
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- false | ||||||||||
agentInfo object optional | Refund initiator details. These will be available in refund success response and refund report generated from merchant panel | ||||||||||
AgentInfo +
|
Response Attributes
Head
Attribute | Description |
---|---|
version string(2) | Version of the API passed in the request. |
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. |
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 +
| |||||||||||||||||||||||||||||
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 | The Unique reference ID of the Order. It is alphanumeric and special characters allowed are “@” “-” “_” “.”. | ||||||||||||||||||||||||||||
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. | ||||||||||||||||||||||||||||
txnTimestamp string(20) | Timestamp of customer to merchant payment transaction. Example: 2020-05-02 12:24:25.0 | ||||||||||||||||||||||||||||
source string | Source Example: MERCHANT | ||||||||||||||||||||||||||||
txnAmount string(10) | Order value of the transaction in INR. Example: 1.00 | ||||||||||||||||||||||||||||
refundAmount string | Amount for which refund was initiated by the merchant. It can be equal to or less than the transaction amount. Example: 1.00 | ||||||||||||||||||||||||||||
totalRefundAmount string | Total cumulative refund amount against this transaction. Example: 1.00 | ||||||||||||||||||||||||||||
merchantRefundRequestTimestamp string | EPOCH timestamp of the time at which request is being sent. Example: 2020-05-02 12:24:25.0 | ||||||||||||||||||||||||||||
maxRefundRetryTimeStamp string | Timestamp till which system refund retry would be attempted in case of insufficient MPA. Example: 2020-05-02 12:24:25.0 | ||||||||||||||||||||||||||||
acceptRefundTimestamp string | Timestamp at which Paytm accepted the refund. At the time of acceptance refund amount is deducted from the merchant payable balance Example: 2020-05-02 12:24:25.0 | ||||||||||||||||||||||||||||
acceptRefundStatus string | Status of Paytm accepting the refund | ||||||||||||||||||||||||||||
userCreditInitiateStatus string | Status of Paytm initiating the refund with the acquirer | ||||||||||||||||||||||||||||
userCreditInitiateTimestamp string | Timestamp at which Paytm has initiated the refund with the acquirer. Note that this should not be confused with the time customer realizes the money into his account Example: 2020-05-02 12:24:25.0 | ||||||||||||||||||||||||||||
refundDetailInfoList object | Details of refund like masked refund destination, refund amount allocation, RRN Number etc | ||||||||||||||||||||||||||||
RefundDetailInfoList +
|
Response Codes & Messages
resultCode | resultStatus | resultMsg |
---|---|---|
10 | TXN_SUCCESS | Refund Successfull |
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 | Invalid Merchant Id |
600 | TXN_FAILURE | Invalid refund request or restricted by bank. |
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 |
635 | TXN_FAILURE | Partial Refund under Rupee 1 is not allowed |
328 | TXN_FAILURE | Invalid PaytmId. |
602 | TXN_FAILURE | Refund cannot be processed by the bank |
607 | TXN_FAILURE | Refund can not be initiated for a cancelled transaction. |
612 | TXN_FAILURE | This is a valid authorized transaction, but could not be cancelled due to operational reasons. |
617 | TXN_FAILURE | Refund Already Raised (If merchant repeated their request within the 10 minutes after initiate the first refund request) |
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 |
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 |
663 | TXN_FAILURE | Refund cannot be processed as chargeback received at banks' end |
664 | TXN_FAILURE | Refund cannot be processed by the bank as customer source account is frozen |
665 | TXN_FAILURE | Refund cannot be processed by the bank as customer source account is closed |
666 | TXN_FAILURE | Refund cannot be processed by the bank as customer source account limit breached |
667 | TXN_FAILURE | Refund cannot be processed by the bank as refund window expired |
668 | TXN_FAILURE | Refund cannot be processed by the bank as issuing bank is down or facing issues. |
669 | TXN_FAILURE | Refund rejected by the bank due to risk |
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 |
curl -X POST 'https://securegw-stage.paytm.in/refund/api/v1/refund/apply/sync' \
--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}"}}'