File dispute
Files a dispute against a cleared card transaction. Card, cardholder, and currency are derived from the transaction. When requiresCardholderSignature is true, mint a signature form URL with POST /disputes/:id/signature-link. Status changes arrive as CARD_DISPUTE_STATUS_UPDATED.
Authorizations
API key as Bearer token
Headers
API version (YYYY-MM-DD)
2025-02-14 "2025-02-14"
Unique 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).
1 - 255Body
File a dispute against a cleared card transaction.
The card transaction being disputed
Why the cardholder is disputing the transaction
FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT, FRAUD_EMV_LIABILITY_SHIFT_NON_COUNTERFEIT, FRAUD_OTHER_CARD_PRESENT, FRAUD_OTHER_CARD_ABSENT, FRAUD_VISA_MONITORING_PROGRAM, AUTHORIZATION_CARD_RECOVERY_BULLETIN, AUTHORIZATION_DECLINED, AUTHORIZATION_NO_AUTH_LATE_PRESENTMENT, PROCESSING_ERROR_INCORRECT_TRANSACTION_CODE, PROCESSING_ERROR_INCORRECT_CURRENCY, PROCESSING_ERROR_INCORRECT_ACCOUNT_NUMBER, PROCESSING_ERROR_INCORRECT_AMOUNT, PROCESSING_ERROR_DUPLICATE_PROCESSING, PROCESSING_ERROR_INVALID_DATA, CONSUMER_MERCHANDISE_NOT_RECEIVED, CONSUMER_CANCELLED_RECURRING, CONSUMER_NOT_AS_DESCRIBED, CONSUMER_COUNTERFEIT_MERCHANDISE, CONSUMER_MISREPRESENTATION, CONSUMER_CREDIT_NOT_PROCESSED, CONSUMER_CANCELLED_MERCHANDISE, CONSUMER_ORIGINAL_CREDIT_NOT_ACCEPTED, CONSUMER_NON_RECEIPT_CASH_ATM "FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT"
Disputed amount in the transaction billing currency. Defaults to the full cleared amount, and may not exceed it.
100.5
1234.99
Address that receives the dispute outcome. Defaults to the cardholder email on file.
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Response
Card dispute resource
Unique dispute identifier
The card transaction being disputed
Card used for the disputed transaction
Current dispute status
PENDING_SIGNATURE, RECEIVED, REVIEWING, SUBMITTED, WON, LOST, REFUNDED, DECLINED, CANCELED "PENDING_SIGNATURE"
Why the cardholder is disputing the transaction
FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT, FRAUD_EMV_LIABILITY_SHIFT_NON_COUNTERFEIT, FRAUD_OTHER_CARD_PRESENT, FRAUD_OTHER_CARD_ABSENT, FRAUD_VISA_MONITORING_PROGRAM, AUTHORIZATION_CARD_RECOVERY_BULLETIN, AUTHORIZATION_DECLINED, AUTHORIZATION_NO_AUTH_LATE_PRESENTMENT, PROCESSING_ERROR_INCORRECT_TRANSACTION_CODE, PROCESSING_ERROR_INCORRECT_CURRENCY, PROCESSING_ERROR_INCORRECT_ACCOUNT_NUMBER, PROCESSING_ERROR_INCORRECT_AMOUNT, PROCESSING_ERROR_DUPLICATE_PROCESSING, PROCESSING_ERROR_INVALID_DATA, CONSUMER_MERCHANDISE_NOT_RECEIVED, CONSUMER_CANCELLED_RECURRING, CONSUMER_NOT_AS_DESCRIBED, CONSUMER_COUNTERFEIT_MERCHANDISE, CONSUMER_MISREPRESENTATION, CONSUMER_CREDIT_NOT_PROCESSED, CONSUMER_CANCELLED_MERCHANDISE, CONSUMER_ORIGINAL_CREDIT_NOT_ACCEPTED, CONSUMER_NON_RECEIPT_CASH_ATM "FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT"
The grouping the reason belongs to
FRAUD, AUTHORIZATION, PROCESSING_ERROR, CONSUMER "FRAUD"
Whether the cardholder must sign a form before the case can progress
The amount under dispute, which may be less than the transaction total
Cardholder identity on the case
When the dispute reached a final status, or null while open
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ISO 8601 timestamp of creation
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$ISO 8601 timestamp of last update
^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$