About Partner Disputes API

Overview

The Partner Disputes API enables partners to manage the entire lifecycle of their disputes, including accessing dispute details, closing disputes, and submitting supporting evidence. Within managing the lifecycle of your disputes, the Partner Disputes API provides you with the following actions:

Explore the sections below to learn about the dispute endpoints and their requirements.


Basic Requirements

Authentication

All Partner Disputes API endpoints require merchant authentication.

Idempotency

For idempotent requests, the idempotency key has an expiration date of 24 hours. Idempotency keys are passed in using the Idempotency-Key header.


List Disputes

GET /api/partner/v1/merchants/{merchant_id}/disputes

This endpoint is used to list all disputes for a given merchant.

Idempotency: No

Response Schema:

Field NameData TypeDescription
idstringDispute ID.
transaction_idintegerID of the charge associated with the dispute.
amountintegerDispute amount in the smallest denomination of the currency, such as cents.

Example: 10000
currencystringThe local currency of the dispute; must be a valid subset of the ISO 4217 currency code.

Example: USD
reasonenumDispute reason. Possible values are:

- affirm_fraud_review
- cancellation_or_return_not_processed
- credit_not_processed
- duplicate
- fake_product
- fraudulent
- incorrect_amount
- other
- product_not_received
- product_unacceptable
- subscription_canceled
- technical_issue
- unrecognized
statusenumCurrent status of the dispute

- lost
- needs_review
- partially_won
- under_review
- won
openbooleanFalse if final decision on the dispute has been made, otherwise True.
response_due_bystringDeadline by which merchant must respond to the dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
createdstringTimestamp indicating when the dispute was opened, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
opening_notestringText description from the customer describing the complaint reason for the dispute.
opening_note_attachmentsstringAttachments to supplement the opening_note.

Example: File-ID-123
closed_atstringTimestamp indicating when the dispute was closed, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
closing_reasonenumReason indicating how the final decision for the dispute was reached.

- customer_canceled
- deadline_expired
- evidence_accepted
- evidence_rejected
- merchant_accepted
closing_notestringText description detailing how the final decision on the dispute was reached. Supplements the closing_reason.
evidence_received_atstringTimestamp indicating when evidence was received for this dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z


Get Dispute

GET /api/partner/v1/merchants/{merchant_id}/disputes/{dispute_id}

This endpoint is used to fetch information about a dispute using a dispute_id.

Idempotency: No

Response Schema:

Field NameData TypeDescription
idstringDispute ID.
transaction_idintegerID of the charge associated with the dispute.
amountintegerDispute amount in the smallest denomination of the currency, such as cents.

Example: 10000
currencystringThe local currency of the dispute; must be a valid subset of the ISO 4217 currency code.

Example: USD
reasonenumDispute reason. Possible values are:

- affirm_fraud_review
- cancellation_or_return_not_processed
- credit_not_processed
- duplicate
- fake_product
- fraudulent
- incorrect_amount
- other
- product_not_received
- product_unacceptable
- subscription_canceled
- technical_issue
- unrecognized
statusenumCurrent status of the dispute

lost
needs_review
partially_won
under_review
won
openbooleanFalse if final decision on the dispute has been made, otherwise True.
response_due_bystringDeadline by which merchant must respond to the dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
createdstringTimestamp indicating when the dispute was opened, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
opening_notestringText description from the customer describing the complaint reason for the dispute.
opening_note_attachmentsstringAttachments to supplement the opening_note.

Example: File-ID-123
closed_atstringTimestamp indicating when the dispute was closed, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
closing_reasonenumReason indicating how the final decision for the dispute was reached.

customer_canceled
deadline_expired
evidence_accepted
evidence_rejected
merchant_accepted
closing_notestringText description detailing how the final decision on the dispute was reached. Supplements the closing_reason.
evidence_received_atstringTimestamp indicating when evidence was received for this dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z

