# List disputes

Used to fetch a paginated list of disputes

Endpoint: GET /disputes
Version: 1.1.0
Security: secretApiKeyAuth

## Query parameters:

  - `startTimestamp` (integer)
    The start timestamp (inclusive), it must be before the endTimestamp.
    Example: 1641859200

  - `endTimestamp` (integer)
    The timestamp when to return payment sessions up to (inclusive), it must be after the startTimestamp.
    Example: 1641945599

  - `ascending` (boolean)
    Control the order (newest or oldest) in which the disputes are returned. false will arrange the results with newest first, whereas true shows oldest first. The default is false.

  - `limit` (integer)
    Control how many items are return in a given page The max limit we allow is 25. The default is 10.
    Example: 10

  - `startsAfter` (string)
    A token to identify where to resume a subsequent paginated query. The value of the paginationToken field from that response should be supplied here, to retrieve the next page of results for that timestamp range.
    Example: "dsp_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"

## Response 200 fields (application/json):

  - `items` (array)

  - `items.id` (string)
    The ID of the dispute
    Example: "dsp_01G0EYVFR02KBBVE2YWQ8AKMGJ"

  - `items.amount` (integer)
    The amount that is being disputed and the merchant is liable for
    Example: 500

  - `items.currency` (string)
    The ISO currency code
    Example: "GBP"

  - `items.status` (string)
    Enum: "Open", "Cancelled", "Accepted", "Challenged", "Lost", "Won", "Expired"

  - `items.category` (string)
    Disputes are grouped into a specific category based on their reason.code. These define the overlapping reason across various card schemes (who each have their own codes)
    Enum: "Fraudulent", "Authorization", "ProcessingError", "CardholderDispute", "General"

  - `items.reason` (object)

  - `items.reason.code` (string)
    The reason code provided by the card scheme
    Example: "13.6"

  - `items.reason.description` (string)
    Description of the code
    Example: "Merchandise/Services Not Received"

  - `items.respondBy` (integer)
    The deadline by which the evidence needs responding by. Note that you cannot attach evidence or challenge the dispute once this date has passed. The dispute will move to Expired.
    Example: 1685059200

  - `items.recommendedEvidence` (array)
    The evidence strongly recommended for the best chance to challenge and win the dispute. Note that this is based on the underlying reason.code of the Dispute and is subject to change should further types of evidence be added or no longer supported. Leverage this field to select the best forms of evidence should you choose to challenge the dispute.
    Enum: "ProofOfDelivery", "BillingAddress", "ShippingAddress", "DuplicateTransaction", "CustomerSignature", "Receipt", "ShippingConfirmation", "CustomerCommunication", "RefundPolicy", "CancellationPolicy", "RecurringPaymentAgreement", "Uncategorised"

  - `items.paymentSession` (object)
    Details of the payment session linked to the dispute.

  - `items.paymentSession.id` (string)
    The ID of the payment session the dispute relates to.
    Example: "ps_01G0EYVFR02KBBVE2YWQ8AKMGJ"

  - `items.paymentSession.paymentType` (string)
    Enum: "Standard", "Unscheduled", "MOTO", "Recurring"

  - `items.paymentSession.paymentMethod` (object)

  - `items.paymentSession.paymentMethod.card` (object)
    Details of the card used

  - `items.paymentSession.paymentMethod.card.scheme` (string)
    Enum: "Visa", "Mastercard", "Amex"

  - `items.paymentSession.paymentMethod.card.last4` (string)
    The last 4 digits of the card used
    Example: "4444"

  - `items.evidence` (object,null)
    The text/file evidence you have attached to the dispute.

  - `items.evidence.text` (object,null)
    Contains any evidence in text format

  - `items.evidence.text.billingAddress` (string,null)
    Billing address provided by the customer on the original transaction. We will automatically append this if it was provided.

  - `items.evidence.text.shippingAddress` (string,null)
    Shipping address the product or service were shipped to. Note we recommend also attaching any supporting files you have that confirm shipment to the same address. We will automatically append this if it was provided, however you can amend it if the address after taking payment with Ryft.

  - `items.evidence.text.duplicateTransaction` (string,null)
    Relevant when category is Duplicate. Use this to attach an explanation detailing why the transaction in dispute is unique and not in fact a duplicate of a previous transaction.

  - `items.evidence.text.uncategorised` (string,null)
    Any miscellanous text evidence you have attached.

  - `items.evidence.files` (object,null)
    Contains any evidence in file format

  - `items.evidence.files.proofOfDelivery` (any)
    Proof of delivery to the customer's shipping address.

  - `items.evidence.files.customerSignature` (any)
    Document/contract containing the customer's signature for the service or product.

  - `items.evidence.files.receipt` (any)
    Receipt or invoice confirming purchase of the product.

  - `items.evidence.files.shippingConfirmation` (any)
    Document proving the product was shipped to the same shipping address the customer provided. This could be a shipping label/confirmation from the shipping courier. Make sure the shipping address is also clearly visible within the file.

  - `items.evidence.files.customerCommunication` (any)
    Any communication with the customer that proves they received and or are happy with the product.

  - `items.evidence.files.refundPolicy` (any)
    Document containing your refund policy.

  - `items.evidence.files.recurringPaymentAgreement` (any)
    Document containing your recurring/subscription agreement.

  - `items.evidence.files.uncategorised` (any)
    Used to attach any miscellanous or additional evidence you feel is relevant to the dispute.

  - `items.customer` (object,null)
    Details of the customer who is making the dispute

  - `items.customer.email` (string,null)
    The email that was used for the disputed payment
    Example: "john.doe@ryftpay.com"

  - `items.customer.id` (string,null)
    The Ryft ID of the customer
    Example: "cus_01G0EYVFR02KBBVE2YWQ8AKMGJ"

  - `items.customer.createdTimestamp` (integer,null)
    The epoch timestamp (seconds) when the customer was first recorded/created
    Example: 1470989538

  - `items.subAccount` (object,null)
    If this dispute is for a payment under a sub account, then this contains details of that account

  - `items.subAccount.id` (string)
    The Ryft ID of the sub account
    Example: "ac_3fe8398f-8cdb-43a3-9be2-806c4f84c327"

  - `items.createdTimestamp` (integer)
    The epoch timestamp (seconds) when the dispute was created
    Example: 1470989538

  - `items.lastUpdatedTimestamp` (integer)
    The epoch timestamp (seconds) when the dispute was last updated
    Example: 1470989538

  - `paginationToken` (string)
    A token to use for getting the next page of results - send the same request with this value in the 'paginationToken' query parameter. This field is null when there are no further items to return
    Example: "dsp_01FCTS1XMKH9FF43CAFA4CXT3P_1641912473"

## Response 400 fields (application/json):

  - `requestId` (string)
    Example: "b83f2653-06d7-44a9-a548-5825e8186004"

  - `code` (string)
    Example: "400"

  - `errors` (array)

  - `errors.message` (string)
    Example: "Required property 'amount' not found in JSON"

## Response 500 fields (application/json):

  - `requestId` (string)
    Example: "b83f2653-06d7-44a9-a548-5825e8186004"

  - `code` (string)
    Example: "400"

  - `errors` (array)

  - `errors.message` (string)
    Example: "Required property 'amount' not found in JSON"