Skip to content

Submit dispute

Request

Submit a dispute for a card transaction.

The request body structure varies per dispute reason code. All reasons share a common structure with transaction, form, disclaimer, and files objects, but the fields within form and files differ per reason.

For per-reason request body details, see the disputes via API guide.

Security
UserToken
Path
profileIdinteger, (int64)required

Your profile ID.

Example:14547572
schemestringrequired

The network of the card that was used to make this transaction.

Enum:"MASTERCARD""VISA"
Example:VISA
reasonstringrequired

Dispute reason code supplied by the dispute reasons endpoint.

Example:WRONG_AMOUNT
Headers
X-External-Correlation-Idstring, (uuid), <= 36 characters

Optional UUID for correlating requests across systems. If provided, Wise echoes it back in the response. Maximum 36 characters. Learn more.

Example:f47ac10b-58cc-4372-a567-0e02b2c3d479
Bodyapplication/jsonrequired
transactionobject

Transaction details for the dispute.

formobject

Form fields required to submit this dispute. The specific fields vary per reason code.

See the disputes via API guide for per-reason field details.

disclaimerobject

Acknowledgement fields.

filesobject

Key-value pairs mapping file field names to file IDs obtained from the file upload endpoint. Available file fields vary per reason code.

curl -i -X POST \
  https://api.wise.com/2026Q3/spend/profiles/14547572/dispute-form/flows/VISA/WRONG_AMOUNT \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-External-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -d '{
    "transaction": {
      "transactionId": "12345",
      "email": "support@partner.com"
    },
    "form": {
      "charged": {
        "value": 50,
        "currency": "EUR"
      },
      "expected": {
        "value": 5,
        "currency": "EUR"
      },
      "agreedDetails": {
        "agreed": true,
        "agreedReason": "some reason"
      },
      "goods": "something",
      "details": "wrong amount dispute"
    },
    "disclaimer": {
      "allAnswered": true,
      "filesUploaded": true
    }
  }'

Responses

Dynamic Flow JSON response. If using the Dynamic Flow framework, pass this to the framework. If using the API directly, the response can be ignored.

Headers
X-External-Correlation-Idstring, (uuid), <= 36 characters

Echoed back when X-External-Correlation-Id was included in the request. Learn more.

Example:"f47ac10b-58cc-4372-a567-0e02b2c3d479"
x-trace-idstring

Unique trace identifier assigned by Wise. Useful when contacting support about a specific request.

Example:"fba501b6d453b96789f52338f019341f"
Bodyapplication/json
object

Dynamic Flow JSON object.

Response
{
  "key": "final",
  "type": "form",
  "title": "Done!",
  "actions": [
    {
      "title": "Continue",
      "exit": true,
      "$id": "continue"
    }
  ],
  "schemas": [],
  "layout": [
    {
      "width": "md",
      "components": [ … ],
      "type": "box"
    },
    {
      "margin": "lg",
      "align": "center",
      "type": "info",
      "markdown": "Thanks for reporting this transaction. It's pre-authorised right now, but as soon as it becomes \"spent\" we'll begin our investigation."
    },
    {
      "type": "button",
      "action": { … }
    }
  ]
}