Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.useaxra.com/llms.txt

Use this file to discover all available pages before exploring further.

A dispute — also called a chargeback — occurs when a cardholder contacts their bank to challenge a charge. The bank initiates a formal dispute process on the cardholder’s behalf, and the outcome determines whether the funds are returned to the customer or kept by you. When a dispute is opened, Axra immediately debits the full charge amount from your merchant account and charges a $5.82 dispute fee. This fee is non-refundable regardless of the outcome — even if you win the dispute.
Disputes can occur weeks or months after the original transaction. Maintain records of customer orders, delivery confirmations, and communications so you can respond with evidence if needed.

​
How disputes affect your account

EventMerchant impact
payment.disputedCharge amount debited + $5.82 dispute fee charged
payment.dispute_wonCharge amount re-credited (dispute fee not refunded)
payment.dispute_lostNo further changes — funds already debited
Axra notifies you of each stage via webhook events. Subscribe to payment.disputed, payment.dispute_won, and payment.dispute_lost to track dispute outcomes in real time.

​
List disputes

Retrieve all disputes for your business account. 
GET /business/disputes
Authentication: Required Query parameters:
ParameterTypeDefaultDescription
statusstringallFilter by outcome: open, won, lost, or all
pagenumber1Page number for pagination
limitnumber20Results per page
Example response: 
{
  "data": [
    {
      "id": "bpay_01H...",
      "amount": 49.99,
      "currency": "USD",
      "status": "DISPUTED",
      "metadata": {
        "disputeId": "dp_1Abc...",
        "disputeReason": "fraudulent",
        "merchantDisputeFee": 5.82
      },
      "business": {
        "id": "biz_01H...",
        "businessName": "Acme Corp"
      },
      "updatedAt": "2026-03-20T16:00:00.000Z"
    }
  ],
  "meta": {
    "total": 3,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  }
}

​
Get dispute statistics

Retrieve an aggregate summary of dispute activity for your account. 
GET /business/disputes/stats
Authentication: Required Response fields:
FieldDescription
openNumber of disputes currently in progress
wonNumber of disputes resolved in your favor
lostNumber of disputes resolved against you
totalTotal disputes across all statuses
winRatePercentage of resolved disputes you won
totalDisputeFeesTotal dispute fees charged to your account

​
Get dispute detail

Retrieve full dispute information for a specific payment. 
GET /business/disputes/:paymentId
Authentication: Required Path parameters:
ParameterDescription
paymentIdThe ID of the payment to look up (e.g., bpay_01H...)
Errors:
StatusMeaning
400The payment exists but has no dispute associated with it
404No payment found with the given ID
The response is the full payment object, with dispute metadata in the metadata field — including disputeId, disputeReason, and merchantDisputeFee.

​
Reducing disputes

The most effective way to manage disputes is to prevent them. Fewer disputes mean lower fees, a healthier account standing, and less time spent on evidence gathering.
1

Enable 3DS authentication

Use 3D Secure authentication on card transactions. When a customer completes 3DS, fraud liability shifts from you to the card issuer — meaning you win most fraud-related disputes automatically.
2

Use clear billing descriptors

Make sure the charge description on your customers’ bank statements clearly identifies your business. An unrecognized charge name is one of the most common reasons customers dispute a transaction.
3

Respond to disputes promptly

Card networks impose strict deadlines — typically 7–21 days — for submitting evidence. Respond as quickly as possible with relevant documentation: order receipts, delivery confirmations, customer communications, and usage logs.
4

Maintain transaction records

Keep records of customer interactions, order details, shipping/delivery confirmations, and any refund requests. These are your primary tools when building a dispute response.
If a customer contacts you directly about an issue before filing a dispute, resolving it promptly (including issuing a refund if warranted) is almost always cheaper than a chargeback. You avoid the dispute fee and protect your dispute rate.