> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tabby.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Challenge disputes
> Challenge disputes (request Tabby support to take a look at the case). Only 20 disputes can be challenged within a single request. Only disputes with status 'new' might be challenged.
## OpenAPI
````yaml post /api/v1/disputes/challenge
openapi: 3.1.0
info:
title: Tabby API Reference
version: 1.0.0
x-logo:
url: assets/tabby-new.png
altText: tabby Logo
description: |
Tabby Documentation: **[docs.tabby.ai](https://docs.tabby.ai/)**
servers:
- url: https://api.tabby.ai/
description: Production (UAE, Kuwait)
- url: https://api.tabby.sa/
description: Production (KSA)
security: []
tags:
- name: Checkout
description: >-
Checkout is a whole process of customer data collection and payment
authorization.
- name: Payments
description: >-
The core of tabby is a payments flow enabling you to handle payments at
your webstore.
- name: Webhooks
description: Manage webhook endpoints.
- name: Disputes
description: >-
The Disputes API is designed to simplify the process of handling disputes
and help merchants resolve issues with customer orders more efficiently.
Merchants can use this API to retrieve a list of disputes, view details
about a specific dispute, and approve or challenge a bunch of disputes. It
mirrors the functionality available in Tabby Merchant Dashboard and
operates exclusively with live payments using live credentials. A secret
key is required for using the Disputes API.
paths:
/api/v1/disputes/challenge:
post:
tags:
- Disputes
summary: Challenge disputes
description: >-
Challenge disputes (request Tabby support to take a look at the case).
Only 20 disputes can be challenged within a single request. Only
disputes with status 'new' might be challenged.
operationId: postDisputesChallenge
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
dispute_id:
type: string
example: uuid
description: ID of the dispute
description:
type: string
example: Comment for Tabby support
description: Comment for Tabby support.
reason:
type: string
enum:
- merchant_reason_other
- merchant_reason_order_on_its_way
- merchant_reason_order_has_been_already_delivered
- merchant_reason_order_amount_should_be_different
- merchant_reason_problem_with_delivery
example: merchant_reason_other
description: |
Reason for requesting dispute challenge:
- `merchant_reason_other` - there were other problems with the order that required further clarification;
- `merchant_reason_order_on_its_way` - the order has been confirmed and is in the process of being delivered;
- `merchant_reason_order_has_been_already_delivered` - the order has already been delivered and is complete;
- `merchant_reason_order_amount_should_be_different` - there was a problem with the amount of the order and it needed to be changed;
- `merchant_reason_problem_with_delivery` - there was a problem with the order during delivery that needed to be adjusted and resolved.
amount:
type: string
example: '100'
description: >-
If the dispute challenged with reason
`merchant_reason_order_amount_should_be_different` - a new
disputed amount is required.
attachment_ids:
type: array
items:
type: string
format: uuid
example: attachment id, uuid format
description: >-
Attachment ID that will be attached. ID can be received via
`upload attachment` endpoint.
required:
- dispute_id
- description
- reason
responses:
'200':
$ref: '#/components/responses/DisputesChallenge'
'400':
$ref: '#/components/responses/BadRequestError_bad_request'
'401':
$ref: '#/components/responses/AuthenticationError_invalid_secret_key'
'404':
$ref: '#/components/responses/NotFoundError'
'500':
$ref: '#/components/responses/UnexpectedError'
security:
- bearerAuth:
- secret_key
components:
responses:
DisputesChallenge:
description: Success. Disputes were challenged.
content:
application/json:
schema:
type: object
properties:
disputes:
type: array
items:
$ref: '#/components/schemas/DisputeNoHistory'
BadRequestError_bad_request:
description: >-
One of the required fields is missing or request is not formatted
correctly.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_400_bad_request'
AuthenticationError_invalid_secret_key:
description: The request cannot be authorized.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_401_invalid_secret_key'
NotFoundError:
description: You are using an incorrect ID.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_404'
UnexpectedError:
description: Something bad happened. We're notified.
content:
application/json:
schema:
$ref: '#/components/schemas/Error_500'
schemas:
DisputeNoHistory:
type: object
properties:
id:
$ref: '#/components/schemas/DisputeID'
attachments:
$ref: '#/components/schemas/DisputeAttachments'
payment_id:
$ref: '#/components/schemas/PaymentID'
description: ID of the payment.
amount:
type: string
example: '100.00'
description: Total disputed amount.
currency:
$ref: '#/components/schemas/Currency'
description: >-
The currency of the dispute. It's always equal to the currency of
the payment.
created_at:
$ref: '#/components/schemas/DisputeCreatedAt'
expired_at:
$ref: '#/components/schemas/DisputeExpiredAt'
status:
$ref: '#/components/schemas/DisputeStatus'
reason:
$ref: '#/components/schemas/DisputeReason'
days_left:
$ref: '#/components/schemas/DisputeDaysLeft'
items:
type: array
items:
$ref: '#/components/schemas/DisputeOrderItem'
order_number:
type: string
example: '#1234'
description: Merchant-assigned order number.
comment:
$ref: '#/components/schemas/DisputeComment'
required:
- id
- attachments
- payment_id
- amount
- currency
- created_at
- expired_at
- status
- reason
- days_left
- items
- order_number
- comment
Error_400_bad_request:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: bad_data
error:
type: string
example: bad_request
Error_401_invalid_secret_key:
type: object
properties:
status:
type: string
example: error
errorType:
type: string
example: not_authorized
error:
type: string
example: invalid secret key
Error_404:
type: string
example: 404 page not found
Error_500:
type: string
example: Internal Server error
DisputeID:
type: string
format: uuid
example: dispute id, uuid format
readOnly: true
description: ID of the dispute.
DisputeAttachments:
type: array
nullable: true
items:
type: string
example: attachment_1
readOnly: true
description: Array of links to images which were uploaded by customer.
PaymentID:
type: string
format: uuid
example: payment id, uuid format
readOnly: true
description: >-
Unique identifier for the payment (UUID), assigned by Tabby. Save it on
your side!
Currency:
type: string
enum:
- AED
- SAR
- KWD
example: AED
description: >
ISO 4217 currency code for the payment amount. Currently there are 3
possible currency options - depending on the country where the store is
located:
- `AED` - United Arab Emirates Dirham
- `SAR` - Saudi Riyal
- `KWD` - Kuwaiti Dinar
DisputeCreatedAt:
type: string
readOnly: true
example: '2018-10-17T00:00:00.000Z'
description: >-
Date and time the Dispute was created, in UTC, and displayed in ISO 8601
datetime format.
DisputeExpiredAt:
type: string
readOnly: true
example: '2018-10-17T00:00:00.000Z'
description: >-
Date and time of the expiration of the Dispute, in UTC, and displayed in
ISO 8601 datetime format.
DisputeStatus:
type: string
readOnly: true
enum:
- new
- declined
- cancelled
- refunded
- in_progress
- evidence_merchant
- evidence_customer
example: new
description: |
The current status of the dispute:
- `new` - dispute pending merchant approval for refund or initiate a challenge
- `declined` - dispute was declined by Tabby support
- `cancelled` - dispute was canceled by customer
- `refunded` - dispute was approved or the order was refunded via Payments API
- `in_progress` - merchant challenged dispute and need a response from Tabby support
- `evidence_merchant` - waiting for evidence from the merchant
- `evidence_customer` - waiting for evidence from the customer
DisputeReason:
type: string
readOnly: true
enum:
- unreceived_refund
- identity_theft
- product_issue
- not_delivered
example: unreceived_refund
description: >
Cause of the dispute was created (selected by customer). There are only
four reasons:
- `unreceived_refund` - a refund not received
- `identity_theft` - I did not place this order (also known as identity theft)
- `product_issue` - there was a problem with the product
- `not_delivered` - the order was not delivered
DisputeDaysLeft:
type: integer
format: uint16
description: How many days left before dispute will be automatically approved.
DisputeOrderItem:
type: object
properties:
reference_id:
type: string
example: payment id
description: Reference id from payment.
title:
type: string
example: Order item title
description: Order item title.
unit_price:
type: string
example: '100.00'
description: Order item unit price.
required:
- reference_id
- title
- unit_price
DisputeComment:
type: string
example: additional comments
description: The customer additional comments on the causes of the dispute.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >
Bearer authentication header of the form `Bearer `, where
`` is your `secret_key`.
````