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

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

Attribute

Description

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

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

comments

string

optional

Any additional comments

Response Attributes

Content Type : JSON

Head

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

Attribute

Description

resultInfo

string

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

resultInfo

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

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

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	Currency not same.
701	TXN_FAILURE	Refund Already Raised with Same REFID.
602	TXN_FAILURE	Bank has declined refund request.
227	TXN_FAILURE	Invalid refund request or restricted by bank.
400	PENDING	Refund request was raised for this transaction. But it is pending state.
247	TXN_FAILURE	Your refund cannot be completed. Transaction record not found at bank's end.
698	TXN_FAILURE	Please retry the refund.
624	TXN_FAILURE	Parameter illegal
625	TXN_FAILURE	Param missing

⇾

Staging

Production

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