Overview
The Disputes API enables merchants 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 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 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.
Get Dispute
GET /api/v1/disputes/{dispute_id}
This endpoint is used to fetch information about a dispute using a dispute_id.
Idempotency: No
Response Schema:
| Field Name | Data Type | Description |
|---|---|---|
id | string | Dispute ID. |
transaction_id | integer | ID of the charge associated with the dispute. |
amount | integer | Dispute amount in the smallest denomination of the currency, such as cents. Example: 10000 |
currency | string | The local currency of the dispute; must be a valid subset of the ISO 4217 currency code. Example: USD |
reason | enum | Dispute 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 |
status | enum | Current status of the dispute lost needs_review partially_won under_review won |
open | boolean | False if final decision on the dispute has been made, otherwise True. |
response_due_by | string | Deadline by which merchant must respond to the dispute, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
created | string | Timestamp indicating when the dispute was opened, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
opening_note | string | Text description from the customer describing the complaint reason for the dispute. |
opening_note_attachments | string | Attachments to supplement the opening_note.Example: File-ID-123 |
closed_at | string | Timestamp indicating when the dispute was closed, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
closing_reason | enum | Reason indicating how the final decision for the dispute was reached. customer_canceled deadline_expired evidence_accepted evidence_rejected merchant_accepted |
closing_note | string | Text description detailing how the final decision on the dispute was reached. Supplements the closing_reason. |
evidence_received_at | string | Timestamp 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/v1/disputes/{dispute_id}/close
This endpoint will move the dispute to the merchant loss state.
Idempotency: Yes
Response Schema:
| Field Name | Data Type | Description |
|---|---|---|
id | string | Dispute ID. |
transaction_id | integer | ID of the charge associated with the dispute. |
amount | integer | Dispute amount in the smallest denomination of the currency, such as cents. Example: 10000 |
currency | string | The local currency of the dispute; must be a valid subset of the ISO 4217 currency code. Example: USD |
reason | enum | Dispute 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 |
status | enum | Current status of the dispute lost needs_review partially_won under_review won |
open | boolean | False if final decision on the dispute has been made, otherwise True. |
response_due_by | string | Deadline by which merchant must respond to the dispute, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
created | string | Timestamp indicating when the dispute was opened, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
opening_note | string | Text description from the customer describing the complaint reason for the dispute. |
opening_note_attachments | string | Attachments to supplement the opening_note.Example: File-ID-123 |
closed_at | string | Timestamp indicating when the dispute was closed, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
closing_reason | enum | Reason indicating how the final decision for the dispute was reached. customer_canceled deadline_expired evidence_accepted evidence_rejected merchant_accepted |
closing_note | string | Text description detailing how the final decision on the dispute was reached. Supplements the closing_reason. |
evidence_received_at | string | Timestamp 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/v1/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 Name | Description |
|---|---|
evidence_file_token | ID of evidence file that was uploaded using a separate file upload API. Example: FILE-ID-123 |
shipping_carrier | The 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_address | The 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_name | The name of the customer. This field is automatically filled on behalf of the merchant, when possible. |
customer_email_address | The email address of the customer. This field is automatically filled on behalf of the merchant, when possible. |
customer_purchase_ip | The 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_signature | A relevant document or contract showing the customer’s signature and/or evidence that the person who signed for the products was authorized to. |
customer_communication | Any 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). |
receipt | Any receipt or message sent to the customer notifying them of the charge. |
product_description | A description of the product or service and any relevant details on how this was presented to the customer at the time of purchase. |
cancellation_policy | Merchant’s subscription cancellation policy, as shown to the customer. |
cancellation_policy_disclosure | An explanation of how and when the customer was shown the merchant’s cancellation policy prior to purchase. |
cancellation_rebuttal | A justification for why the customer’s subscription was not canceled. |
refund_policy | The merchant’s refund policy, as shown or provided to the customer. |
refund_policy_disclosure | An explanation of how and when the customer was shown or provided with the merchant’s refund policy prior to purchase. |
refund_refusal_explanation | The merchant’s explanation for why the customer is not entitled to a refund. |
duplicate_charge_id | The charge ID for the previous payment that appears to be a duplicate of the one that is disputed. |
duplicate_charge_explanation | An explanation of the difference between the disputed payment and the prior one that appears to be a duplicate. |
duplicate_charge_documentation | Documentation 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_documentation | A shipping label or receipt for the disputed payment. |
shipping_address | In 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_date | In 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_documentation | A 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_date | Documentation showing proof that a service was provided on a given date. |
access_activity_logs | For 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_file | Additional 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_text | Any additional text deemed relevant by the merchant. |
Response Schema:
| Field Name | Data Type | Description |
|---|---|---|
id | string | Dispute ID. |
transaction_id | integer | ID of the charge associated with the dispute. |
amount | integer | Dispute amount in the smallest denomination of the currency, such as cents. Example: 10000 |
currency | string | The local currency of the dispute; must be a valid subset of the ISO 4217 currency code. Example: USD |
reason | enum | Dispute 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 |
status | enum | Current status of the dispute lost needs_review partially_won under_review won |
open | boolean | False if final decision on the dispute has been made, otherwise True. |
response_due_by | string | Deadline by which merchant must respond to the dispute, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
created | string | Timestamp indicating when the dispute was opened, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
opening_note | string | Text description from the customer describing the complaint reason for the dispute. |
opening_note_attachments | string | Attachments to supplement the opening_note.Example: File-ID-123 |
closed_at | string | Timestamp indicating when the dispute was closed, in ISO 8601 UTC format. Example: 2024-03-02T14:29:07Z |
closing_reason | enum | Reason indicating how the final decision for the dispute was reached. customer_canceled deadline_expired evidence_accepted evidence_rejected merchant_accepted |
closing_note | string | Text description detailing how the final decision on the dispute was reached. Supplements the closing_reason. |
evidence_received_at | string | Timestamp 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 Files API.
Dispute Webhooks
Webhooks will be sent upon dispute creation as well as any subsequent dispute update, to inform our merchant of a change in the state of the dispute. Merchant 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 Disputes API:
| Dispute Event Description | Event Type | Additional Notes |
|---|---|---|
| Dispute opened | dispute_created | Webhook sent upon dispute open notifying our merchant that a dispute has been opened. |
| Merchant evidence submitted | dispute_updated | Webhook sent after our merchant has uploaded evidence through our Files API and hit our /submit_evidence endpoint. |
| Dispute closed | dispute_closed | Webhook sent after the dispute has been closed. |
Below is the webhook schema that will be sent upon each of the above instances:
| Field Name | Data Type | Description |
|---|---|---|
event_id | string | Unique identifier for the webhook event. |
event_type | string | An enum indicating if the dispute was created, updated, or closed. Possible values: - dispute_created- dispute_updated- dispute_closed |
dispute_id | string | Unique identifier for the dispute that the webhook corresponds to. |
merchant_id | string | Unique Affirm identifier for the merchant. |