Increase Card Disputes API
If unauthorized activity occurs on a card, you can create a Card Dispute and we'll work with the card networks to return the funds if appropriate.
OpenAPI Specification
openapi: 3.1.0
info:
description: Anything that you can achieve with PDFs, presence, and persistence in a bank branch you can do with our API. We've always wanted a fully programmatic bank so we built one. Our API faithfully exposes the data and capabilities of the Federal Reserve, Visa, The Clearing House, depository networks, and accounting tools. It's lovingly boring and exceptionally powerful. If you have any questions or want to get started, don't hesitate to ping us at sales@increase.com. We can't wait to see what you build!
title: Increase Account Numbers Card Disputes API
version: 0.0.1
servers:
- url: https://api.increase.com
- url: https://sandbox.increase.com
security:
- bearerAuth: []
tags:
- description: If unauthorized activity occurs on a card, you can create a Card Dispute and we'll work with the card networks to return the funds if appropriate.
name: Card Disputes
paths:
/card_disputes:
get:
operationId: list_card_disputes
parameters:
- in: query
name: cursor
required: false
schema:
description: Return the page of entries after this one.
type: string
x-documentation-priority: low
- in: query
name: limit
required: false
schema:
description: Limit the size of the list that is returned. The default (and maximum) is 100 objects.
minimum: 1
type: integer
x-documentation-priority: low
- in: query
name: created_at.after
required: false
schema:
description: Return results after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.before
required: false
schema:
description: Return results before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.on_or_after
required: false
schema:
description: Return results on or after this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: created_at.on_or_before
required: false
schema:
description: Return results on or before this [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) timestamp.
format: date-time
type: string
x-documentation-priority: low
- in: query
name: status.in
required: false
schema:
description: Filter Card Disputes for those with the specified status or statuses. For GET requests, this should be encoded as a comma-delimited string, such as `?in=one,two,three`.
items:
enum:
- user_submission_required
- pending_user_submission_reviewing
- pending_user_submission_submitting
- pending_user_withdrawal_submitting
- pending_response
- lost
- won
type: string
x-enum-descriptions:
- A User Submission is required to continue with the Card Dispute.
- The most recent User Submission is being reviewed.
- The most recent User Submission is being submitted to the network.
- The user's withdrawal of the Card Dispute is being submitted to the network.
- The Card Dispute is pending a response from the network.
- The Card Dispute has been lost and funds previously credited from the acceptance have been debited.
- The Card Dispute has been won and no further action can be taken.
type: array
x-documentation-priority: default
explode: false
- in: query
name: idempotency_key
required: false
schema:
description: Filter records to the one with the specified `idempotency_key` you chose for that object. This value is unique across Increase and is used to ensure that a request is only processed once. Learn more about [idempotency](https://increase.com/documentation/idempotency-keys).
maxLength: 200
minLength: 1
type: string
x-documentation-priority: default
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_dispute_list'
description: Card Dispute List
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: List Card Disputes
x-sandbox-only: false
x-tag: Card Disputes
tags:
- Card Disputes
post:
operationId: create_a_card_dispute
parameters: []
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/create_a_card_dispute_parameters'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_dispute'
description: Card Dispute
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: Create a Card Dispute
x-sandbox-only: false
x-tag: Card Disputes
tags:
- Card Disputes
/card_disputes/{card_dispute_id}:
get:
operationId: retrieve_a_card_dispute
parameters:
- example: card_dispute_h9sc95nbl1cgltpp7men
in: path
name: card_dispute_id
required: true
schema:
description: The identifier of the Card Dispute.
type: string
x-documentation-priority: default
x-id-reference-to: Card Disputes
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_dispute'
description: Card Dispute
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: Retrieve a Card Dispute
x-sandbox-only: false
x-tag: Card Disputes
tags:
- Card Disputes
/card_disputes/{card_dispute_id}/submit_user_submission:
post:
operationId: submit_a_user_submission_for_a_card_dispute
parameters:
- example: card_dispute_h9sc95nbl1cgltpp7men
in: path
name: card_dispute_id
required: true
schema:
description: The identifier of the Card Dispute to submit a user submission for.
type: string
x-documentation-priority: default
x-id-reference-to: Card Disputes
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/submit_a_user_submission_for_a_card_dispute_parameters'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_dispute'
description: Card Dispute
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: Submit a User Submission for a Card Dispute
x-sandbox-only: false
x-tag: Card Disputes
tags:
- Card Disputes
/card_disputes/{card_dispute_id}/withdraw:
post:
operationId: withdraw_a_card_dispute
parameters:
- example: card_dispute_h9sc95nbl1cgltpp7men
in: path
name: card_dispute_id
required: true
schema:
description: The identifier of the Card Dispute to withdraw.
type: string
x-documentation-priority: default
x-id-reference-to: Card Disputes
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/withdraw_a_card_dispute_parameters'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/card_dispute'
description: Card Dispute
4XX:
$ref: '#/components/responses/errorResponse'
5XX:
$ref: '#/components/responses/errorResponse'
summary: Withdraw a Card Dispute
x-sandbox-only: false
x-tag: Card Disputes
tags:
- Card Disputes
components:
schemas:
card_dispute_visa_user_submission:
additionalProperties: false
properties:
accepted_at:
anyOf:
- description: The date and time at which the Visa Card Dispute User Submission was reviewed and accepted.
format: date-time
type: string
x-documentation-priority: default
- type: 'null'
amount:
anyOf:
- description: The amount of the dispute if it is different from the amount of a prior user submission or the disputed transaction.
type: integer
x-documentation-priority: default
- type: 'null'
attachment_files:
description: The files attached to the Visa Card Dispute User Submission.
items:
$ref: '#/components/schemas/card_dispute_file_attachment'
type: array
x-documentation-priority: default
category:
description: The category of the user submission. We may add additional possible values for this enum over time; your application should be able to handle such additions gracefully.
enum:
- chargeback
- merchant_prearbitration_decline
- user_prearbitration
type: string
x-documentation-priority: default
x-enum-descriptions:
- 'Visa Card Dispute Chargeback User Submission Chargeback Details: details will be under the `chargeback` object.'
- 'Visa Card Dispute Merchant Pre-Arbitration Decline User Submission: details will be under the `merchant_prearbitration_decline` object.'
- 'Visa Card Dispute User-Initiated Pre-Arbitration User Submission: details will be under the `user_prearbitration` object.'
chargeback:
anyOf:
- additionalProperties: false
description: A Visa Card Dispute Chargeback User Submission Chargeback Details object. This field will be present in the JSON response if and only if `category` is equal to `chargeback`. Contains the details specific to a Visa chargeback User Submission for a Card Dispute.
example:
authorization: null
category: fraud
consumer_canceled_merchandise: null
consumer_canceled_recurring_transaction: null
consumer_canceled_services: null
consumer_counterfeit_merchandise: null
consumer_credit_not_processed: null
consumer_damaged_or_defective_merchandise: null
consumer_merchandise_misrepresentation: null
consumer_merchandise_not_as_described: null
consumer_merchandise_not_received: null
consumer_non_receipt_of_cash: null
consumer_original_credit_transaction_not_accepted: null
consumer_quality_merchandise: null
consumer_quality_services: null
consumer_services_misrepresentation: null
consumer_services_not_as_described: null
consumer_services_not_received: null
fraud:
fraud_type: lost
processing_error: null
properties:
authorization:
anyOf:
- additionalProperties: false
description: Authorization. Present if and only if `category` is `authorization`.
properties:
account_status:
description: Account status.
enum:
- account_closed
- credit_problem
- fraud
type: string
x-documentation-priority: default
x-enum-descriptions:
- Account closed.
- Credit problem.
- Fraud.
required:
- account_status
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Authorization
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Authorizations
- type: 'null'
category:
description: Category.
enum:
- authorization
- consumer_canceled_merchandise
- consumer_canceled_recurring_transaction
- consumer_canceled_services
- consumer_counterfeit_merchandise
- consumer_credit_not_processed
- consumer_damaged_or_defective_merchandise
- consumer_merchandise_misrepresentation
- consumer_merchandise_not_as_described
- consumer_merchandise_not_received
- consumer_non_receipt_of_cash
- consumer_original_credit_transaction_not_accepted
- consumer_quality_merchandise
- consumer_quality_services
- consumer_services_misrepresentation
- consumer_services_not_as_described
- consumer_services_not_received
- fraud
- processing_error
type: string
x-documentation-priority: default
x-enum-descriptions:
- Authorization.
- 'Consumer: canceled merchandise.'
- 'Consumer: canceled recurring transaction.'
- 'Consumer: canceled services.'
- 'Consumer: counterfeit merchandise.'
- 'Consumer: credit not processed.'
- 'Consumer: damaged or defective merchandise.'
- 'Consumer: merchandise misrepresentation.'
- 'Consumer: merchandise not as described.'
- 'Consumer: merchandise not received.'
- 'Consumer: non-receipt of cash.'
- 'Consumer: Original Credit Transaction (OCT) not accepted.'
- 'Consumer: merchandise quality issue.'
- 'Consumer: services quality issue.'
- 'Consumer: services misrepresentation.'
- 'Consumer: services not as described.'
- 'Consumer: services not received.'
- Fraud.
- Processing error.
consumer_canceled_merchandise:
anyOf:
- additionalProperties: false
description: Canceled merchandise. Present if and only if `category` is `consumer_canceled_merchandise`.
properties:
cardholder_cancellation:
anyOf:
- additionalProperties: false
description: Cardholder cancellation.
properties:
canceled_at:
description: Canceled at.
format: date
type: string
x-documentation-priority: default
canceled_prior_to_ship_date:
description: Canceled prior to ship date.
enum:
- canceled_prior_to_ship_date
- not_canceled_prior_to_ship_date
type: string
x-documentation-priority: default
x-enum-descriptions:
- Canceled prior to ship date.
- Not canceled prior to ship date.
cancellation_policy_provided:
description: Cancellation policy provided.
enum:
- not_provided
- provided
type: string
x-documentation-priority: default
x-enum-descriptions:
- Not provided.
- Provided.
reason:
description: Reason.
type: string
x-documentation-priority: default
required:
- canceled_at
- canceled_prior_to_ship_date
- cancellation_policy_provided
- reason
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Merchandise Cardholder Cancellation
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Cardholder Cancellations
- type: 'null'
merchant_resolution_attempted:
description: Merchant resolution attempted.
enum:
- attempted
- prohibited_by_local_law
type: string
x-documentation-priority: default
x-enum-descriptions:
- Attempted.
- Prohibited by local law.
not_returned:
anyOf:
- additionalProperties: false
description: Not returned. Present if and only if `return_outcome` is `not_returned`.
properties: {}
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Merchandise Not Returned
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: true
x-title-plural: Not Returneds
- type: 'null'
purchase_explanation:
description: Purchase explanation.
type: string
x-documentation-priority: default
received_or_expected_at:
description: Received or expected at.
format: date
type: string
x-documentation-priority: default
return_attempted:
anyOf:
- additionalProperties: false
description: Return attempted. Present if and only if `return_outcome` is `return_attempted`.
properties:
attempt_explanation:
description: Attempt explanation.
type: string
x-documentation-priority: default
attempt_reason:
description: Attempt reason.
enum:
- merchant_not_responding
- no_return_authorization_provided
- no_return_instructions
- requested_not_to_return
- return_not_accepted
type: string
x-documentation-priority: default
x-enum-descriptions:
- Merchant not responding.
- No return authorization provided.
- No return instructions.
- Requested not to return.
- Return not accepted.
attempted_at:
description: Attempted at.
format: date
type: string
x-documentation-priority: default
merchandise_disposition:
description: Merchandise disposition.
type: string
x-documentation-priority: default
required:
- attempt_explanation
- attempt_reason
- attempted_at
- merchandise_disposition
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Merchandise Return Attempted
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Return Attempteds
- type: 'null'
return_outcome:
description: Return outcome.
enum:
- not_returned
- returned
- return_attempted
type: string
x-documentation-priority: default
x-enum-descriptions:
- Not returned.
- Returned.
- Return attempted.
returned:
anyOf:
- additionalProperties: false
description: Returned. Present if and only if `return_outcome` is `returned`.
properties:
merchant_received_return_at:
anyOf:
- description: Merchant received return at.
format: date
type: string
x-documentation-priority: default
- type: 'null'
other_explanation:
anyOf:
- description: Other explanation. Required if and only if the return method is `other`.
type: string
x-documentation-priority: default
- type: 'null'
return_method:
description: Return method.
enum:
- dhl
- face_to_face
- fedex
- other
- postal_service
- ups
type: string
x-documentation-priority: default
x-enum-descriptions:
- DHL.
- Face-to-face.
- FedEx.
- Other.
- Postal service.
- UPS.
returned_at:
description: Returned at.
format: date
type: string
x-documentation-priority: default
tracking_number:
anyOf:
- description: Tracking number.
type: string
x-documentation-priority: default
- type: 'null'
required:
- merchant_received_return_at
- other_explanation
- return_method
- returned_at
- tracking_number
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Merchandise Returned
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Returneds
- type: 'null'
required:
- cardholder_cancellation
- merchant_resolution_attempted
- not_returned
- purchase_explanation
- received_or_expected_at
- return_attempted
- return_outcome
- returned
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Merchandise
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Consumer Canceled Merchandises
- type: 'null'
consumer_canceled_recurring_transaction:
anyOf:
- additionalProperties: false
description: Canceled recurring transaction. Present if and only if `category` is `consumer_canceled_recurring_transaction`.
properties:
cancellation_target:
description: Cancellation target.
enum:
- account
- transaction
type: string
x-documentation-priority: default
x-enum-descriptions:
- Account.
- Transaction.
merchant_contact_methods:
additionalProperties: false
description: Merchant contact methods.
properties:
application_name:
anyOf:
- description: Application name.
type: string
x-documentation-priority: default
- type: 'null'
call_center_phone_number:
anyOf:
- description: Call center phone number.
type: string
x-documentation-priority: default
- type: 'null'
email_address:
anyOf:
- description: Email address.
type: string
x-documentation-priority: default
- type: 'null'
in_person_address:
anyOf:
- description: In person address.
type: string
x-documentation-priority: default
- type: 'null'
mailing_address:
anyOf:
- description: Mailing address.
type: string
x-documentation-priority: default
- type: 'null'
text_phone_number:
anyOf:
- description: Text phone number.
type: string
x-documentation-priority: default
- type: 'null'
required:
- application_name
- call_center_phone_number
- email_address
- in_person_address
- mailing_address
- text_phone_number
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Recurring Transaction Merchant Contact Methods
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Merchant Contact Methods
other_form_of_payment_explanation:
anyOf:
- description: Other form of payment explanation.
type: string
x-documentation-priority: default
- type: 'null'
transaction_or_account_canceled_at:
description: Transaction or account canceled at.
format: date
type: string
x-documentation-priority: default
required:
- cancellation_target
- merchant_contact_methods
- other_form_of_payment_explanation
- transaction_or_account_canceled_at
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Recurring Transaction
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Consumer Canceled Recurring Transactions
- type: 'null'
consumer_canceled_services:
anyOf:
- additionalProperties: false
description: Canceled services. Present if and only if `category` is `consumer_canceled_services`.
properties:
cardholder_cancellation:
additionalProperties: false
description: Cardholder cancellation.
properties:
canceled_at:
description: Canceled at.
format: date
type: string
x-documentation-priority: default
cancellation_policy_provided:
description: Cancellation policy provided.
enum:
- not_provided
- provided
type: string
x-documentation-priority: default
x-enum-descriptions:
- Not provided.
- Provided.
reason:
description: Reason.
type: string
x-documentation-priority: default
required:
- canceled_at
- cancellation_policy_provided
- reason
title: Visa Card Dispute User Submission Visa Card Dispute Chargeback User Submission Chargeback Details Consumer Canceled Services Cardholder Cancellation
type: object
x-documentation-priority: default
x-event-categories: []
x-stainless-empty-object: false
x-title-plural: Cardholder Cancellations
contracted_at:
description: Contracted at.
format: date
type: string
x-documentation-priority: default
guaranteed_reservation:
# --- truncated at 32 KB (368 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/increase/refs/heads/main/openapi/increase-card-disputes-api-openapi.yml