Skip to content

Disputes

Raise and manage card transaction disputes, including submission via Dynamic Flow or direct API, file uploads, and dispute lifecycle tracking.

For implementation details, see:

Dispute sub-statuses

The possible subStatus values are:

  • SUBMITTED — Initial status
  • IN_REVIEW — The dispute is under review or requires additional information
  • REFUNDED — The refund has been processed
  • REJECTED — The dispute is invalid
  • WITHDRAWN — The customer has withdrawn the dispute
  • CONFIRMED — The dispute has been reviewed but a refund is not applicable
  • REFUND_IN_PROGRESS — A refund is being processed
  • ATTEMPTING_RECOVERY — A chargeback request has been submitted
  • RECOVERY_UNSUCCESSFUL — The chargeback attempt was unsuccessful

The status transition diagram may undergo modifications in the future and only covers regular pathways.

Dispute statuses transition diagram
Operations
Webhooks

Dispute dynamic flow entry point

Request

Retrieves the JSON for initiating the dispute flow. Use this endpoint with Wise's Dynamic Flow framework.

The JSON response must be passed into the Dynamic Flow framework, which handles the multi-step dispute submission including the generation of subsequent pages and the creation of the dispute.

Setting up the API

You will need to implement a GET API with the following format: GET https://{{yourApiUrl}}/v3/spend/profiles/{{profileId}}/dispute-form/flows/step/{{scheme}}/{{reason}}?transactionId={{transactionId}}

This API should forward the call to: POST https://{{wiseUrl}}/v3/spend/profiles/{{profileId}}/dispute-form/flows/step/{{scheme}}/{{reason}}?transactionId={{transactionId}}

This is required as the dynamic flow returned by Wise will automatically be configured to call your GET API. Use baseUrl or fetcher as part of the dynamic flow setup to redirect the Dynamic Flow JavaScript library to your domain.

For a full integration guide, including example backend implementation and styling, see Disputes via Dynamic Flow.

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:TROUBLE_WITH_GOODS_SERVICES
Query
transactionIdstringrequired

The ID of the transaction being disputed. Can be a comma-separated list of IDs if the reason code has the supportsMultipleTransactions flag.

Example:transactionId=6789
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
emailstring

Email used to receive communications regarding the dispute from Wise (e.g. your support team's email).

Example:"support@partner.com"
curl -i -X POST \
  'https://api.wise.com/2026Q3/spend/profiles/14547572/dispute-form/flows/step/VISA/TROUBLE_WITH_GOODS_SERVICES?transactionId=6789' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-External-Correlation-Id: f47ac10b-58cc-4372-a567-0e02b2c3d479' \
  -d '{
    "email": "support@partner.com"
  }'

Responses

Returns information required to populate the form with the correct information. Note how the action field contains the URL and method to the next step.

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. Pass this to the Dynamic Flow framework to render the dispute form.

Response
{
  "key": "TROUBLE_WITH_GOODS_SERVICES",
  "type": "form",
  "title": "There's a problem with the goods or service I ordered",
  "actions": [],
  "schemas": [],
  "layout": [
    {
      "type": "decision",
      "options": [ … ]
    }
  ]
}