Disputes
File dispute
https://api.firstleeward.com/v0/disputesFiles a dispute against a cleared card transaction. Card, cardholder, and currency are derived from the transaction. Status changes arrive as CARD_DISPUTE_STATUS_UPDATED.
Authorizations
Authorizationstring · headerrequiredAPI key as Bearer token, e.g. Bearer YOUR_API_KEY
Headers
Leeward-Versionenum<string>requiredAPI version (YYYY-MM-DD). Available option: 2026-09-18
Idempotency-KeystringrequiredUnique key for safely retrying this request. Up to 255 characters; we recommend a UUIDv4. The first request executes and its response is cached; subsequent requests with the same key replay the cached response (24h retention).
Body
application/json
transactionIdstring<uuid>requiredThe card transaction being disputed
reasonstringrequiredWhy the cardholder is disputing the transaction
FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEITFRAUD_EMV_LIABILITY_SHIFT_NON_COUNTERFEITFRAUD_OTHER_CARD_PRESENTFRAUD_OTHER_CARD_ABSENTFRAUD_VISA_MONITORING_PROGRAMAUTHORIZATION_CARD_RECOVERY_BULLETINAUTHORIZATION_DECLINEDAUTHORIZATION_NO_AUTH_LATE_PRESENTMENTPROCESSING_ERROR_INCORRECT_TRANSACTION_CODEPROCESSING_ERROR_INCORRECT_CURRENCYPROCESSING_ERROR_INCORRECT_ACCOUNT_NUMBERPROCESSING_ERROR_INCORRECT_AMOUNTPROCESSING_ERROR_DUPLICATE_PROCESSINGPROCESSING_ERROR_INVALID_DATACONSUMER_MERCHANDISE_NOT_RECEIVEDCONSUMER_CANCELLED_RECURRINGCONSUMER_NOT_AS_DESCRIBEDCONSUMER_COUNTERFEIT_MERCHANDISECONSUMER_MISREPRESENTATIONCONSUMER_CREDIT_NOT_PROCESSEDCONSUMER_CANCELLED_MERCHANDISECONSUMER_ORIGINAL_CREDIT_NOT_ACCEPTEDCONSUMER_NON_RECEIPT_CASH_ATMamountnumberCardholder amount under dispute in the billing currency, including FX and ATM fees. Defaults to the full cleared cardholder amount, and may not exceed it.
contactEmailstring<email>Address that receives the dispute outcome. Defaults to the cardholder email on file.
Response
200Card dispute resource
idstring<uuid>requiredUnique dispute identifier
transactionIdstring<uuid>requiredThe card transaction being disputed
cardIdstring<uuid>requiredCard used for the disputed transaction
statusstringrequiredCurrent dispute status
RECEIVEDREVIEWINGSUBMITTEDWONLOSTREFUNDEDDECLINEDCANCELEDreasonstringrequiredWhy the cardholder is disputing the transaction
FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEITFRAUD_EMV_LIABILITY_SHIFT_NON_COUNTERFEITFRAUD_OTHER_CARD_PRESENTFRAUD_OTHER_CARD_ABSENTFRAUD_VISA_MONITORING_PROGRAMAUTHORIZATION_CARD_RECOVERY_BULLETINAUTHORIZATION_DECLINEDAUTHORIZATION_NO_AUTH_LATE_PRESENTMENTPROCESSING_ERROR_INCORRECT_TRANSACTION_CODEPROCESSING_ERROR_INCORRECT_CURRENCYPROCESSING_ERROR_INCORRECT_ACCOUNT_NUMBERPROCESSING_ERROR_INCORRECT_AMOUNTPROCESSING_ERROR_DUPLICATE_PROCESSINGPROCESSING_ERROR_INVALID_DATACONSUMER_MERCHANDISE_NOT_RECEIVEDCONSUMER_CANCELLED_RECURRINGCONSUMER_NOT_AS_DESCRIBEDCONSUMER_COUNTERFEIT_MERCHANDISECONSUMER_MISREPRESENTATIONCONSUMER_CREDIT_NOT_PROCESSEDCONSUMER_CANCELLED_MERCHANDISECONSUMER_ORIGINAL_CREDIT_NOT_ACCEPTEDCONSUMER_NON_RECEIPT_CASH_ATMcategorystringrequiredThe grouping the reason belongs to
FRAUDAUTHORIZATIONPROCESSING_ERRORCONSUMERamountobjectrequiredThe cardholder amount under dispute, including FX and ATM fees. May be less than the transaction total.
Show child attributes
valuenumberrequiredDisputed amount
currencystringrequiredCurrency of the disputed amount
refundedAmountobject | nullrequiredAmount credited to the cardholder when the dispute reaches REFUNDED. Includes the network refund plus a prorated FX markup and ATM variable fee. Does not include the per-withdrawal ATM fixed fee, which stays charged. Null until REFUNDED. May be less than the disputed amount. The same credit is recorded as a DISPUTE_REFUND event on the disputed card transaction and delivered in CARD_TRANSACTION_UPDATED; apply balance changes from that event, not from this field.
Show child attributes
valuenumberrequiredAmount credited to the cardholder
currencystringrequiredCurrency of the refunded amount
cardholderobjectrequiredCardholder identity on the case
Show child attributes
namestringrequiredCardholder name on the case
emailstring<email>requiredCardholder email on the case
contactEmailstring<email>requiredAddress that receives the dispute outcome
resolvedAtstring<date-time> | nullrequiredWhen the dispute reached a final status, or null while open
createdAtstring<date-time>requiredISO 8601 timestamp of creation
updatedAtstring<date-time>requiredISO 8601 timestamp of last update
400Dispute filing is not available for this transaction. It was created by an older sandbox simulation; please try again with a new transaction
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired404Card transaction not found
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired409An active card dispute already exists for this transaction
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired422Response for status 422
Option 1 · CardDisputeTransactionNotClearedError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 2 · CardDisputeFilingWindowExpiredError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequiredOption 3 · CardDisputeAmountInvalidError
errorobjectrequiredShow child attributes
codestringrequiredmessagestringrequireddetailobject | nullrequired