> ## Documentation Index > Fetch the complete documentation index at: https://docs.reap.global/llms.txt > Use this file to discover all available pages before exploring further. # 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`. ## OpenAPI ````yaml /api-reference/openapi.json post /disputes/ openapi: 3.1.0 info: title: Reap API version: 1.0.0 description: Reap platform API servers: - url: https://sandbox.api.reap.global description: Sandbox - url: https://prod.api.reap.global description: Production security: - bearerAuth: [] tags: - name: Accounts - name: Activities - name: Card Designs - name: Card Shipments - name: Card Transactions - name: Cards - name: Companies - name: Crypto Deposits - name: Disputes - name: Fiat Deposits - name: Fraud Alerts - name: Policies - name: Simulation - name: Users - name: Virtual Asset Postings - name: Virtual Assets - name: Webhooks paths: /disputes/: post: tags: - Disputes summary: File dispute description: >- 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`. operationId: file_disputes parameters: - name: Reap-Version in: header required: true schema: type: string enum: - '2025-02-14' description: API version (YYYY-MM-DD) example: '2025-02-14' - name: Idempotency-Key in: header required: true schema: type: string minLength: 1 maxLength: 255 description: >- 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). requestBody: description: File a dispute against a cleared card transaction. required: true content: application/json: schema: type: object properties: transactionId: type: string format: uuid description: The card transaction being disputed reason: type: string enum: - 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 description: Why the cardholder is disputing the transaction example: FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT amount: description: >- Disputed amount in the transaction billing currency. Defaults to the full cleared amount, and may not exceed it. type: number exclusiveMinimum: 0 examples: - 100.5 - 1234.99 contactEmail: description: >- Address that receives the dispute outcome. Defaults to the cardholder email on file. type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ required: - transactionId - reason application/x-www-form-urlencoded: schema: type: object properties: transactionId: type: string format: uuid description: The card transaction being disputed reason: type: string enum: - 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 description: Why the cardholder is disputing the transaction example: FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT amount: description: >- Disputed amount in the transaction billing currency. Defaults to the full cleared amount, and may not exceed it. type: number exclusiveMinimum: 0 examples: - 100.5 - 1234.99 contactEmail: description: >- Address that receives the dispute outcome. Defaults to the cardholder email on file. type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ required: - transactionId - reason multipart/form-data: schema: type: object properties: transactionId: type: string format: uuid description: The card transaction being disputed reason: type: string enum: - 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 description: Why the cardholder is disputing the transaction example: FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT amount: description: >- Disputed amount in the transaction billing currency. Defaults to the full cleared amount, and may not exceed it. type: number exclusiveMinimum: 0 examples: - 100.5 - 1234.99 contactEmail: description: >- Address that receives the dispute outcome. Defaults to the cardholder email on file. type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ required: - transactionId - reason responses: '200': description: Card dispute resource content: application/json: schema: $ref: '#/components/schemas/CardDispute' '404': description: Card transaction not found content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: CARD_DISPUTE_TRANSACTION_NOT_FOUND message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardDisputeTransactionNotFoundError '409': description: An active card dispute already exists for this transaction content: application/json: schema: type: object properties: error: type: object properties: code: type: string const: CARD_DISPUTE_ALREADY_EXISTS message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardDisputeAlreadyExistsError '422': description: Response for status 422 content: application/json: schema: anyOf: - type: object properties: error: type: object properties: code: type: string const: CARD_DISPUTE_TRANSACTION_NOT_CLEARED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardDisputeTransactionNotClearedError description: Transaction is not cleared and cannot be disputed - type: object properties: error: type: object properties: code: type: string const: CARD_DISPUTE_FILING_WINDOW_EXPIRED message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardDisputeFilingWindowExpiredError description: Dispute filing window has expired - type: object properties: error: type: object properties: code: type: string const: CARD_DISPUTE_AMOUNT_INVALID message: type: string detail: anyOf: - type: object additionalProperties: {} - type: 'null' required: - code - message - detail required: - error title: CardDisputeAmountInvalidError description: >- Dispute amount must be positive and at most the transaction amount components: schemas: CardDispute: type: object properties: id: type: string format: uuid description: Unique dispute identifier transactionId: type: string format: uuid description: The card transaction being disputed cardId: type: string format: uuid description: Card used for the disputed transaction status: type: string enum: - PENDING_SIGNATURE - RECEIVED - REVIEWING - SUBMITTED - WON - LOST - REFUNDED - DECLINED - CANCELED description: Current dispute status example: PENDING_SIGNATURE reason: type: string enum: - 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 description: Why the cardholder is disputing the transaction example: FRAUD_EMV_LIABILITY_SHIFT_COUNTERFEIT category: type: string enum: - FRAUD - AUTHORIZATION - PROCESSING_ERROR - CONSUMER description: The grouping the reason belongs to example: FRAUD requiresCardholderSignature: type: boolean description: Whether the cardholder must sign a form before the case can progress amount: $ref: '#/components/schemas/CardDisputeAmount' cardholder: $ref: '#/components/schemas/CardDisputeCardholder' resolvedAt: anyOf: - type: string format: date-time pattern: >- ^(?:(?:\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))$ - type: 'null' description: When the dispute reached a final status, or null while open createdAt: type: string format: date-time pattern: >- ^(?:(?:\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))$ description: ISO 8601 timestamp of creation updatedAt: type: string format: date-time pattern: >- ^(?:(?:\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))$ description: ISO 8601 timestamp of last update required: - id - transactionId - cardId - status - reason - category - requiresCardholderSignature - amount - cardholder - resolvedAt - createdAt - updatedAt CardDisputeAmount: type: object properties: value: type: number exclusiveMinimum: 0 examples: - 100.5 - 1234.99 description: Disputed amount currency: description: Currency of the disputed amount type: string pattern: ^[A-Z]{3}$ required: - value - currency description: The amount under dispute, which may be less than the transaction total CardDisputeCardholder: type: object properties: name: type: string description: Cardholder name on the case email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: Cardholder email on the case contactEmail: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: Address that receives the dispute outcome required: - name - email - contactEmail description: Cardholder identity on the case securitySchemes: bearerAuth: type: http scheme: bearer description: API key as Bearer token ````