Sign in

v1

latestOpenAPI 3.0.0Forter License2026-07-1333204516.7 KB
Disputes

Dispute

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.

post/v2/claims

Headers

api-versionstring required
Example:10.1

Specify the version of the API to target.

x-forter-siteidstring required
Example:a1b2c3d4e5f6

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

Authorizationstring required
Example:Basic <base64-encoded-api-key:>

Basic Authentiation in the form of a username and password. Use the API Key as the username and leave the password empty.

Request body

chargeIdstring nullable

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

commentsstring nullable

Additional comments by the merchant

dueDatestring date required

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. The expected date timezone is UTC.

externalClaimStatusstring nullable

Detailed claim status in the claim source system

goodsRecoveredboolean nullable

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

invoiceURLstring nullable

url to a copy of the invoice sent to the customer

issueDatestring date required

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

orderIdstring nullable

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.

originalPayloadobject nullable

General payload object

processorChargebackCaseIdstring nullable

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

processorName'Adyen' | 'Airwallex' | 'AmazonPay' | 'AMEX' | 'AuthorizeNet' | 'Be2bill' | 'BlueSnap' | 'Braintree' | 'BusinessTrack' | 'Chase' | 'Checkout' | 'Citcon' | 'Citibank' | 'ConcoraCredit' | 'Credorax' | 'Cybersource' | 'Dalenys' | 'Discover' | 'Dlocal' | 'Ebanx' | 'Elavon' | 'Fidelity' | 'FirstData' | 'Fiserv' | 'Fortis' | 'Globalpay' | 'Ingenico' | 'IQ' | 'Klarna' | 'MCP' | 'MerchantConnect' | 'Merlink' | 'MidTrans' | 'NCR' | 'Nuvei' | 'OceanPay' | 'OmniPayGroup' | 'Paymentech' | 'Paymenttech' | 'PayPal' | 'PayPlus' | 'PaySafe' | 'PayU' | 'PayUEastEurope' | 'PayULatam' | 'Privvy' | 'Przelewy' | 'Revolut' | 'Safecharge' | 'Shift4' | 'Shopify' | 'Sofort' | 'Sprint' | 'Square' | 'Stripe' | 'Vantiv' | 'Wirecard' | 'Worldline' | 'Worldnet' | 'WorldpayAccertify' | 'WorldpayDisputes' | 'WorldpayMAI' | 'WorldpayWDP' | 'Xendit' | 'Zen' nullable

Payment processor name.

reasonstring nullable

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

reasonCodestring nullable

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

reasonType'FRAUD' | 'SERVICE' | 'OTHER' | 'AUTHORIZATION' | 'PROCESSING_ERROR' required

The claim reason category type.

sourceDetailsstring nullable

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

sourceType'PROCESSOR_CB' | 'AMEX' | 'DISCOVER' | 'PAYPAL' | 'PROCESSOR_INQUIRY' | 'CUSTOMER_SUPPORT' | 'SHIPPING_CARRIER' | 'THIRD_PARTY' | 'FORTER' | 'OTHER' required

The category of the source of the claim.

status'OPEN' | 'IN_DISPUTE' | 'WON' | 'LOST' | 'CANCELED' required

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

type'CHARGEBACK' | 'PRE_CHARGEBACK' | 'DEBIT_MEMO' | 'REQUEST_FOR_INFORMATION' | 'FRAUD_ALERT' required

Type of claim.

wasRefundedboolean nullable

Relevant only for the prechargeback claim type. Indication of whether or not the buyer was refunded

Example request

{
  "additionalCost": {
    "amountLocalCurrency": "105.55",
    "amountUSD": "99.95",
    "currency": "CAD"
  },
  "amount": {
    "amountLocalCurrency": "105.55",
    "amountUSD": "99.95",
    "currency": "CAD"
  },
  "chargeId": "111111111",
  "chargebackShippingInfo": {
    "additionalShippingInfo": "PO Box 3297",
    "carrier": "UPS",
    "proofOfShippingURL": "true",
    "signedProofOfShipping": true,
    "trackingNumber": "123456"
  },
  "comments": "Contacted customer via phone",
  "dueDate": "2016-01-30",
  "externalClaimStatus": "pending merchant response",
  "invoiceURL": "mystore.com/invoices/abc123",
  "issueDate": "2016-01-20",
  "orderId": "4306795",
  "processorChargebackCaseId": "CB-4343343219",
  "processorName": "Braintree",
  "reason": "Fraudulent Transaction: Card Not Present Environment",
  "reasonCode": "83",
  "reasonType": "FRAUD",
  "sourceDetails": "UPS",
  "sourceType": "PROCESSOR_CB",
  "status": "OPEN",
  "type": "CHARGEBACK"
}

Response

Example claimResponse

messagestring required

The message containing status response text

statusstring required

Status of the request processing

Example response

{
  "message": "Claim received",
  "status": "success"
}