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

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/2027Q1/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": [ … ]
    }
  ]
}