Create a dispute 

Issuing
Disputes
Create a dispute

Creates an Issuing Dispute object. Individual pieces of evidence within the evidence object are optional at this point. Stripe only validates that required evidence is present during submission. Refer to Dispute reasons and evidence for more details about evidence requirements.

Parameters

  • evidenceobject

    Evidence provided for the dispute.

    • evidence.canceledobject

      Evidence provided when reason is ‘canceled’.

      • evidence.canceled.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.canceled.canceled_attimestamp

        Date when order was canceled.

      • evidence.canceled.cancellation_policy_providedboolean

        Whether the cardholder was provided with a cancellation policy.

      • evidence.canceled.cancellation_reasonstring

        Reason for canceling the order.

      • evidence.canceled.expected_attimestamp

        Date when the cardholder expected to receive the product.

      • evidence.canceled.explanationstring

        Explanation of why the cardholder is disputing this transaction.

      • evidence.canceled.product_descriptionstring

        Description of the merchandise or service that was purchased.

      • evidence.canceled.product_typeenum

        Whether the product was a merchandise or service.

        Possible enum values
        merchandise

        Tangible goods such as groceries and furniture.

        service

        Intangible goods such as domain name registration, flights and lessons.

      • evidence.canceled.return_statusenum

        Result of cardholder’s attempt to return the product.

        Possible enum values
        merchant_rejected

        The merchant rejected the return.

        successful

        The merchant accepted the return.

      • evidence.canceled.returned_attimestamp

        Date when the product was returned or attempted to be returned.

    • evidence.duplicateobject

      Evidence provided when reason is ‘duplicate’.

      • evidence.duplicate.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.duplicate.card_statementstring

        (ID of a file upload) Copy of the card statement showing that the product had already been paid for.

      • evidence.duplicate.cash_receiptstring

        (ID of a file upload) Copy of the receipt showing that the product had been paid for in cash.

      • evidence.duplicate.check_imagestring

        (ID of a file upload) Image of the front and back of the check that was used to pay for the product.

      • evidence.duplicate.explanationstring

        Explanation of why the cardholder is disputing this transaction.

      • evidence.duplicate.original_transactionstring

        Transaction (e.g., ipi_…) that the disputed transaction is a duplicate of. Of the two or more transactions that are copies of each other, this is original undisputed one.

    • evidence.fraudulentobject

      Evidence provided when reason is ‘fraudulent’.

      • evidence.fraudulent.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.fraudulent.explanationstring

        Explanation of why the cardholder is disputing this transaction.

    • evidence.merchandise_not_as_describedobject

      Evidence provided when reason is ‘merchandise_not_as_described’.

      • evidence.merchandise_not_as_described.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.merchandise_not_as_described.explanationstring

        Explanation of why the cardholder is disputing this transaction.

      • evidence.merchandise_not_as_described.received_attimestamp

        Date when the product was received.

      • evidence.merchandise_not_as_described.return_descriptionstring

        Description of the cardholder’s attempt to return the product.

      • evidence.merchandise_not_as_described.return_statusenum

        Result of cardholder’s attempt to return the product.

        Possible enum values
        merchant_rejected

        The merchant rejected the return.

        successful

        The merchant accepted the return.

      • evidence.merchandise_not_as_described.returned_attimestamp

        Date when the product was returned or attempted to be returned.

    • evidence.no_valid_authorizationobject

      Evidence provided when reason is ‘no_valid_authorization’.

      • evidence.no_valid_authorization.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.no_valid_authorization.explanationstring

        Explanation of why the cardholder is disputing this transaction.

    • evidence.not_receivedobject

      Evidence provided when reason is ‘not_received’.

      • evidence.not_received.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.not_received.expected_attimestamp

        Date when the cardholder expected to receive the product.

      • evidence.not_received.explanationstring

        Explanation of why the cardholder is disputing this transaction.

      • evidence.not_received.product_descriptionstring

        Description of the merchandise or service that was purchased.

      • evidence.not_received.product_typeenum

        Whether the product was a merchandise or service.

        Possible enum values
        merchandise

        Tangible goods such as groceries and furniture.

        service

        Intangible goods such as domain name registration, flights and lessons.

    • evidence.otherobject

      Evidence provided when reason is ‘other’.

      • evidence.other.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.other.explanationstring

        Explanation of why the cardholder is disputing this transaction.

      • evidence.other.product_descriptionstring

        Description of the merchandise or service that was purchased.

      • evidence.other.product_typeenum

        Whether the product was a merchandise or service.

        Possible enum values
        merchandise

        Tangible goods such as groceries and furniture.

        service

        Intangible goods such as domain name registration, flights and lessons.

    • evidence.reasonenum

      The reason for filing the dispute. The evidence should be submitted in the field of the same name.

      Possible enum values
      canceled

      Service or merchandise was canceled.

      duplicate

      There were multiple copies of a charge for a single purchase, or the charge was paid by other means.

      fraudulent

      The cardholder’s details were compromised and the cardholder claims to not have participated in the transaction.

      merchandise_not_as_described

      The merchandise was not as described.

      no_valid_authorization

      The merchant processed a transaction without first obtaining a correct and valid authorization approval.

      not_received

      Merchandise or service was not received.

      other

      All other types of disputes.

      service_not_as_described

      The service was not as described.

    • evidence.service_not_as_describedobject

      Evidence provided when reason is ‘service_not_as_described’.

      • evidence.service_not_as_described.additional_documentationstring

        (ID of a file upload) Additional documentation supporting the dispute.

      • evidence.service_not_as_described.canceled_attimestamp

        Date when order was canceled.

      • evidence.service_not_as_described.cancellation_reasonstring

        Reason for canceling the order.

      • evidence.service_not_as_described.explanationstring

        Explanation of why the cardholder is disputing this transaction.

      • evidence.service_not_as_described.received_attimestamp

        Date when the product was received.

  • metadataobject

    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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • transactionstring

    The ID of the issuing transaction to create a dispute for. For transaction on Treasury FinancialAccounts, use treasury.received_debit.

More parameters

  • amountinteger

    The dispute amount in the card’s currency and in the smallest currency unit. If not set, defaults to the full transaction amount.

Returns

Returns an Issuing Dispute object in unsubmitted status if creation succeeds.

POST /v1/issuing/disputes
curl https://api.stripe.com/v1/issuing/disputes \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
-d transaction=ipi_1MykXhFtDWhhyHE1UjsZZ3xQ \
-d "evidence[reason]"=fraudulent \
-d "evidence[fraudulent][explanation]"="This transaction is fraudulent."
Response
{
"id": "idp_1MykdxFtDWhhyHE1BFAV3osZ",
"object": "issuing.dispute",
"amount": 100,
"created": 1681947753,
"currency": "usd",
"evidence": {
"fraudulent": {
"additional_documentation": null,
"dispute_explanation": null,
"explanation": "This transaction is fraudulent.",
"uncategorized_file": null
},
"reason": "fraudulent"
},
"livemode": false,
"metadata": {},
"status": "unsubmitted",
"transaction": "ipi_1MykXhFtDWhhyHE1UjsZZ3xQ"
}