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.

ENDPOINTS

GET/v1/disputes GET/v1/disputes/{id}PATCH/v1/disputes/{id}POST/v1/disputes/{id}/documents

export FRAME_API_KEY='sk_sandbox_...'

The Dispute object

Attributes

idstring

Unique identifier for the dispute.

statusstring

Current dispute status. Possible values include received, warning_needs_response, warning_under_review, warning_closed, needs_response, under_review, won, and lost.

display_statusstring

Human-readable status for display in dashboards.

amount_centsinteger

Disputed amount in the smallest currency unit (e.g. cents for USD).

amount_currencystring

Three-letter ISO currency code (uppercase) for the disputed amount.

reasondictionary

Reason given by the cardholder for the dispute. Fields may be null until the issuer reports them.

acquirer_reference_numbernullable string

Reference number assigned by the acquirer for tracking.

authorization_codenullable string

Authorization code from the original transaction.

charge_intentdictionary

livemodeboolean

true if live mode, false if test mode.

updatedinteger

Unix timestamp of last update.

THE DISPUTE OBJECT

{
  "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_id": "cus_1a2b3c",
    "customer": {},
    "account_id": null,
    "account": {},
    "payment_method": {},
    "subscription": null,
    "invoice": null,
    "latest_charge": {},
    "shipping": null,
    "metadata": {},
    "revenue_split": null
  },
  "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

pageintegeroptional

The page offset at which you'd like to resume fetching data.

per_pageintegeroptional

A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 10.

chargestringoptional

Only return disputes associated to the charge specified by this charge ID.

charge_intentstringoptional

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.

GET/v1/disputes

curl --request GET \
  --url https://api.framepayments.com/v1/disputes \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "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

idstringrequired

The ID of the dispute to retrieve.

Returns

Returns a dispute object if a valid dispute ID was provided.

GET/v1/disputes/{id}

curl --request GET \
  --url https://api.framepayments.com/v1/disputes/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "received",
  "amount_currency": "USD",
  "amount_cents": 1000,
  "livemode": false,
  "acquirer_reference_number": null,
  "authorization_code": null,
  "charge_intent": {
    "id": "00000000-0000-4000-8000-000000000002",
    "currency": "usd",
    "client_secret": "ci_00000000-0000-4000-8000-000000000002_secret_000000000000000000000001",
    "status": "pending",
    "description": null,
    "authorization_mode": "automatic",
    "failure_description": null,
    "reference_id": null,
    "object": "charge_intent",
    "amount": 1000,
    "amount_captured": 0,
    "amount_voided": 0,
    "created": 1745107200,
    "livemode": false,
    "subscription": null,
    "invoice": null,
    "latest_charge": {
      "id": "00000000-0000-4000-8000-000000000003",
      "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": "00000000-0000-4000-8000-000000000004",
        "customer_id": null,
        "account_id": null,
        "billing": {
          "id": "00000000-0000-4000-8000-000000000005",
          "city": "South Angelika",
          "country": "US",
          "state": "CA",
          "postal_code": "84767",
          "line_1": "9382 Corwin Prairie",
          "line_2": "Apt. 973",
          "livemode": false,
          "type": "billing"
        },
        "type": "card",
        "object": "payment_method",
        "created": 1745107200,
        "updated": 1745107200,
        "livemode": false,
        "status": "active",
        "card": {
          "brand": "visa",
          "exp_month": "07",
          "exp_year": "30",
          "issuer": null,
          "currency": null,
          "segment": null,
          "type": null,
          "last_four": "4242"
        }
      },
      "customer": "00000000-0000-4000-8000-000000000006",
      "account": null,
      "account_id": null,
      "payment_method": "00000000-0000-4000-8000-000000000004",
      "amount": 1000,
      "amount_captured": 0,
      "amount_refunded": 0,
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "captured": true,
      "disputed": false,
      "charge_intent": "00000000-0000-4000-8000-000000000002",
      "refunded": false,
      "net_amount": 926
    },
    "customer": {
      "id": "00000000-0000-4000-8000-000000000006",
      "name": "Marvel Denesik",
      "email": "customer@frame.com",
      "description": "adipisci",
      "status": "active",
      "date_of_birth": null,
      "phone": "+13107484186",
      "billing_address": null,
      "shipping_address": null,
      "object": "customer",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "metadata": {}
    },
    "customer_id": "00000000-0000-4000-8000-000000000006",
    "account_id": null,
    "account": null,
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000004",
      "customer_id": null,
      "account_id": null,
      "billing": {
        "id": "00000000-0000-4000-8000-000000000005",
        "city": "South Angelika",
        "country": "US",
        "state": "CA",
        "postal_code": "84767",
        "line_1": "9382 Corwin Prairie",
        "line_2": "Apt. 973",
        "livemode": false,
        "type": "billing"
      },
      "type": "card",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "07",
        "exp_year": "30",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242"
      }
    },
    "shipping": {
      "id": "00000000-0000-4000-8000-000000000007",
      "city": "Thompsonville",
      "country": "US",
      "state": "CA",
      "postal_code": "12238-1036",
      "line_1": "547 Randell Circle",
      "line_2": "Suite 976",
      "livemode": false,
      "type": "shipping"
    },
    "metadata": {},
    "cart_data": null
  },
  "object": "dispute",
  "created": 1745107200,
  "updated": 1745107200,
  "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

