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

201: Created 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": {
        "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"
    }
}

422: Unprocessable Entity

401: Unauthorized

404: Request not found

500: Internal Server Error

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": "[email protected]",
       "customerMobile": "xxxxxxxxxx",
       "amount": "1001",
       "transactionDate": "2023-10-11"
   },
   "merchantDetails": {
       "id": "TUT778t78yt",
       "name": "yyyy",
       "businessName": "xxxx",
       "chargebackEmail":"[email protected]",
       "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