Error Responses
Status code 401
{
"status_code": 401,
"message": "You have provided an invalid API key pair.",
"code": "api-key-pair-invalid",
"type": "unauthorized"
}
Status code 401
{
"status_code": 401,
"message": "You did not provide an API key pair.",
"code": "api-key-pair-not-found",
"type": "unauthorized"
}
Status code 404
{
"code": "not_found",
"message": "Not found"
}
Status code 500
{
"code": "internal_server_error",
"message": "Internal server error"
}

Close Dispute

POST /api/partner/v1/merchants/{merchant_id}/disputes/{dispute_id}/close

This endpoint will move the dispute to the merchant loss state.

Idempotency: Yes

Response Schema:

Field NameData TypeDescription
idstringDispute ID.
transaction_idintegerID of the charge associated with the dispute.
amountintegerDispute amount in the smallest denomination of the currency, such as cents.

Example: 10000
currencystringThe local currency of the dispute; must be a valid subset of the ISO 4217 currency code.

Example: USD
reasonenumDispute reason. Possible values are:

- affirm_fraud_review
- cancellation_or_return_not_processed
- credit_not_processed
- duplicate
- fake_product
- fraudulent
- incorrect_amount
- other
- product_not_received
- product_unacceptable
- subscription_canceled
- technical_issue
- unrecognized
statusenumCurrent status of the dispute

lost
needs_review
partially_won
under_review
won
openbooleanFalse if final decision on the dispute has been made, otherwise True.
response_due_bystringDeadline by which merchant must respond to the dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
createdstringTimestamp indicating when the dispute was opened, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
opening_notestringText description from the customer describing the complaint reason for the dispute.
opening_note_attachmentsstringAttachments to supplement the opening_note.

Example: File-ID-123
closed_atstringTimestamp indicating when the dispute was closed, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
closing_reasonenumReason indicating how the final decision for the dispute was reached.

customer_canceled
deadline_expired
evidence_accepted
evidence_rejected
merchant_accepted
closing_notestringText description detailing how the final decision on the dispute was reached. Supplements the closing_reason.
evidence_received_atstringTimestamp indicating when evidence was received for this dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z

Error Responses
Status code 401
{
"status_code": 401,
"message": "You have provided an invalid API key pair.",
"code": "api-key-pair-invalid",
"type": "unauthorized"
}
Status code 401
{
"status_code": 401,
"message": "You did not provide an API key pair.",
"code": "api-key-pair-not-found",
"type": "unauthorized"
}
Status code 404
{
"code": "not_found",
"message": "Not found"
}
Status code 404
{
"code": "dispute_close_reason_not_found",
"message": "Dispute close reason not found"
}
Status code 400
{
"code": "dispute_already_closed",
"message": "Cannot close or submit evidence for an already closed dispute"
}
Status code 400
{
"code": "idempotency_data_conflict",
"message": "Idempotency key has been reused with different request data."
}
Status code 400
{
"code": "invalid_argument",
"message": "Idempotency key must be <= 36 chars."
}
Status code 409
{
"code": "idempotent_request_in_progress",
"message": "The request with this idempotency key is processing. Please wait to retry or use a different idempotency key."
}
Status code 500
{
"code": "internal_server_error",
"message": "Internal server error"
}

Respond to Dispute (Submit Evidence)

POST /api/partner/v1/merchants/{merchant_id}/disputes/{dispute_id}/submit_evidence

This endpoint is used to update disputes with supporting evidence from the merchant to challenge the dispute.

Idempotency: Yes

Request Schema:

Field NameDescription
evidence_file_tokenID of evidence file that was uploaded using a separate file upload API.

