[POST] customer/v2/dispute

Create a dispute

The V2 Dispute endpoint introduces a new required field disputeAmount with value string. The new endpoint also incorporates automation with the compliance monitoring system so that disputes can be researched, worked, and adjudicated with updates reflected back in Avenu when an adjustment is needed.

Customers can dispute a transaction utilizing the create dispute endpoint. This is used for fraudulent and/or unauthorized charges that may appear on the customer's ledger. Creating a dispute does not guarantee a resolution in the customer's favor. The status will be pending until the dispute case is handled in the compliance monitoring system by administration. As updates to the dispute are made within the compliance monitoring system, real time notifications will be sent via webhook.

Please note: Customers cannot dispute a debit transfer. Only ACH transfers may be disputed. Only one dispute can be created per original transaction. Additionally, a transaction must be in SETTLED state for a dispute to be possible.

deviceIdentity is optional, but it is passed to our vendor for help with compliance case management (refunds, fraud, etc.).

Example [POST] Request

    "transactionID": "",
    "disputeReason": "",
    "disputeAmount": "",
    "disputeType": "",
    "declarationAcknowledged": true,
    "deviceIdentity": {
        "deviceId": "",
        "deviceType": "",
        "deviceName": "",
        "deviceOperatingSystem": "",
        "deviceIPAddress": "",
        "deviceLocation": "",
        "deviceLongitude": "",
        "deviceLatitude": "",
        "deviceUser": "",
        "deviceIMEINumber" : "",
        "deviceTorEnabled" : "",
        "deviceFirstSeen" : "",
        "deviceLastSeen" : ""

Input Parameters

"transactionID"StringYThe transaction ID to dispute.
"disputeReason"StringNThe reason for the dispute (free text).
"disputeAmount"StringYThe amount being disputed, must be less than or equal to the original transaction amount.
"disputeType"StringNThe type of the dispute - See table below
"declarationAcknowledged"BooleanYThis value must always be "true" - otherwise, return Error Code 1001.
"deviceId"StringNThe user's unique device identifier.
"deviceType"StringNThe type of the user's device
"deviceName"StringNThe name given to the user's device.
"deviceOperatingSystem"StringNThe OS of the user's device.
"deviceIPAddress"StringNCurrent IP Address for the device.
"deviceLocation"StringNCurrent location for the device.
"deviceLongitude"StringNDevice's location longitude.
"deviceLatitude"StringNDevice's location latitude.
"deviceUser"StringNThe name of the user of the device.
"deviceIMEINumber"StringNMobile device unique equipment identifier.
"deviceTorEnabled"BooleanNDevice is/is not using Tor browser.
"deviceFirstSeen"String; ISO 8601 yyyy-mm-ddNDate/Time the device was first used to access Avenu.
"deviceLastSeen"String; ISO 8601 yyyy-mm-ddNDate/Time the device was last used to access Avenu.

Dispute Type ENUM

ENUM ValueDescription
UNAUTHORIZEDUnauthorized Transaction
INCORRECT_AMOUNTIncorrect amount sent to or from customer's account
TRANSACTION_OMITTEDTransaction omitted from statement
BOOKKEEPING_ERRORBookkeeping error relating to a transaction
INCORRECT_AMOUNT_AT_ATMReceipt of incorrect amount of money at an ATM
TRANSACTION_NOT_DEFINEDTransaction not properly identified
CLARIFICATION_REQUESTCustomer clarification request

Example Response

     "disputeID": "",
     "dateCreated": "",  
     "status": ""

Response Elements

disputeIDUnique ID to track this dispute case
dateCreatedDispute created date/time
statusDispute status

Error Codes

1001"Missing required field"This error will be returned when a required field is not sent.
1002"Error - Invalid data structure"This error will be returned when invalid data structures are sent.
1003"Error - Invalid data"This error will be returned when invalid data is sent.
1010"Error - Transaction Not Allowed"This error will be returned when the transaction is not permitted.
AE7000"Call Issuer"This error will be returned when a dispute is sent for a DEBIT or DEBIT_FUND transaction type. When a customer needs to dispute a debit card funding transaction, they should reach out to the phone number listed on their card in order to dispute the transaction.
AE3000"Missing required fields"The request body does not have one or more required fields to execute the call.

Get updates on dispute status via webhook

As updates to the dispute are made within the compliance monitoring system, real time notifications will be sent via webhook. Learn more about dispute status webhook notifications.