--- title: Dispute slug: reference/dispute docTags: createdAt: 2026-08-23T06:01:06.452Z --- { "id": "jPpJtkAMpZMKg3ApIw9_S", "type": "api-oas-v2", "data": { "method": "POST", "url": "https://api.forter-secure.com/v2/claims", "servers": [ { "url": "https://api.forter-secure.com/v2/claims" } ], "name": "Dispute", "description": "

Inform of a dispute initiated by a customer. This endpoint should be used to report any disputes not already reported via webhook from the payment processor. While no decision is provided on this request, it is a required input that both improves the decision model and enables chargeback recovery.

", "contentType": "application/json", "request": { "pathParameters": [], "headerParameters": [ { "name": "accept", "type": "string", "kind": "optional", "description": "Generated from available response content types", "enum": [ "application/json" ], "default": "application/json" }, { "kind": "required", "name": "api-version", "type": "string", "example": "10.3", "description": "Specify the version of the API to target." }, { "kind": "required", "name": "x-forter-siteid", "type": "string", "example": "a1b2c3d4e5f6", "description": "

Forter-assigned ID for your account. Note that your Site ID for your test site is different from your production site.

" } ], "queryParameters": [], "bodyDataParameters": [ { "kind": "required", "name": "body", "type": "object", "description": "

Inform of a dispute initiated by a customer. This endpoint should be used to report any disputes not already reported via webhook from the payment processor. While no decision is provided on this request, it is a required input that both improves the decision model and enables chargeback recovery.

", "customType": "claimRequest", "schema": [ { "name": "additionalCost", "kind": "required", "type": "object", "description": "Additional fees associated with the claim such as processor fees or shipping recovery fees.", "modelRef": "#/components/schemas/Amount", "customType": "Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] }, { "name": "amount", "kind": "required", "type": "object", "description": "The amount representing the value of the goods that were not retrieved.", "modelRef": "#/components/schemas/Amount", "customType": "Amount", "schema": [ { "name": "amountLocalCurrency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in currency chosen by the buyer", "example": "105.55", "maxLength": 20 }, { "name": "amountUSD", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nTransaction amount in USD", "example": "99.95", "maxLength": 12 }, { "name": "currency", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Transaction currency chosen by the buyer, 3-letter ISO-4217 format currency code

", "example": "CAD", "maxLength": 3, "pattern": "[A-Z]{3}" } ] }, { "name": "chargeId", "kind": "optional", "type": "string", "nullable": true, "description": "

The unique identifier of the payment, such as Acquirer Reference Number (ARN).

", "example": "111111111", "maxLength": 100 }, { "name": "chargebackShippingInfo", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "ChargebackShippingInfo", "description": "", "modelRef": "#/components/schemas/ChargebackShippingInfo", "schema": [ { "name": "additionalShippingInfo", "kind": "optional", "type": "string", "nullable": true, "description": "Aditional identification document details and verification", "example": "PO Box 3297", "maxLength": 100 }, { "name": "carrier", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nShipping carrier name", "example": "UPS", "maxLength": 50 }, { "name": "proofOfShippingURL", "kind": "optional", "type": "string", "nullable": true, "description": "URL to the proof of shipping in the merchant's system", "example": "true", "maxLength": 1024 }, { "name": "signedProofOfShipping", "kind": "optional", "type": "boolean", "nullable": true, "description": "Whether the user has signed a proof of shipping", "example": true }, { "name": "trackingNumber", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nOrder tracking number", "example": "123456", "maxLength": 50 } ] } ], "schema": [] }, { "name": "comments", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nAdditional comments by the merchant", "example": "Contacted customer via phone", "maxLength": 255 }, { "name": "dueDate", "kind": "required", "type": "string", "description": "

Due date for disputing the claim which was stated by the processor in case of a chargeback. Otherwise, the issue date. Use YYYY-MM-DD format.\nThe expected date timezone is UTC.

", "example": "2016-01-30", "format": "date" }, { "name": "externalClaimStatus", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nDetailed claim status in the claim source system", "example": "pending merchant response", "maxLength": 100 }, { "name": "goodsRecovered", "kind": "optional", "type": "boolean", "conditional": true, "nullable": true, "description": "Conditional.\n

Relevant only for the prechargeback claim type, in case the goods were not sent or delivered yet. Indication of whether or not the goods were recovered

", "example": false }, { "name": "invoiceURL", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\nurl to a copy of the invoice sent to the customer", "example": "mystore.com/invoices/abc123", "maxLength": 1024 }, { "name": "issueDate", "kind": "required", "type": "string", "description": "

Date the chargeback was issued / the prechargeback notification was sent. Use YYYY-MM-DD format.\nThe expected date timezone is UTC.

", "example": "2016-01-20", "format": "date" }, { "name": "orderId", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Unique order/transaction identifier. Should match the order id sent to Forter at checkout. Note that Forter treats this ID as case-insensitive; Order123 and ORDER123 will be identified as the same order.

", "example": "4306795", "maxLength": 40 }, { "name": "originalPayload", "kind": "optional", "type": "object", "description": "", "complexType": "allOf", "complexItems": [ { "name": "GeneralPayloadMap", "description": "", "modelRef": "#/components/schemas/GeneralPayloadMap", "schema": [] } ], "schema": [] }, { "name": "processorChargebackCaseId", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

The case number from the payment processor. (for BrainTree, please map the disputeId instead of caseNumber)

", "example": "CB-4343343219", "maxLength": 75 }, { "name": "processorName", "kind": "optional", "type": "string", "nullable": true, "description": "Payment processor name.", "example": "Braintree", "enum": [ "Adyen", "Airwallex", "AmazonPay", "AMEX", "AuthorizeNet", "Be2bill", "BlueSnap", "Braintree", "BusinessTrack", "Chase", "Checkout", "Citcon", "Citibank", "ConcoraCredit", "Credorax", "Cybersource", "Dalenys", "Discover", "Dlocal", "Ebanx", "Elavon", "emerchantpay", "Fidelity", "FirstData", "Fiserv", "Fortis", "FreedomPay", "Globalpay", "Ingenico", "IQ", "Klarna", "MCP", "MerchantConnect", "Merlink", "MidTrans", "NCR", "Nuvei", "OceanPay", "OmniPayGroup", "Paymentech", "Paymenttech", "PayPal", "PayPlus", "PaySafe", "PayU", "PayUEastEurope", "PayULatam", "Privvy", "Przelewy", "RazorPay", "Revolut", "Safecharge", "Shift4", "Shopify", "Sofort", "Sprint", "Square", "Stripe", "Vantiv", "Wirecard", "Worldline", "Worldnet", "WorldpayAccertify", "WorldpayDisputes", "WorldpayMAI", "Xendit", "Zen" ], "maxLength": 50 }, { "name": "reason", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

The claim reason as supplied by the claim source. For example, the chargeback reason provided in the chargeback notification.

", "example": "Fraudulent Transaction: Card Not Present Environment", "maxLength": 100 }, { "name": "reasonCode", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

The claim code as supplied by the claim source. For example, the chargeback reason provided in the chargeback notification.

", "example": "83", "maxLength": 50 }, { "name": "reasonType", "kind": "required", "type": "string", "description": "The claim reason category type.", "example": "FRAUD", "enum": [ "FRAUD", "SERVICE", "OTHER", "AUTHORIZATION", "PROCESSING_ERROR" ] }, { "name": "sourceDetails", "kind": "optional", "type": "string", "conditional": true, "nullable": true, "description": "Conditional.\n

Specifics about the source of the claim such as the processor name / 3rd party name, etc.

", "example": "UPS" }, { "name": "sourceType", "kind": "required", "type": "string", "description": "The category of the source of the claim.", "example": "PROCESSOR_CB", "enum": [ "PROCESSOR_CB", "AMEX", "DISCOVER", "PAYPAL", "PROCESSOR_INQUIRY", "CUSTOMER_SUPPORT", "SHIPPING_CARRIER", "THIRD_PARTY", "FORTER", "OTHER" ] }, { "name": "status", "kind": "required", "type": "string", "description": "

Claim status mapping from the current status of the claim. For example, a mapping of the processor chargeback dispute status.

", "example": "OPEN", "enum": [ "OPEN", "IN_DISPUTE", "WON", "LOST", "CANCELED" ] }, { "name": "type", "kind": "required", "type": "string", "description": "Type of claim.", "example": "CHARGEBACK", "enum": [ "CHARGEBACK", "PRE_CHARGEBACK", "DEBIT_MEMO", "REQUEST_FOR_INFORMATION", "FRAUD_ALERT" ] }, { "name": "wasRefunded", "kind": "optional", "type": "boolean", "conditional": true, "nullable": true, "description": "Conditional.\nRelevant only for the prechargeback claim type. Indication of whether or not the buyer was refunded", "example": false } ], "modelRef": "#/components/schemas/claimRequest", "isExpanded": true } ], "formDataParameters": [], "oAuthParameters": [ { "id": "basicAuth", "name": "basicAuth", "kind": "optional", "type": "http", "scheme": "basic" } ], "cookieParameters": [] }, "responses": [ { "statusCode": "200", "description": "Example claimResponse", "jsonExample": "", "isExpanded": true, "schema": [ { "kind": "optional", "type": "object", "description": "The response object following claims request to the system", "customType": "claimResponse", "schema": [ { "name": "message", "kind": "required", "type": "string", "description": "The message containing status response text", "example": "Claim received", "maxLength": 1000 }, { "name": "status", "kind": "required", "type": "string", "description": "Status of the request processing", "example": "success", "maxLength": 50 } ], "modelRef": "#/components/schemas/claimResponse", "isExpanded": true } ] }, { "statusCode": "400", "description": "

Bad Request (Often missing a required parameter)

", "jsonExample": "", "isExpanded": true }, { "statusCode": "401", "description": "

Unauthorized (No valid API key provided)

", "jsonExample": "", "isExpanded": true }, { "statusCode": "404", "description": "

Not Found (The requested item doesn't exist)

", "jsonExample": "", "isExpanded": true }, { "statusCode": "500", "description": "

Server Error (Something went wrong on Forter's end)

", "jsonExample": "", "isExpanded": true } ], "hasXCodeSamples": false, "examples": { "languages": [ { "id": "w2rn8XuUXzUqFmaOUa0Wi", "language": "curl", "label": "cURL", "code": "curl --request POST \\\n --url https://api.forter-secure.com/v2/claims \\\n --header 'accept: application/json' \\\n --header 'content-type: application/json' \\\n --header 'api-version: 10.3' \\\n --header 'x-forter-siteid: a1b2c3d4e5f6' \\\n --data '{\n \"additionalCost\": {},\n \"amount\": {},\n \"chargebackShippingInfo\": {},\n \"dueDate\": \"2016-01-30\",\n \"issueDate\": \"2016-01-20\",\n \"originalPayload\": {},\n \"reasonType\": \"FRAUD\",\n \"sourceType\": \"PROCESSOR_CB\",\n \"status\": \"OPEN\",\n \"type\": \"CHARGEBACK\"\n }'" }, { "id": "fJhNKvXj7CO-qXKXSjW7z", "language": "javascript", "label": "javascript", "code": "var myHeaders = new Headers();\nmyHeaders.append(\"accept\", \"application/json\");\nmyHeaders.append(\"content-type\", \"application/json\");\nmyHeaders.append(\"api-version\", \"10.3\");\nmyHeaders.append(\"x-forter-siteid\", \"a1b2c3d4e5f6\");\n\nvar raw = JSON.stringify({\n \"additionalCost\": {},\n \"amount\": {},\n \"chargebackShippingInfo\": {},\n \"dueDate\": \"2016-01-30\",\n \"issueDate\": \"2016-01-20\",\n \"originalPayload\": {},\n \"reasonType\": \"FRAUD\",\n \"sourceType\": \"PROCESSOR_CB\",\n \"status\": \"OPEN\",\n \"type\": \"CHARGEBACK\"\n});\n\nvar requestOptions = {\n method: 'POST',\n headers: myHeaders,\n body: raw,\n redirect: 'follow'\n};\n\nfetch(\"https://api.forter-secure.com/v2/claims\", requestOptions)\n .then(response => response.text())\n .then(result => console.log(result))\n .catch(error => console.log('error', error));" }, { "id": "mbPrlwNyK4AhJTcXVLw5y", "language": "ruby", "label": "Ruby", "code": "require \"uri\"\nrequire \"json\"\nrequire \"net/http\"\n\nurl = URI(\"https://api.forter-secure.com/v2/claims\")\n\nhttps = Net::HTTP.new(url.host, url.port)\nhttps.use_ssl = true\n\nrequest = Net::HTTP::Post.new(url)\nrequest[\"accept\"] = \"application/json\"\nrequest[\"content-type\"] = \"application/json\"\nrequest[\"api-version\"] = \"10.3\"\nrequest[\"x-forter-siteid\"] = \"a1b2c3d4e5f6\"\nrequest.body = JSON.dump({\n \"additionalCost\": {},\n \"amount\": {},\n \"chargebackShippingInfo\": {},\n \"dueDate\": \"2016-01-30\",\n \"issueDate\": \"2016-01-20\",\n \"originalPayload\": {},\n \"reasonType\": \"FRAUD\",\n \"sourceType\": \"PROCESSOR_CB\",\n \"status\": \"OPEN\",\n \"type\": \"CHARGEBACK\"\n})\n\nresponse = https.request(request)\nputs response.read_body\n" }, { "id": "yzZ7uqJdkE9uqvIg9CMHE", "language": "python", "label": "Python", "code": "import requests\nimport json\n\nurl = \"https://api.forter-secure.com/v2/claims\"\n\npayload = json.dumps({\n \"additionalCost\": {},\n \"amount\": {},\n \"chargebackShippingInfo\": {},\n \"dueDate\": \"2016-01-30\",\n \"issueDate\": \"2016-01-20\",\n \"originalPayload\": {},\n \"reasonType\": \"FRAUD\",\n \"sourceType\": \"PROCESSOR_CB\",\n \"status\": \"OPEN\",\n \"type\": \"CHARGEBACK\"\n})\nheaders = {\n 'accept': 'application/json',\n 'content-type': 'application/json',\n 'api-version': '10.3',\n 'x-forter-siteid': 'a1b2c3d4e5f6'\n}\n\nresponse = requests.request(\"POST\", url, headers=headers, data=payload)\n\nprint(response.text)\n" } ], "selectedLanguageId": "w2rn8XuUXzUqFmaOUa0Wi" }, "results": { "languages": [ { "id": "zfYEX2tFipoQlz9Y_oDKl", "language": "200", "code": "// Example claimResponse\n{\n \"message\": \"Claim received\",\n \"status\": \"success\"\n}" }, { "id": "pohqkfy1W8nnJyKQ5axDW", "language": "400", "code": "// Bad Request (Often missing a required parameter)\n" }, { "id": "E7_i84fMNXZY0arKmbcF8", "language": "401", "code": "// Unauthorized (No valid API key provided)\n" }, { "id": "fVqhFdJa8UDGyYhceGquy", "language": "404", "code": "// Not Found (The requested item doesn't exist)\n" }, { "id": "4d-_geR_yNyxJZ7ovDYBM", "language": "500", "code": "// Server Error (Something went wrong on Forter's end)\n" } ], "selectedLanguageId": "zfYEX2tFipoQlz9Y_oDKl" } }, "children": [ { "text": "" } ] }