Skip to main content

Disputes

A dispute, also known as a chargeback, occurs when a cardholder or bank account owner questions a transaction with their card issuer or bank.

Financial Impact

When dispute funds are withdrawn (see the DISPUTE_FUNDS_WITHDRAWN event), the full amount of the transaction, along with a non-refundable dispute fee, is debited from your balance. If you choose to challenge the dispute by submitting evidence, an additional fee may be applied.

Proactive Refund Protection​

To avoid dispute fees entirely, you must issue a full refund to the customer before they initiate a dispute with their bank or credit card company. Once a dispute is formally initiated, the Dispute Received Fee cannot be avoided or refunded, regardless of the outcome.

Supported Events​

Event TypeDescriptionApplicable payment method types
DISPUTE_INITIATEDEmitted when a dispute is created.CARD, BANK_ACCOUNT
DISPUTE_FUNDS_WITHDRAWNEmitted when funds are withdrawn because of a dispute.CARD, BANK_ACCOUNT
DISPUTE_WONEmitted when a dispute is won and funds are reinstated.CARD, BANK_ACCOUNT
DISPUTE_CLOSEDEmitted when a dispute is closed.CARD, BANK_ACCOUNT

Event Structure​

FieldTypeValid valuesDescription
nameEnumDISPUTE_INITIATED, DISPUTE_FUNDS_WITHDRAWN, DISPUTE_WON, DISPUTE_CLOSEDEvent name
payloadPayloadEvent Payload

Payload Structure​

FieldTypeDescription
iduuidThe unique identifier for the dispute.
merchantTransactionIduuidThe transaction ID provided by the merchant.
paymentIduuidThe unique identifier for the associated payment.
vendorDisputeIdstringThe dispute identifier from the vendor/processor.
amountlongDispute amount in United States Cents.
merchantIduuidThe unique identifier for the merchant.
evidenceEvidenceEvidence submitted for the dispute.
reasonstringThe reason for the dispute.
statusstringThe current status of the dispute.
paymentMethodTypestringThe payment method type, e.g., CARD or BANK_ACCOUNT.
balanceTransactionsarrayA list of balance transactions associated with the dispute.

Evidence Structure​

To increase your chances of winning, provide as much evidence as possible. We have categorized the fields below based on the type of documentation required.

info

The evidence object is typically empty for DISPUTE_INITIATED and DISPUTE_FUNDS_WITHDRAWN events, as evidence is submitted after a dispute is created. For DISPUTE_WON and DISPUTE_CLOSED events, this object will contain the submitted evidence.

Not all fields within the evidence object will be populated in every dispute event. The availability of a field is contingent on the information provided by the payment processor (e.g., Stripe).

FieldDescription
customer_nameFull name of the customer.
customer_email_addressContact email for the customer.
billing_addressThe customer's registered billing address.
customer_purchase_ipThe IP address used at the time of purchase.
customer_signatureThe customer's signature.
access_activity_logA log of the customer's activity.

Balance Transaction Object Structure​

info

The balanceTransactions array's content depends on the event type:

  • DISPUTE_INITIATED: This array is typically empty as the financial adjustment has not yet occurred.
  • DISPUTE_FUNDS_WITHDRAWN: This array contains a transaction object representing the withdrawal of funds from your account.
  • DISPUTE_WON / DISPUTE_CLOSED: This array may contain transaction objects if there was a financial adjustment (for example, returning some or all of the disputed transaction amount to your balance). These adjustments generally apply only to the underlying transaction amount; the non‑refundable Dispute Received Fee is not returned as part of these balance transactions. The array can be empty if no adjustment was needed.

Not all fields will be populated for every balance transaction object within the balanceTransactions array. The availability of each field can vary per object and depends on the information provided by the payment processor (e.g., Stripe).

FieldTypeDescription
amountintegerThe amount of the transaction, in cents.
feeintegerThe fee associated with the transaction, in cents.
fee_detailsarray of Fee DetailA list of fee details associated with the transaction.
idstringThe unique identifier for the balance transaction.
netintegerThe net amount of the transaction, in cents.
typestringThe type of the balance transaction (e.g., adjustment).

Fee Detail Structure​

Each item in the fee_details array is an object with the following fields:

FieldTypeDescription
amountintegerThe amount of the fee, in cents.
descriptionstringA human-readable description of the specific fee.

Payload Structure Samples​

info

The following payload examples are representative and may be subject to change as our API, and that of our partners like Stripe, evolves.

Here are sample payloads for each of the dispute-related events.

{
  "name": "DISPUTE_INITIATED",
  "payload": {
    "id": "2605fad5-db5a-447f-9cb8-9d9fdb3aef97",
    "merchantTransactionId": "9d5e3a78-dcd1-4337-a461-fd9a348a9128",
    "paymentId": "20240786-61cb-49a1-88ad-2678551e9b85",
    "vendorDisputeId": "du_1SxXp2LkuYvMIVR6FzLrA3fU",
    "amount": 500,
    "merchantId": "6089b031-948b-49fd-baf1-ef52fee63920",
    "evidence": {},
    "reason": "FRAUDULENT",
    "status": "NEEDS_RESPONSE",
    "paymentMethodType": "CARD",
    "balanceTransactions": []
  }
}