search

POSTRefund API

Use Case

This API is used to trigger refunds for any of the orders which are to be refunded to the customer.

Request Attributes

Content Type : JSON

Head

AttributeDescription
clientId
string
optional

AI router uses the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

requestTimeStamp
string
optional

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

Example: 1588402269

signature
string
mandatory

AI router 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.

version
string
optional

Version of the API.

Body

AttributeDescription
mid
string
mandatory

This is a unique identifier provided to every merchant by AI router.
 

Example: 216820000002516036253

orderId
string
mandatory

It is a 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
mandatory

Unique Reference Id for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the AI router gateway.
 

Example: REFID_98765

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

txnId
string
mandatory

txnID is AI router payment Transaction Id against which the refund transaction is being placed.
TXNID is provided in response payload for every payment transaction.
 

Example: 202005081112128XXXXXX68470101509706

refundSource
string
optional

Source passed at the time of initiating the refund

refundReason
string
optional

Reason passed at the time of initiating the refund

refundDestination
string
optional

Type of refund. TO_SOURCE: Refund is being credited to the same destination through which the payment took place 

refundType
string
optional

Type of refund. TO_SOURCE: Refund is being credited to the same destination through which the payment took place

payoutAccountNo
string
optional

Account number to which the refund should be transferred to

ifscCode
string
optional

IFSC code of the beneficiary account holding bank branch.

payoutVpa
string
optional

VPA of the beneficiary to which the disbursal should be made

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

comments
string
optional

Any additional comments

Response Attributes

Content Type : JSON

Head

AttributeDescription
cliendId
string

AI router use the merchant key on the basis of clientId parameter value. It requires only if the merchant has more than one key.

responseTimeStamps
string

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

version
string

Version of the API.
 

Example: v1

signature
string

AI router validates the request and ensures that parameters are not tempered by verifying the signature in the request.

Body

AttributeDescription
resultInfo
string

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

resultInfo
+
AttributeDescription
resultStatus
string

This parameter is the result specific to the phase of the transaction mentioned in the txnType field

resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64.

resultMsg
string

This parameter is the result message which contains information about the result.

mid
string

This is a unique identifier provided to every merchant by AI router.

orderId
string

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

Example: OREDRID_98765

txnId
string

transID is AI router payment Transaction Id against which the refund transaction is being placed.
transID is provided in response payload for every payment transaction.
 

Example: 202005081112128XXXXXX68470101509706

txnPaidTime
string

Timestamp of customer to merchant payment transaction.
 

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

txnAmount
string

Order value of the transaction in INR.
 

Example: 100.00

totalrefundAmount
string

Amount for which refund was initiated by the merchant. It can be equal to or less than the transaction amount.
 

Example: 3.00

payMethod
string

Payment method used for the transaction

maskedVpa
string

VPA of the customer in masked format

userMobile
string

User's masked mobile number

issuingBankName
string

Name of issuing bank where refund is being credited

cardScheme
string

For credit/debit card refunds, this contains the card scheme where refund is being credited to
 

maskedCardNumber
string

For credit/debit card refunds, this contains the masked number of the card where the refund is being credited to.

refundInfos
Object

Details of refund like masked refund destination, refund amount allocation, RRN Number etc

refundInfos
+
AttributeDescription
refundAmount
string

Amount for which refund was initiated by the merchant. It can be equal to or less than the transaction amount.

refId
string

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

refundId
string

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

refundRaisedStatus
Enum

Contains status if refund was raised successfully or not

refundRaisedTime
string

Timestamp when refund was raised

refundAcceptStatus
string

Status of Paytm accepting the refund

refundAcceptTime
string

Status of Paytm accepting the refund

rrn
string

Reference number with which customers can inquire status with their respective issuing bank. This is generated by acquiring and passed to the issuing bank. This is not available for all the paymodes.

refundType
Enum

Type of refund. TO_SOURCE: Refund is being credited to the same destination through which the payment took place.

userCreditExpectedDate
string

Latest timestamp for customers to realize the refund

refundStatus
Enum

Contains status of refund 
 

Example: SUCCESS

refundCode
string

This is the refundCode corresponding to a particular message and is returned to the merchant. Its maximum length is 64. (Not being used for now)

refundMsg
string

Source of raising the refund

refundSource
string

Source of raising the refund

gatewayResponse
string

Response provided by the gateway during payment or transaction. This is available for Super Router product only.

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_FAILURECurrency not same.
701TXN_FAILURERefund Already Raised with Same REFID.
602TXN_FAILUREBank has declined refund request.
227TXN_FAILUREInvalid refund request or restricted by bank.
400PENDINGRefund request was raised for this transaction. But it is pending state.
247TXN_FAILUREYour refund cannot be completed. Transaction record not found at bank's end.
698TXN_FAILUREPlease retry the refund.
624TXN_FAILUREParameter illegal
625TXN_FAILUREParam missing
⇾
Staging
Production
https://stage-router.paytm.in/aoa-refund-service/refund/applycopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET
curl --location -g 'https://stage-router.paytm.in/aoa-refund-service/refund/apply' \
--header 'Content-Type: application/json' \
--data '{"head": {"clientId": "12345","requestTimeStamp": "2022123456","version": "1.0","signature": "SIGNATURE"},"body": {"mid": "YOUR_MID_HERE","orderId": "QA11_217519","refId": "112","refundAmount": "1","txnId": "2023051101002XXXX863378207239249921","refundSource": "REFUND_SOURCE","refundReason": "REFUND_REASON","refundDestination": "TO_SOURCE","refundType": "REFUND_TYPE","payoutAccountNo": "PAYOUT_ACCOUNT_NUMBER","ifscCode": "IFSC_CODE","payoutVpa": "PAYOUT_VPA","agentInfo": {"employeeId": "EMPLOYEE_ID","name": "NAME","phoneNo": "PHONE_NUMBER","email": "EMAIL_ID"},"comments": "COMMENTS"}}'

 

copy icon