Example: FILE-ID-123
shipping_carrierThe delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If a merchant reports multiple carriers, then separate them by commas.
shipping_tracking_number The tracking number for a physical product that was delivered to the customer. If a merchant provides multiple tracking numbers, then separate them by commas.
billing_addressThe billing address provided by the customer (if the AVS check was successful). This field is automatically filled on behalf of the merchant, when possible.
customer_nameThe name of the customer. This field is automatically filled on behalf of the merchant, when possible.
customer_email_addressThe email address of the customer. This field is automatically filled on behalf of the merchant, when possible.
customer_purchase_ipThe IP address that the customer used when making the purchase. This field is automatically filled on behalf of the merchant when possible, and is expanded to include geographical data before being sent to the Merchant.
customer_signatureA relevant document or contract showing the customer’s signature and/or evidence that the person who signed for the products was authorized to.
customer_communicationAny communication with the customer that the merchant feels is relevant to the case (e.g., emails proving that the customer received the product or service, or demonstrating the customer’s use of or satisfaction with the product or service).
receiptAny receipt or message sent to the customer notifying them of the charge.
product_descriptionA description of the product or service and any relevant details on how this was presented to the customer at the time of purchase.
cancellation_policyMerchant’s subscription cancellation policy, as shown to the customer.
cancellation_policy_disclosureAn explanation of how and when the customer was shown the merchant’s cancellation policy prior to purchase.
cancellation_rebuttalA justification for why the customer’s subscription was not canceled.
refund_policyThe merchant’s refund policy, as shown or provided to the customer.
refund_policy_disclosureAn explanation of how and when the customer was shown or provided with the merchant’s refund policy prior to purchase.
refund_refusal_explanationThe merchant’s explanation for why the customer is not entitled to a refund.
duplicate_charge_idThe charge ID for the previous payment that appears to be a duplicate of the one that is disputed.
duplicate_charge_explanationAn explanation of the difference between the disputed payment and the prior one that appears to be a duplicate.
duplicate_charge_documentationDocumentation for the prior payment that can uniquely identify it, such as a separate receipt. This document should be paired with a similar document from the disputed payment that proves the two are separate. This should also include a separate shipping label or receipt for the other payment. If multiple products were shipped together, provide a packing list that shows each purchase.
shipping_documentationA shipping label or receipt for the disputed payment.
shipping_addressIn cases of physical Products, the address a physical product was shipped to. The shipping address must match a billing address verified with AVS. (A signature is not required as evidence of delivery). The merchant must also provide documentation as proof that a product was shipped to the customer at the same address the customer provided. This could include a copy of the shipment receipt or label, and show the full shipping address of the customer if possible.
shipping_dateIn cases of physical products, the date that a physical product began its route to the shipping address in a clear human-readable format. This date should be prior to the date of the dispute.
service_documentationA copy of a service agreement or documentation for the disputed payment. This could include a copy of a signed contract, work order, or other form of written agreement.
service_dateDocumentation showing proof that a service was provided on a given date.
access_activity_logsFor digital products or services, evidence of access including at least two of the following pieces of information:

-Customer’s IP address and their device’s geographical location at the time of purchase
-Device ID and name of the device
-Customer name and email address linked to their customer profile
-Evidence that the customer logged in to their account for your business before the transaction date
-Evidence that the merchant website or app was accessed by the customer for purchase or services on or after the transaction date
-Evidence that the same device and payment method used in the disputed payment was used in a previous payment that was not disputed
uncategorized_fileAdditional file deemed relevant by the merchant, which may include:

-A signed order form for products purchased by mail or phone order
-Evidence that the transaction was completed by a member of the cardholder’s family or household
-Evidence of one or more non-disputed payments for the same products
-For recurring payments, evidence of a legally binding contract held between your business and the customer, that the customer is using the products, and of any previous payments not disputed
uncategorized_textAny additional text deemed relevant by the merchant.

Response Schema:

Field NameData TypeDescription
idstringDispute ID.
transaction_idintegerID of the charge associated with the dispute.
amountintegerDispute amount in the smallest denomination of the currency, such as cents.

Example: 10000
currencystringThe local currency of the dispute; must be a valid subset of the ISO 4217 currency code.

