paytm developer docs logoDeveloperDocumentation
search

POSTDispute Action API

Use Case

This API allows the merchant to take appropriate action on a Dispute raised against them.

 

Merchant can either accept the dispute or defend it by uploading proofs using the S2S API call. Since this API allows files upload so it will consume multipart/form-data for request and will produce application/json for a response.

Request Attributes

API Content Type: JSON

ATTRIBUTE DESCRIPTION

mid

string(32)
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

.

clientId

string(32)
optional

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

Example: C11

requestTimestamp

string(16)
mandatory

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

files

object
conditional

Proof of document. This should be file content uploading/streaming in a request.

Note: If merchant action is to DEFEND the dispute then either files or filesPath are required, if both are sent then only files will be considered in a request.

filesPath

string
conditional

Proof of document. This should be a file path relative. This path must exist on SFTP Credentials provided by the merchant.

Note: If merchant action is to DEFEND the dispute then either files or filesPath are required, if both are sent then only files will be considered in a request. 

disputeId

string(64)
mandatory

Dispute Id for which merchant is uploading proofs/documents

Example: 20191218111221000100168001200816663

action

string(32)
mandatory

This field is used to perform an action on the dispute

Possible Values: ACCEPT, DEFEND

comments

string
optional

Comment/Remark in case of POD Rejected

Note: This field is used only if merchant action is DEFEND

orderStatus

string
conditional

If a merchant is defending the dispute then he can provide his order status using this field.

Note: This field is Mandatory if merchant action is DEFEND

Possible Values: ORDER_DELIVERED, ORDER_IN_TRANSIT

tokenType

Enum
optional

Authorization method for this request.

Possible Values: CHECKSUM

signature

string(128)
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.

Response Attributes

Content Type : JSON

Head

AttributeDescription
responseTimestamp
string(16)

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

version
string(2)

Version of the API passed in the request.
Example: v1

clientId
string(32)

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

signature
string(128)

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.

Example: TXBw50YPUKIgJd8gR8RpZuOMZ+csvCT7i0/YXmG//J8+BpFdY5goPBiLAkCzKlCkOvAQip/Op5aD6Vs+cNUTjFmC55JBxvp7WunZ45Ke2q0=

Body

AttributeDescription
resultInfo
string

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

ResultInfo
+
AttributeDescription
resultStatus
string(1)

This parameter indicates the status of API call.

Possible Values: S,F,U,A

resultCodeId
string(4)

This is the resultCode corresponding to a particular message and is returned to the merchant. 

Example: 1003

resultMsg
string(256)

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

Example: AUDIT_SUCCESS

resultCode
string(64)

Result Code of the response

Example: AUDIT_SUCCESS

mid
string(32)

Merchant Id

Example: ethics90962220263187

disputeId
string(64)

Dispute Id for which merchant has uploaded the proofs/documents

Example: 20201118111221000100168000300212600

Following response is expected when files are sent in the API request:

{
    "head": {
        "requestTimestamp": "1526969112101",
        "version": "v1",
        "clientId": "C11",
        "signature": "TXBw50YPUKIgJd8gR8RpZuOMZ+csvCT7i0/YXmG//J8+BpFdY5goPBiLAkCzKlCkOvAQip/Op5aD6Vs+cNUTjFmC55JBxvp7WunZ45Ke2q0="
    },
    "body": {
        "resultInfo": {
            "resultStatus": "A",
            "resultCodeId": "1001",
            "resultCode": "UPLOADED_SUCCESS",
            "resultMsg": "Document has been uploaded successfully."
        },
        "mid": "ethics90962220263187",
        "disputeId": "20201118111221000100168000300212600"
    }
}

Following response is expected when filesPath are sent in the API request:

{
    "head": {
        "requestTimestamp": "1606234630696",
        "version": "v1",
        "clientId": "C11",
        "signature": "TXBw50YPUKIgJd8gR8RpZuOMZ+csvCT7i0/YXmG//J8+BpFdY5goPBiLAkCzKlCkOvAQip/Op5aD6Vs+cNUTjFmC55JBxvp7WunZ45Ke2q0="
    },
    "body": {
        "resultInfo": {
            "resultStatus": "A",
            "resultCodeId": "1002",
            "resultCode": "ACCEPTED_SUCCESS",
            "resultMsg": "Document upload request has been accepted."
        },
        "mid": "ethics90962220263187",
        "disputeId": "20201118111221000100168000300212600"
    }
}

Response Codes & Messages

resultCodeId resultStatus resultCode resultMsg
1001 S UPLOADED_SUCCESS Document has been uploaded successfully.
1002 A ACCEPTED_SUCCESS Document upload request has been accepted.
1003 S DISPUTE_ACCEPTED Dispute Accepted Successfully
4001 F INVALID_SIGNATURE Provided signature is invalid
4002 F MANDATORY_PARAM_MISSING Dispute Id is required
4003 F REQUEST_PARAMS_INVALID Invalid filesPath
4004 F DISPUTE_ID_NOT_FOUND Dispute id not found
4005 F POD_UPLOAD_NOT_ALLOWED Document upload due date has expired
4006 F POD_ALREADY_UPLOADED Document already uploaded for this dispute
4007 F MAX_FILES_EXCEEDED Maximum 5 files are allowed to upload
4008 F MAX_SIZE_EXCEEDED Maximum 5MB of each file is allowed
4009 F FILE_NOT_SUPPORTED Provided file type is not supported
4010 F POD_UPLOAD_FAILED Failed to upload document
4011 F DISPUTE_ACCEPTANCE_NOT_ALLOWED Due date to accept dispute has expired
5001 U SYSTEM_ERROR System Error
⇾
Staging
Production
https://securestage.paytmpayments.com/v1/dispute/actioncopy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
curl --location --request POST 'https://secure.paytmpayments.com/v1/dispute/action' \
    {
      'mid=ethics90962220263187',
      'disputeId=20201118111221000100168000300212600',
      'requestTimestamp=1588402269',
      'signature=bNY0+Sr9u1ioNhSPnpXVnCHWt4YeSJKIOkW2O/vE4bXwlqIaX9AL1N0xUQ5uLHuqmzOMXgA0spdr/SkDdrN97tVbnC+kKdnn7aOGsfzl2I8=',
      'orderStatus=ORDER_IN_TRANSIT',
      'action=DEFEND',
      'files=@/path/to/file1',
      'files=@/path/to/file2'
    }
copy icon