Create Dispute

A disputed transaction refers one where a customer questions the validity of a transaction initiated through his/her registered transacting account.

Customers may report a disputed transaction for various reasons, as mentioned below:

  • Unauthorized transactions

  • Excessive charges

  • Failure by the merchant to deliver goods/products

  • Defective goods/products

  • Dissatisfaction with the product(s) or service(s) received

  • Billing errors

POST https://stgsecctrl.tutelar.io/api/v1/dispute/create

Transaction status is success

 {
   "success": true,
   "code": 201,
   "message": "Dispute raised successfully",
   "data": {
       "disputeId": "dispute_Dffgonjc"
   }
}

Transaction status is Failed

{
    "success": true,
    "code": 201,
    "message": "Your transaction failed, Dispute closed",
    "data": {
        "disputeId": "dispute_uFtNF21b"
    }
}

Transaction status is Refund

 {
    "success": true,
    "code": 201,
    "message": "Your dispute has been closed due to a refunded transaction",
    "data": {
        "disputeId": "dispute_gWMecHCd"
    }
}

Post Parameters,

Post parameters description is given below :

Post Parameter
Type
Is Mandatory
Description

transactionDetails

Object

Yes

Transaction details provide the entire details of the particular transaction such as transaction ID, transaction date and time, mode of transaction etc. Which is useful in the means of reviewing the raised dispute. transactionDetails has fields [id, customerName, customerEmail, customerMobile ( Type as String)], amount data type is Number, transactionDate data type is DateTime.

merchantDetails

Object

Yes

In merchant details, details of the merchant will be shown such as merchant name, merchant ID , merchant business name . Used in order to verify the transaction done. merchantDetails has fields [id, name, businessName, chargebackEmail, mobile( Type as String)].

disputeAmount

Number

Yes

Dispute amount is also known as the challenged amount by the customer in order of the billing or the financial transaction done to the respected merchant.

disputeAmountTdrDetails

Object

No

The TDR type, amount , amount type is using To calculate the TDR amount from dispute Amount. disputeAmountTdrDetails has fields [ type, amountType ( Type as String )].amount data type is Number.

disputeAmountTaxDetails

Object

No

The TAX type, amount, amount type is using To calculate the TAX amount from dispute Amount. disputeAmountTaxDetails has fields [ type, amountType ( Type as String )].amount data type is Number.

disputeType

String

Yes

Dispute type is used to identify what kind of dispute is raised by the customer , various types of disputes are as follows fraud , chargeback , BO ,complaint

internalDueDate

Date

Yes

Internal due date refers to the final date that a resolution need to be provided for an dispute

dueDate

Date

No

The date provided by a client to disclose the respective dispute . the due date is applicable only

level

String

Yes

Following the dispute raised in the panel, the client can use the edit option in the action menu to change level. The level is mainly based on the priority of the dispute raised by the acquirer bank.

paymentType

String

Yes

Payment type is used to mention the payment type the customer is used to pay the required amount , payment type includes credit card , debit card ,POS

acquirerBankCode

String

Yes

The payment receiver bank is also called an acquirer bank . Every individual bank have an individual code referred to as acquirer bank code.

remitterBank

String

No

The customers bank is also known as remitter bank , the card holding of the required bank is known as remitter bank.

reasonCode

String

Yes

Send the reason code based on your transaction type. For instance, if you've made a transaction using a Visa card, send the sample code: 10.1

nodalAccountNo

String

No

The merchants receiving bank is called as nodal account number or the nodal account.

gatewayOrderId

String

Yes

Send your transaction order id.

paymentInstrumentId

String

Yes

The payments instruments such pos and carding machine have an unique ID which is known as payment instrument ID.

comments

String

Yes

Short description based on the dispute will be provided.

Sample POST Parameters

{
   "transactionDetails": {
       "id": "trans_53146",
       "customerName": "xxxx",
       "customerEmail": "xxxx@yyy.com",
       "customerMobile": "xxxxxxxxxx",
       "amount": "1001",
       "transactionDate": "2023-10-11"
   },
   "merchantDetails": {
       "id": "TUT778t78yt",
       "name": "yyyy",
       "businessName": "xxxx",
       "chargebackEmail":"yyyy@zzzz.com",
       "mobile": "xxxxxxxxx"
   },
   "disputeAmount": "100",
   "disputeAmountTdrDetails": {
       "type": "include",
       "amountType": "price",
       "amount": "50"
   },
   "disputeAmountTaxDetails": {
       "type": "exclude",
       "amountType": "percentage",
       "amount": "50"
   },
   "disputeType": "dispute",
   "internalDueDate": "2023-12-31",
   "dueDate" : "2023-12-25", 
   "level": "level_1",
   "paymentType":"cc",
   "acquirerBankCode":  "xxx",
   "remitterBank":"yyyy" ,
   "reasonCode": "109",
   "nodalAccountNo": "0989778",
   "gatewayOrderId": "ORD_90045",
   "paymentInstrumentId": "89 09 78",
   "comments": " your comments "
}

Success Response

 Transaction status is success
 
 {
   "success": true,
   "code": 201,
   "message": "Dispute raised successfully",
   "data": {
       "disputeId": "dispute_Dffgonjc"
   }
}

Transaction status is Failed

{
    "success": true,
    "code": 201,
    "message": "Your transaction failed, Dispute closed",
    "data": {}
 }
 
 Transaction status is Refund
 
 {
    "success": true,
    "code": 201,
    "message": "Your transaction refund successfully, Dispute closed",
    "data": {}
 }

Failure Response

{
   "success": false,
   "code": 300,
   "message": "Please enter your Customer name",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Transaction id is missing",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Dispute details already in submitted",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Invalid Internal Due date",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Dispute amount cannot be higher than transaction amount",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Only allowed A-Za-z0-9 .,'!&@_ in Comments",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Invalid reason code ",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Only allow uppercase for Acquirer bank code",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Please add acquirer bank details",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Please select dispute-tax type",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Invalid data received from dispute-tdr amount type",
   "data": {}
}
{
   "success": false,
   "code": 300,
   "message": "Please Update general configuration",
   "data": {}
}

Response parameter description,

Response Parameter
Type
Description

disputeId

String

A unique ID will be raised for an dispute in order to differentiate it from other disputes

PreviousList APINextUpdate Dispute

Last updated