Disputes
Retrieve and respond to disputes. A dispute (chargeback) occurs when a cardholder questions a charge with their bank. Use this API to submit evidence.
The Dispute object
Attributes
Unique identifier for the dispute.
Current dispute status. Possible values include received, warning_needs_response, warning_under_review, warning_closed, needs_response, under_review, won, and lost.
Human-readable status for display in dashboards.
Disputed amount in the smallest currency unit (e.g. cents for USD).
Three-letter ISO currency code (uppercase) for the disputed amount.
Reason given by the cardholder for the dispute. Fields may be null until the issuer reports them.
Reference number assigned by the acquirer for tracking.
Authorization code from the original transaction.
true if live mode, false if test mode.
Unix timestamp of last update.
{
"id": "388f584c-0003-4470-9c52-667a3dd71e0b",
"status": "needs_response",
"display_status": "Under review",
"amount_cents": 2000,
"amount_currency": "USD",
"reason": {
"code": "fraudulent",
"description": "Cardholder claims the charge is fraudulent.",
"category": "fraud"
},
"acquirer_reference_number": "24692160000000123456789",
"authorization_code": "A1B2C3",
"charge_intent": {
"id": "a70cd72f-e74a-40f2-96a2-3f60714aac4a",
"object": "charge_intent",
"amount": 2000,
"currency": "usd",
"status": "incomplete",
"livemode": false,
"created": 1721010605,
"client_secret": "ci_a70cd72f_secret_xk3m2n9p",
"authorization_mode": "automatic",
"description": null,
"failure_description": null,
"reference_id": "user_8675309",
"customer": {},
"payment_method": {},
"subscription": null,
"invoice": null,
"latest_charge": {},
"shipping": null,
"metadata": {}
},
"livemode": false,
"updated": 1721010705
}
List disputes
Returns a list of your disputes. The disputes are returned in reverse chronological order.
Use the charge or charge_intent filters to narrow results to disputes associated with a specific charge or ChargeIntent.
Query parameters
The page offset at which you'd like to resume fetching data.
A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.
Only return disputes associated to the charge specified by this charge ID.
Only return disputes associated to the ChargeIntent specified by this ChargeIntent ID.
Returns
A dictionary with a data property that contains an array of up to per_page disputes. Each entry in the array is a separate Dispute object. If no other disputes are available, the resulting array is empty.
curl --request GET \
--url https://api.framepayments.com/v1/disputes \
--header 'Authorization: Bearer API_KEY'
{
"meta": {
"page": 1,
"url": "/v1/disputes",
"has_more": false,
"prev": null,
"next": null
},
"data": []
}
Get dispute
Retrieves the dispute with the given ID.
Returns a dispute if a valid dispute ID was provided. Returns an error otherwise.
Path parameters
The ID of the dispute to retrieve.
Returns
Returns a dispute object if a valid dispute ID was provided.
curl --request GET \
--url https://api.framepayments.com/v1/disputes/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "21fbb8e0-46e0-4254-912e-04e78641ba1d",
"status": "received",
"amount_currency": "USD",
"amount_cents": 1000,
"livemode": false,
"acquirer_reference_number": null,
"authorization_code": null,
"charge_intent": {
"id": "f2d93cb6-8ea0-4d52-85f3-d4be29172afe",
"currency": "usd",
"client_secret": "ci_f2d93cb6-8ea0-4d52-85f3-d4be29172afe_secret_UKTK9wQejnpreBBy1aEhUSoWV1nmRyWGLH1",
"status": "pending",
"description": null,
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 1000,
"amount_captured": 0,
"amount_voided": 0,
"created": 1781115875,
"livemode": false,
"subscription": null,
"invoice": null,
"latest_charge": {
"id": "8b188f06-3e32-4cee-b06a-acda003b4d34",
"currency": "usd",
"failure_code": null,
"failure_message": null,
"failure_category": null,
"description": null,
"status": "pending",
"acquirer_reference_number": null,
"authorization_code": null,
"object": "charge",
"payment_method_details": {
"id": "fd1ec367-ca54-411a-a7f0-35c847b1a7b0",
"customer_id": null,
"account_id": null,
"billing": {
"id": "eadbe50d-d9db-4bea-aaf5-55ec124ee2d6",
"city": "Welchport",
"country": "US",
"state": "CA",
"postal_code": "67335",
"line_1": "234 Tromp Rapids",
"line_2": "Suite 579",
"livemode": false,
"type": "billing"
},
"type": "card",
"object": "payment_method",
"created": 1781115875,
"updated": 1781115875,
"livemode": false,
"status": "active",
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "31",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
},
"customer": "a027ed30-0a15-4159-a390-1770a67bde4c",
"account": null,
"account_id": null,
"payment_method": "fd1ec367-ca54-411a-a7f0-35c847b1a7b0",
"amount": 1000,
"amount_captured": 0,
"amount_refunded": 0,
"created": 1781115875,
"updated": 1781115875,
"livemode": false,
"captured": true,
"disputed": false,
"charge_intent": "f2d93cb6-8ea0-4d52-85f3-d4be29172afe",
"refunded": false,
"net_amount": 926
},
"customer": {
"id": "a027ed30-0a15-4159-a390-1770a67bde4c",
"name": "Garth Ward I",
"email": "customer@frame.com",
"description": "sequi",
"status": "active",
"date_of_birth": null,
"phone": "+13107484186",
"billing_address": null,
"shipping_address": null,
"object": "customer",
"created": 1781115875,
"updated": 1781115875,
"livemode": false,
"metadata": {}
},
"account_id": null,
"account": null,
"payment_method": {
"id": "fd1ec367-ca54-411a-a7f0-35c847b1a7b0",
"customer_id": null,
"account_id": null,
"billing": {
"id": "eadbe50d-d9db-4bea-aaf5-55ec124ee2d6",
"city": "Welchport",
"country": "US",
"state": "CA",
"postal_code": "67335",
"line_1": "234 Tromp Rapids",
"line_2": "Suite 579",
"livemode": false,
"type": "billing"
},
"type": "card",
"object": "payment_method",
"created": 1781115875,
"updated": 1781115875,
"livemode": false,
"status": "active",
"card": {
"brand": "visa",
"exp_month": "12",
"exp_year": "31",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
},
"shipping": {
"id": "da3ef046-5aa1-42a3-8ea0-17b3a64b3e1e",
"city": "West Jonathonville",
"country": "US",
"state": "CA",
"postal_code": "61120",
"line_1": "25492 Hayes Pine",
"line_2": "Apt. 602",
"livemode": false,
"type": "shipping"
},
"metadata": {},
"cart_data": null
},
"object": "dispute",
"created": 1781115875,
"updated": 1781115875,
"display_status": "under_review",
"reason": {
"code": null,
"description": null,
"category": null
}
}
Update dispute
Upon receiving a dispute, initiating contact with your customer is advised as the primary step. Should direct communication prove ineffective, you can opt to submit evidence through your dashboard or programmatically via the API.
Different types of disputes may require specific evidence fields to increase the likelihood of a favorable resolution. Updating any field in the evidence hash submits all fields in the hash for review.
Path parameters
The ID of the dispute to update.
Body parameters
The tracking number for a physical product, obtained from the delivery service. If multiple tracking numbers were generated for this purchase, please separate them with commas.
The IP address that the customer used when making the purchase.
Documentation demonstrating that the customer was shown your refund policy prior to purchase.
Any server or activity logs showing proof that the customer accessed or downloaded the purchased digital product. This information should include IP addresses, corresponding timestamps, and any detailed recorded activity.
Returns
Returns the updated dispute object.
curl --request PATCH \
--url https://api.framepayments.com/v1/disputes/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
--header 'Authorization: Bearer API_KEY'
{
"id": "2bb1633c-cad2-48a3-bb75-c149c6621214",
"status": "received",
"amount_currency": "USD",
"amount_cents": 1000,
"livemode": false,
"acquirer_reference_number": null,
"authorization_code": null,
"charge_intent": {
"id": "1e9f66ed-35f0-40db-a4f8-4dce3637ab52",
"currency": "usd",
"client_secret": "ci_1e9f66ed-35f0-40db-a4f8-4dce3637ab52_secret_bPJM2ivghu2uVdmK7zVyrvBxD5SpP4HeKed",
"status": "pending",
"description": null,
"authorization_mode": "automatic",
"failure_description": null,
"object": "charge_intent",
"amount": 1000,
"amount_captured": 0,
"amount_voided": 0,
"created": 1781115876,
"livemode": false,
"subscription": null,
"invoice": null,
"latest_charge": {
"id": "737bb8fc-5d58-4fc2-b46b-680030476fa9",
"currency": "usd",
"failure_code": null,
"failure_message": null,
"failure_category": null,
"description": null,
"status": "pending",
"acquirer_reference_number": null,
"authorization_code": null,
"object": "charge",
"payment_method_details": {
"id": "a4021b60-f38f-43fa-b248-1360005343d9",
"customer_id": null,
"account_id": null,
"billing": {
"id": "fc8c136b-fde2-4c5b-b2bc-55b76d5b7f96",
"city": "South Dwana",
"country": "US",
"state": "CA",
"postal_code": "71696-8204",
"line_1": "91709 Quitzon Knolls",
"line_2": "Suite 392",
"livemode": false,
"type": "billing"
},
"type": "card",
"object": "payment_method",
"created": 1781115876,
"updated": 1781115876,
"livemode": false,
"status": "active",
"card": {
"brand": "visa",
"exp_month": "08",
"exp_year": "31",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
},
"customer": "661f72fa-b142-45a1-b195-ddc7e3284f7c",
"account": null,
"account_id": null,
"payment_method": "a4021b60-f38f-43fa-b248-1360005343d9",
"amount": 1000,
"amount_captured": 0,
"amount_refunded": 0,
"created": 1781115876,
"updated": 1781115876,
"livemode": false,
"captured": true,
"disputed": false,
"charge_intent": "1e9f66ed-35f0-40db-a4f8-4dce3637ab52",
"refunded": false,
"net_amount": 926
},
"customer": {
"id": "661f72fa-b142-45a1-b195-ddc7e3284f7c",
"name": "Spencer Auer",
"email": "customer@frame.com",
"description": "quaerat",
"status": "active",
"date_of_birth": null,
"phone": "+13107484186",
"billing_address": null,
"shipping_address": null,
"object": "customer",
"created": 1781115876,
"updated": 1781115876,
"livemode": false,
"metadata": {}
},
"account_id": null,
"account": null,
"payment_method": {
"id": "a4021b60-f38f-43fa-b248-1360005343d9",
"customer_id": null,
"account_id": null,
"billing": {
"id": "fc8c136b-fde2-4c5b-b2bc-55b76d5b7f96",
"city": "South Dwana",
"country": "US",
"state": "CA",
"postal_code": "71696-8204",
"line_1": "91709 Quitzon Knolls",
"line_2": "Suite 392",
"livemode": false,
"type": "billing"
},
"type": "card",
"object": "payment_method",
"created": 1781115876,
"updated": 1781115876,
"livemode": false,
"status": "active",
"card": {
"brand": "visa",
"exp_month": "08",
"exp_year": "31",
"issuer": null,
"currency": null,
"segment": null,
"type": null,
"last_four": "4242"
}
},
"shipping": {
"id": "ea04925b-e531-4076-a110-89c7b4c71fbb",
"city": "Port Malia",
"country": "US",
"state": "CA",
"postal_code": "10618",
"line_1": "66993 Shelton Fork",
"line_2": "Suite 360",
"livemode": false,
"type": "shipping"
},
"metadata": {},
"cart_data": null
},
"object": "dispute",
"created": 1781115876,
"updated": 1781115876,
"display_status": "under_review",
"reason": {
"code": null,
"description": null,
"category": null
}
}
Create dispute document
Upload a document as evidence for a dispute. Accepts a single PDF file up to 2MB. Document types: shipping_documentation, supporting_file, customer_signature, customer_communication.
Path parameters
Dispute ID
Returns
Document uploaded successfully and associated with the dispute.
curl --request POST \
--url https://api.framepayments.com/v1/disputes/a70cd72f-e74a-40f2-96a2-3f60714aac4a/documents \
--header 'Authorization: Bearer API_KEY'
{
"message": "Document uploaded successfully",
"document_type": "supporting_file",
"filename": "evidence.pdf"
}