Example: USD
reasonenumDispute reason. Possible values are:

- affirm_fraud_review
- cancellation_or_return_not_processed
- credit_not_processed
- duplicate
- fake_product
- fraudulent
- incorrect_amount
- other
- product_not_received
- product_unacceptable
- subscription_canceled
- technical_issue
- unrecognized
statusenumCurrent status of the dispute

lost
needs_review
partially_won
under_review
won
openbooleanFalse if final decision on the dispute has been made, otherwise True.
response_due_bystringDeadline by which merchant must respond to the dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
createdstringTimestamp indicating when the dispute was opened, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
opening_notestringText description from the customer describing the complaint reason for the dispute.
opening_note_attachmentsstringAttachments to supplement the opening_note.

Example: File-ID-123
closed_atstringTimestamp indicating when the dispute was closed, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z
closing_reasonenumReason indicating how the final decision for the dispute was reached.

customer_canceled
deadline_expired
evidence_accepted
evidence_rejected
merchant_accepted
closing_notestringText description detailing how the final decision on the dispute was reached. Supplements the closing_reason.
evidence_received_atstringTimestamp indicating when evidence was received for this dispute, in ISO 8601 UTC format.

Example: 2024-03-02T14:29:07Z

Error Responses
Status code 401
{
"status_code": 401,
"message": "You have provided an invalid API key pair.",
"code": "api-key-pair-invalid",
"type": "unauthorized"
}
Status code 401
{
"status_code": 401,
"message": "You did not provide an API key pair.",
"code": "api-key-pair-not-found",
"type": "unauthorized"
}
Status code 404
{
"code": "not_found",
"message": "Not found"
}
Status code 400
{
"code": "evidence_file_id_not_found",
"message": "Evidence file token missing"
}
Status code 400
{
"code": "invalid_dispute_evidence_fields",
"message": "Invalid dispute evidence field names for evidence submission"
}
Status code 400
{
"code": "dispute_already_closed",
"message": "Cannot close or submit evidence for an already closed dispute"
}
Status code 400
{
"code": "evidence_fields_not_found",
"message": "Evidence fields not found"
}
Status code 400
{
"code": "evidence_past_dispute_window",
"message": "Evidence past dispute window"
}
Status code 400
{
"code": "idempotency_data_conflict",
"message": "Idempotency key has been reused with different request data."
}
Status code 400
{
"code": "invalid_argument",
"message": "Idempotency key must be <= 36 chars."
}
Status code 409
{
"code": "idempotent_request_in_progress",
"message": "The request with this idempotency key is processing. Please wait to retry or use a different idempotency key."
}
Status code 500
{
"code": "internal_server_error",
"message": "Internal server error"
}

File Management

📘

Uploading and Downloading Files

To learn more about uploading and downloading files for disputes, please review the Partner Files API.


Dispute Webhooks

Webhooks will be sent upon dispute creation as well as any subsequent dispute update, to inform our partner of a change in the state of the dispute. Partners will then use our /get_dispute endpoint to grab the latest dispute snapshot after the state change.

Below are the instances where webhooks will be sent as part of the Partner Disputes API:

Dispute Event DescriptionEvent TypeAdditional Notes
Dispute openeddispute_createdWebhook sent upon dispute open notifying our partner that a dispute has been opened.
Merchant evidence submitteddispute_updatedWebhook sent after our partner has uploaded evidence through our Partner Files API and hit our /submit_evidence endpoint.
Dispute closeddispute_closedWebhook sent after the dispute has been closed.

Below is the webhook schema that will be sent upon each of the above instances:

Field NameData TypeDescription
event_idstringUnique identifier for the webhook event.
event_typestringAn enum indicating if the dispute was created, updated, or closed. Possible values:

-dispute_created
-dispute_updated
-dispute_closed
dispute_idstringUnique identifier for the dispute that the webhook corresponds to.
merchant_idstringUnique Affirm identifier for the merchant.