View Source Stripe.Dispute (stripity_stripe v3.2.0)

A dispute occurs when a customer questions your charge with their card issuer. When this happens, you have the opportunity to respond to the dispute with evidence that shows that the charge is legitimate.

Related guide: Disputes and fraud

Summary

Types

created()

evidence()

Evidence to upload, to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review. The combined character count of all fields is limited to 150,000.

t()

The dispute type.

Functions

close(dispute, params \\ %{}, opts \\ [])

Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.

list(params \\ %{}, opts \\ [])

Returns a list of your disputes.

retrieve(dispute, params \\ %{}, opts \\ [])

Retrieves the dispute with the given ID.

update(dispute, params \\ %{}, opts \\ [])

When you get a dispute, contacting your customer is always the best first step. If that doesn’t work, you can submit evidence to help us resolve the dispute in your favor. You can do this in your dashboard, but if you prefer, you can use the API to submit evidence programmatically.

Types

created()

@type created() :: %{
  optional(:gt) => integer(),
  optional(:gte) => integer(),
  optional(:lt) => integer(),
  optional(:lte) => integer()
}

evidence()

@type evidence() :: %{
  optional(:access_activity_log) => binary(),
  optional(:billing_address) => binary(),
  optional(:cancellation_policy) => binary(),
  optional(:cancellation_policy_disclosure) => binary(),
  optional(:cancellation_rebuttal) => binary(),
  optional(:customer_communication) => binary(),
  optional(:customer_email_address) => binary(),
  optional(:customer_name) => binary(),
  optional(:customer_purchase_ip) => binary(),
  optional(:customer_signature) => binary(),
  optional(:duplicate_charge_documentation) => binary(),
  optional(:duplicate_charge_explanation) => binary(),
  optional(:duplicate_charge_id) => binary(),
  optional(:product_description) => binary(),
  optional(:receipt) => binary(),
  optional(:refund_policy) => binary(),
  optional(:refund_policy_disclosure) => binary(),
  optional(:refund_refusal_explanation) => binary(),
  optional(:service_date) => binary(),
  optional(:service_documentation) => binary(),
  optional(:shipping_address) => binary(),
  optional(:shipping_carrier) => binary(),
  optional(:shipping_date) => binary(),
  optional(:shipping_documentation) => binary(),
  optional(:shipping_tracking_number) => binary(),
  optional(:uncategorized_file) => binary(),
  optional(:uncategorized_text) => binary()
}

Evidence to upload, to respond to a dispute. Updating any field in the hash will submit all fields in the hash for review. The combined character count of all fields is limited to 150,000.

t()

@type t() :: %Stripe.Dispute{
  amount: integer(),
  balance_transactions: term(),
  charge: binary() | Stripe.Charge.t(),
  created: integer(),
  currency: binary(),
  evidence: term(),
  evidence_details: term(),
  id: binary(),
  is_charge_refundable: boolean(),
  livemode: boolean(),
  metadata: term(),
  network_reason_code: binary() | nil,
  object: binary(),
  payment_intent: (binary() | Stripe.PaymentIntent.t()) | nil,
  payment_method_details: term(),
  reason: binary(),
  status: binary()
}

The dispute type.

amount Disputed amount. Usually the amount of the charge, but it can differ (usually because of currency fluctuation or because only part of the order is disputed).
balance_transactions List of zero, one, or two balance transactions that show funds withdrawn and reinstated to your Stripe account as a result of this dispute.
charge ID of the charge that's disputed.
created Time at which the object was created. Measured in seconds since the Unix epoch.
currency Three-letter ISO currency code, in lowercase. Must be a supported currency.
evidence
evidence_details
id Unique identifier for the object.
is_charge_refundable If true, it's still possible to refund the disputed payment. After the payment has been fully refunded, no further funds are withdrawn from your Stripe account as a result of this dispute.
livemode Has the value true if the object exists in live mode or the value false if the object exists in test mode.
metadata Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.
network_reason_code Network-dependent reason code for the dispute.
object String representing the object's type. Objects of the same type share the same value.
payment_intent ID of the PaymentIntent that's disputed.
payment_method_details
reason Reason given by cardholder for dispute. Possible values are bank_cannot_process, check_returned, credit_not_processed, customer_initiated, debit_not_authorized, duplicate, fraudulent, general, incorrect_account_details, insufficient_funds, product_not_received, product_unacceptable, subscription_canceled, or unrecognized. Learn more about dispute reasons.
status Current status of dispute. Possible values are warning_needs_response, warning_under_review, warning_closed, needs_response, under_review, won, or lost.

Functions

close(dispute, params \\ %{}, opts \\ [])

@spec close(
  dispute :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Closing the dispute for a charge indicates that you do not have any evidence to submit and are essentially dismissing the dispute, acknowledging it as lost.

The status of the dispute will change from needs_response to lost. Closing a dispute is irreversible.

Details

Method: post
Path: /v1/disputes/{dispute}/close

list(params \\ %{}, opts \\ [])

@spec list(
  params :: %{
    optional(:charge) => binary(),
    optional(:created) => created() | integer(),
    optional(:ending_before) => binary(),
    optional(:expand) => [binary()],
    optional(:limit) => integer(),
    optional(:payment_intent) => binary(),
    optional(:starting_after) => binary()
  },
  opts :: Keyword.t()
) ::
  {:ok, Stripe.List.t(t())} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Returns a list of your disputes.

Details

Method: get
Path: /v1/disputes

retrieve(dispute, params \\ %{}, opts \\ [])

@spec retrieve(
  dispute :: binary(),
  params :: %{optional(:expand) => [binary()]},
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Retrieves the dispute with the given ID.

Details

Method: get
Path: /v1/disputes/{dispute}

update(dispute, params \\ %{}, opts \\ [])

@spec update(
  dispute :: binary(),
  params :: %{
    optional(:evidence) => evidence(),
    optional(:expand) => [binary()],
    optional(:metadata) => %{optional(binary()) => binary()} | binary(),
    optional(:submit) => boolean()
  },
  opts :: Keyword.t()
) :: {:ok, t()} | {:error, Stripe.ApiErrors.t()} | {:error, term()}

Depending on your dispute type, different evidence fields will give you a better chance of winning your dispute. To figure out which evidence fields to provide, see our guide to dispute types.

Details

Method: post
Path: /v1/disputes/{dispute}