idstringrequired

The ID of the dispute to update.

Body parameters

shipping_carrierstringoptional

shipping_datestringoptional

shipping_tracking_numberstringoptional

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.

customer_purchase_ip_addressstringoptional

The IP address that the customer used when making the purchase.

support_descriptionstringoptional

refund_refusal_explanationstringoptional

refund_policystringoptional

Documentation demonstrating that the customer was shown your refund policy prior to purchase.

access_activity_logstringoptional

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.

PATCH/v1/disputes/{id}

curl --request PATCH \
  --url https://api.framepayments.com/v1/disputes/a70cd72f-e74a-40f2-96a2-3f60714aac4a \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "id": "00000000-0000-4000-8000-000000000001",
  "status": "received",
  "amount_currency": "USD",
  "amount_cents": 1000,
  "livemode": false,
  "acquirer_reference_number": null,
  "authorization_code": null,
  "charge_intent": {
    "id": "00000000-0000-4000-8000-000000000002",
    "currency": "usd",
    "client_secret": "ci_00000000-0000-4000-8000-000000000002_secret_000000000000000000000001",
    "status": "pending",
    "description": null,
    "authorization_mode": "automatic",
    "failure_description": null,
    "reference_id": null,
    "object": "charge_intent",
    "amount": 1000,
    "amount_captured": 0,
    "amount_voided": 0,
    "created": 1745107200,
    "livemode": false,
    "subscription": null,
    "invoice": null,
    "latest_charge": {
      "id": "00000000-0000-4000-8000-000000000003",
      "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": "00000000-0000-4000-8000-000000000004",
        "customer_id": null,
        "account_id": null,
        "billing": {
          "id": "00000000-0000-4000-8000-000000000005",
          "city": "Beattyfort",
          "country": "US",
          "state": "CA",
          "postal_code": "43099",
          "line_1": "134 Halvorson Lane",
          "line_2": "Suite 918",
          "livemode": false,
          "type": "billing"
        },
        "type": "card",
        "object": "payment_method",
        "created": 1745107200,
        "updated": 1745107200,
        "livemode": false,
        "status": "active",
        "card": {
          "brand": "visa",
          "exp_month": "04",
          "exp_year": "30",
          "issuer": null,
          "currency": null,
          "segment": null,
          "type": null,
          "last_four": "4242"
        }
      },
      "customer": "00000000-0000-4000-8000-000000000006",
      "account": null,
      "account_id": null,
      "payment_method": "00000000-0000-4000-8000-000000000004",
      "amount": 1000,
      "amount_captured": 0,
      "amount_refunded": 0,
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "captured": true,
      "disputed": false,
      "charge_intent": "00000000-0000-4000-8000-000000000002",
      "refunded": false,
      "net_amount": 926
    },
    "customer": {
      "id": "00000000-0000-4000-8000-000000000006",
      "name": "Onie Nicolas",
      "email": "customer@frame.com",
      "description": "sed",
      "status": "active",
      "date_of_birth": null,
      "phone": "+13107484186",
      "billing_address": null,
      "shipping_address": null,
      "object": "customer",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "metadata": {}
    },
    "customer_id": "00000000-0000-4000-8000-000000000006",
    "account_id": null,
    "account": null,
    "payment_method": {
      "id": "00000000-0000-4000-8000-000000000004",
      "customer_id": null,
      "account_id": null,
      "billing": {
        "id": "00000000-0000-4000-8000-000000000005",
        "city": "Beattyfort",
        "country": "US",
        "state": "CA",
        "postal_code": "43099",
        "line_1": "134 Halvorson Lane",
        "line_2": "Suite 918",
        "livemode": false,
        "type": "billing"
      },
      "type": "card",
      "object": "payment_method",
      "created": 1745107200,
      "updated": 1745107200,
      "livemode": false,
      "status": "active",
      "card": {
        "brand": "visa",
        "exp_month": "04",
        "exp_year": "30",
        "issuer": null,
        "currency": null,
        "segment": null,
        "type": null,
        "last_four": "4242"
      }
    },
    "shipping": {
      "id": "00000000-0000-4000-8000-000000000007",
      "city": "Marioborough",
      "country": "US",
      "state": "CA",
      "postal_code": "50493-8685",
      "line_1": "800 Debby Knolls",
      "line_2": "Apt. 226",
      "livemode": false,
      "type": "shipping"
    },
    "metadata": {},
    "cart_data": null
  },
  "object": "dispute",
  "created": 1745107200,
  "updated": 1745107200,
  "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

idstringrequired

Dispute ID

Returns

Document uploaded successfully and associated with the dispute.

POST/v1/disputes/{id}/documents

curl --request POST \
  --url https://api.framepayments.com/v1/disputes/a70cd72f-e74a-40f2-96a2-3f60714aac4a/documents \
  --header 'Authorization: Bearer API_KEY'

RESPONSE

{
  "message": "Document uploaded successfully",
  "document_type": "supporting_file",
  "filename": "evidence.pdf"
}